1pki(n) public key encryption pki(n)
2______________________________________________________________________________
6
8 pki - Implementation of the public key cipher
9
11 package require Tcl 8.5
12 package require pki ?0.10?
14 ::pki::encrypt ?-binary? ?-hex? ?-pad? ?-nopad? ?-priv? ?-pub? ?--? in‐
16 put key
17 ::pki::decrypt ?-binary? ?-hex? ?-unpad? ?-nounpad? ?-priv? ?-pub? ?--?
19 input key
20 ::pki::sign input key ?algo?
22 ::pki::verify signedmessage plaintext key ?algo?
24 ::pki::key key ?password? ?encodePem?
26 ::pki::pkcs::parse_key key ?password?
28 ::pki::x509::parse_cert cert
30 ::pki::rsa::generate bitlength ?exponent?
32 ::pki::x509::verify_cert cert trustedcerts ?intermediatecerts?
34 ::pki::x509::validate_cert cert ?-sign_message dn_of_signer? ?-en‐
36 crypt_message dn_of_signer? ?-sign_cert dn_to_be_signed ca_depth? ?-ssl
37 dn?
38 ::pki::pkcs::create_csr keylist namelist ?encodePem? ?algo?
40 ::pki::pkcs::parse_csr csr
42 ::pki::x509::create_cert signreqlist cakeylist serial_number notBefore
44 notAfter isCA extensions ?encodePem? ?algo?
45______________________________________________________________________________
47
50 ::pki::encrypt ?-binary? ?-hex? ?-pad? ?-nopad? ?-priv? ?-pub? ?--? in‐
51 put key
52 Encrypt a message using PKI (probably RSA). Requires the caller
53 to specify either -priv to encrypt with the private key or -pub
54 to encrypt with the public key. The default option is to pad
55 and return in hex. One of -pub or -priv must be specified. The
56 -hex option causes the data to be returned in encoded as a hex‐
57 idecimal string, while the -binary option causes the data to be
58 returned as a binary string. If they are specified multiple
59 times, the last one specified is used. The -pad option causes
60 the data to be padded per PKCS#1 prior to being encrypted. The
61 -nopad inhibits this behaviour. If they are specified multiple
62 times, the last one specified is used. The input to encrypt is
63 specified as input. The key parameter, holding the key to use,
64 is a return value from either ::pki::pkcs::parse_key,
65 ::pki::x509::parse_cert, or ::pki::rsa::generate.
66 Mapping to OpenSSL's openssl application:
68 [1] "openssl rsautl -encrypt" == "::pki::encrypt -binary
70 -pub"
71 [2] "openssl rsautl -sign" == "::pki::encrypt -binary
73 -priv"
74 ::pki::decrypt ?-binary? ?-hex? ?-unpad? ?-nounpad? ?-priv? ?-pub? ?--?
76 input key
77 Decrypt a message using PKI (probably RSA). See ::pki::encrypt
78 for option handling.
79 Mapping to OpenSSL's openssl application:
81 [1] "openssl rsautl -decrypt" == "::pki::decrypt -binary
83 -priv"
84 [2] "openssl rsautl -verify" == "::pki::decrypt -binary
86 -pub"
87 ::pki::sign input key ?algo?
89 Digitally sign message input using the private key.
90 If algo is ommited "sha1" is assumed. Possible values for algo
92 include "md5", "sha1", "sha256", and "raw".
93 Specifying "raw" for algo will inhibit the building of an ASN.1
95 structure to encode which hashing algorithm was chosen. Atten‐
96 tion: In this case the corresponding pkgi::verify must be called
97 with algorithm information. Conversely, specifying a non-"raw"
98 algorithm here means that the corresponding pkgi::verify invoka‐
99 tion has to be made without algorithm information.
100 The input should be the plain text, hashing will be performed on
102 it.
103 The key should include the private key.
105 ::pki::verify signedmessage plaintext key ?algo?
107 Verify a digital signature using a public key. Returns true or
108 false.
109 Attention: The algorithm information algo has to be specified if
111 and only if the pki::sign which generated the signedmessage was
112 called with algorithm "raw". This inhibited the building of the
113 ASN.1 structure encoding the chosen hashing algorithm. Con‐
114 versely, if a proper algorithm was specified during signing then
115 you must not specify an algorithm here.
116 ::pki::key key ?password? ?encodePem?
118 Convert a key structure into a serialized PEM (default) or DER
119 encoded private key suitable for other applications. For RSA
120 keys this means PKCS#1.
121 ::pki::pkcs::parse_key key ?password?
123 Convert a PKCS#1 private key into a usable key, i.e. one which
124 can be used as argument for ::pki::encrypt, ::pki::decrypt,
125 ::pki::sign, and ::pki::verify.
126 ::pki::x509::parse_cert cert
128 Convert an X.509 certificate to a usable (public) key, i.e. one
129 which can be used as argument for ::pki:encrypt, ::pki::decrypt,
130 and ::pki::verify. The cert argument can be either PEM or DER
131 encoded.
132 ::pki::rsa::generate bitlength ?exponent?
134 Generate a new RSA key pair, the parts of which can be used as
135 argument for ::pki::encrypt, ::pki::decrypt, ::pki::sign, and
136 ::pki::verify. The bitlength argument is the length of the pub‐
137 lic key modulus. The exponent argument should generally not be
138 specified unless you really know what you are doing.
139 ::pki::x509::verify_cert cert trustedcerts ?intermediatecerts?
141 Verify that a trust can be found between the certificate speci‐
142 fied in the cert argument and one of the certificates specified
143 in the list of certificates in the trustedcerts argument.
144 (Eventually the chain can be through untrusted certificates
145 listed in the intermediatecerts argument, but this is currently
146 unimplemented). The certificates specified in the cert and
147 trustedcerts option should be parsed (from
148 ::pki::x509::parse_cert).
149 ::pki::x509::validate_cert cert ?-sign_message dn_of_signer? ?-en‐
151 crypt_message dn_of_signer? ?-sign_cert dn_to_be_signed ca_depth? ?-ssl
152 dn?
153 Validate that a certificate is valid to be used in some capac‐
154 ity. If multiple options are specified they must all be met for
155 this procedure to return "true". Currently, only the -sign_cert
156 option is functional. Arguments for the -sign_cert option are
157 dn_to_be_signed and ca_depth. The dn_to_be_signed is the dis‐
158 tinguished from the subject of a certificate to verify that the
159 certificate specified in the cert argument can sign. The
160 ca_depth argument is used to indicate at which depth the verifi‐
161 cation should be done at. Some certificates are limited to how
162 far down the chain they can be used to verify a given certifi‐
163 cate.
164 ::pki::pkcs::create_csr keylist namelist ?encodePem? ?algo?
166 Generate a certificate signing request from a key pair specified
167 in the keylist argument. The namelist argument is a list of
168 "name" followed by "value" pairs to encoding as the requested
169 distinguished name in the CSR. The encodePem option specifies
170 whether or not the result should be PEM encoded or DER encoded.
171 A "true" value results in the result being PEM encoded, while
172 any other value 9results in the the result being DER encoded.
173 DER encoding is the default. The algo argument specifies the
174 hashing algorithm we should use to sign this certificate signing
175 request with. The default is "sha1". Other possible values in‐
176 clude "md5" and "sha256".
177 ::pki::pkcs::parse_csr csr
179 Parse a Certificate Signing Request. The csr argument can be
180 either PEM or DER encoded.
181 ::pki::x509::create_cert signreqlist cakeylist serial_number notBefore
183 notAfter isCA extensions ?encodePem? ?algo?
184 Sign a signing request (usually from ::pki::pkcs::create_csr or
185 ::pki::pkcs::parse_csr) with a Certificate Authority (CA) cer‐
186 tificate. The signreqlist argument should be the parsed signing
187 request. The cakeylist argument should be the parsed CA cer‐
188 tificate. The serial_number argument should be a serial number
189 unique to this certificate from this certificate authority. The
190 notBefore and notAfter arguments should contain the time before
191 and after which (respectively) the certificate should be consid‐
192 ered invalid. The time should be encoded as something clock
193 format will accept (i.e., the results of clock seconds and clock
194 add). The isCA argument is a boolean argumen describing whether
195 or not the signed certificate should be a a CA certificate. If
196 specified as true the "id-ce-basicConstraints" extension is
197 added with the arguments of "critical" being true, "allowCA" be‐
198 ing true, and caDepth being -1 (infinite). The extensions argu‐
199 ment is a list of extensions and their parameters that should be
200 encoded into the created certificate. Currently only one ex‐
201 tension is understood ("id-ce-basicConstraints"). It accepts
202 three arguments critical allowCA caDepth. The critical argument
203 to this extension (and any extension) whether or not the valida‐
204 tor should reject the certificate as invalid if it does not un‐
205 derstand the extension (if set to "true") or should ignore the
206 extension (if set to "false"). The allowCA argument is used to
207 specify as a boolean value whether or not we can be used a cer‐
208 tificate authority (CA). The caDepth argument indicates how
209 many children CAs can be children of this CA in a depth-wise
210 fashion. A value of "0" for the caDepth argument means that
211 this CA cannot sign a CA certificate and have the result be
212 valid. A value of "-1" indicates infinite depth.
213
216 [1]
217
219 Roy Keene
220
222 This document, and the package it describes, will undoubtedly contain
223 bugs and other problems. Please report such in the category rsa of the
224 Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also
225 report any ideas for enhancements you may have for either package
226 and/or documentation.
227 When proposing code changes, please provide unified diffs, i.e the out‐
229 put of diff -u.
230 Note further that attachments are strongly preferred over inlined
232 patches. Attachments can be made by going to the Edit form of the
233 ticket immediately after its creation, and then using the left-most
234 button in the secondary navigation bar.
235
237 aes(n), blowfish(n), des(n), md5(n), sha1(n)
238
240 cipher, data integrity, encryption, public key cipher, rsa, security
241
243 Hashes, checksums, and encryption
244
246 Copyright (c) 2010, 2011, 2012, 2013, Roy Keene, Andreas Kupries
247tcllib 0.10 pki(n)