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).
53 Requires the caller to specify either -priv to encrypt with the
55 private key or -pub to encrypt with the public key. The default
56 option is to pad and return in hex. One of -pub or -priv must
57 be specified.
58 The -hex option causes the data to be returned in encoded as a
60 hexidecimal string, while the -binary option causes the data to
61 be returned as a binary string. If they are specified multiple
62 times, the last one specified is used.
63 The -pad option causes the data to be padded per PKCS#1 prior to
65 being encrypted. The -nopad inhibits this behaviour. If they
66 are specified multiple times, the last one specified is used.
67 The input to encrypt is specified as input.
69 The key parameter, holding the key to use, is a return value
71 from either ::pki::pkcs::parse_key, ::pki::x509::parse_cert, or
72 ::pki::rsa::generate.
73 Mapping to OpenSSL's openssl application:
75 [1] "openssl rsautl -encrypt" == "::pki::encrypt -binary
77 -pub"
78 [2] "openssl rsautl -sign" == "::pki::encrypt -binary
80 -priv"
81 ::pki::decrypt ?-binary? ?-hex? ?-unpad? ?-nounpad? ?-priv? ?-pub? ?--?
83 input key
84 Decrypt a message using PKI (probably RSA). See ::pki::encrypt
85 for option handling.
86 Mapping to OpenSSL's openssl application:
88 [1] "openssl rsautl -decrypt" == "::pki::decrypt -binary
90 -priv"
91 [2] "openssl rsautl -verify" == "::pki::decrypt -binary
93 -pub"
94 ::pki::sign input key ?algo?
96 Digitally sign message input using the private key.
97 If algo is ommited "sha1" is assumed. Possible values for algo
99 include "md5", "sha1", "sha256", and "raw". Specifying "raw" for
100 algo will inhibit the building of an ASN.1 structure to encode
101 which hashing algorithm was chosen. Attention: In this case the
102 corresponding pkgi::verify must be called with algorithm infor‐
103 mation. Conversely, specifying a non-"raw" algorithm here means
104 that the corresponding pkgi::verify invokation has to be made
105 without algorithm information.
106 The input should be the plain text, hashing will be performed on
108 it.
109 The key should include the private key.
111 ::pki::verify signedmessage plaintext key ?algo?
113 Verify a digital signature using a public key. Returns true or
114 false.
115 Attention: The algorithm information algo has to be specified if
117 and only if the pki::sign which generated the signedmessage was
118 called with algorithm "raw". This inhibited the building of the
119 ASN.1 structure encoding the chosen hashing algorithm. Con‐
120 versely, if a proper algorithm was specified during signing then
121 you must not specify an algorithm here.
122 ::pki::key key ?password? ?encodePem?
124 Convert a key structure into a serialized PEM (default) or DER
125 encoded private key suitable for other applications. For RSA
126 keys this means PKCS#1.
127 ::pki::pkcs::parse_key key ?password?
129 Convert a PKCS#1 private key into a usable key, i.e. one which
130 can be used as argument for ::pki::encrypt, ::pki::decrypt,
131 ::pki::sign, and ::pki::verify.
132 ::pki::x509::parse_cert cert
134 Convert an X.509 certificate to a usable (public) key. The re‐
135 turned dictionary can be used as argument for ::pki:encrypt,
136 ::pki::decrypt, and ::pki::verify. The cert argument can be ei‐
137 ther PEM or DER encoded. In addition to the public keying in‐
138 formation, the dictionary contains the following keys containing
139 certificate content as defined in RFC5280 [https://www.rfc-edi‐
140 tor.org/rfc/rfc5280#section-4.1]:
141 • subject holds the name of the subject from the certifi‐
143 cate.
144 • issuer holds the name of the issuing CA.
146 • serial_number holds the serial number of the certificate.
148 • notBefore holds the starting date for certificate valid‐
150 ity.
151 • notAfter holds the ending date for certificate validity.
153 • version holds the X.509 version format.
155 • extensions holds a dictionary containing the extensions
157 included in the certificate (see below).
158 The dictionary holds additional entries related to keying. These
160 are intended for use of the above-mentioned commands for crypto‐
161 graphic operations.
162 The extensions key in the returned dictionary holds a nested
164 dictionary whose keys correspond to the names (with same exact
165 case) in Certificate Extensions [https://www.rfc-edi‐
166 tor.org/rfc/rfc5280#section-4.2] in RFC5280. The format of each
167 value is also based on the ASN.1 structures defined there. See
168 the Examples [#section3] for an illustration.
169 ::pki::rsa::generate bitlength ?exponent?
171 Generate a new RSA key pair, the parts of which can be used as
172 argument for ::pki::encrypt, ::pki::decrypt, ::pki::sign, and
173 ::pki::verify.
174 The bitlength argument is the length of the public key modulus.
176 The exponent argument should generally not be specified unless
178 you really know what you are doing.
179 ::pki::x509::verify_cert cert trustedcerts ?intermediatecerts?
181 Verify that a trust can be found between the certificate speci‐
182 fied in the cert argument and one of the certificates specified
183 in the list of certificates in the trustedcerts argument.
184 (Eventually the chain can be through untrusted certificates
185 listed in the intermediatecerts argument, but this is currently
186 unimplemented). The certificates specified in the cert and
187 trustedcerts option should be parsed (from
188 ::pki::x509::parse_cert).
189 ::pki::x509::validate_cert cert ?-sign_message dn_of_signer? ?-en‐
191 crypt_message dn_of_signer? ?-sign_cert dn_to_be_signed ca_depth? ?-ssl
192 dn?
193 Validate that a certificate is valid to be used in some capac‐
194 ity. If multiple options are specified they must all be met for
195 this procedure to return "true".
196 Currently, only the -sign_cert option is functional. Its argu‐
198 ments are dn_to_be_signed and ca_depth. The dn_to_be_signed is
199 the distinguished from the subject of a certificate to verify
200 that the certificate specified in the cert argument can sign.
201 The ca_depth argument is used to indicate at which depth the
202 verification should be done at. Some certificates are limited
203 to how far down the chain they can be used to verify a given
204 certificate.
205 ::pki::pkcs::create_csr keylist namelist ?encodePem? ?algo?
207 Generate a certificate signing request from a key pair specified
208 in the keylist argument.
209 The namelist argument is a list of "name" followed by "value"
211 pairs to encoding as the requested distinguished name in the
212 CSR.
213 The encodePem option specifies whether or not the result should
215 be PEM encoded or DER encoded. A "true" value results in the
216 result being PEM encoded, while any other value 9results in the
217 the result being DER encoded. DER encoding is the default.
218 The algo argument specifies the hashing algorithm we should use
220 to sign this certificate signing request with. The default is
221 "sha1". Other possible values include "md5" and "sha256".
222 ::pki::pkcs::parse_csr csr
224 Parse a Certificate Signing Request. The csr argument can be ei‐
225 ther PEM or DER encoded. The command returns a dictionary that
226 includes the following keys:
227 • subject - contains the subject name from the CSR.
229 • type - contains the public key algorithm name. Currently
231 only rsa is supported.
232 • extensionRequest - contains a dictionary with the con‐
234 tents of the extensionRequest [https://data‐
235 tracker.ietf.org/doc/html/rfc2986#page-5] information in
236 the CSR. This has the same form as described for the ex‐
237 tensions dictionary in the documentation for parse_cert.
238 There may be other keys in the dictionary related to the public
240 key algorithm in use.
241 ::pki::x509::create_cert signreqlist cakeylist serial_number notBefore
243 notAfter isCA extensions ?encodePem? ?algo?
244 Sign a signing request (usually from ::pki::pkcs::create_csr or
245 ::pki::pkcs::parse_csr) with a Certificate Authority (CA) cer‐
246 tificate.
247 The signreqlist argument should be the parsed signing request.
249 The cakeylist argument should be the parsed CA certificate.
251 The serial_number argument should be a serial number unique to
253 this certificate from this certificate authority.
254 The notBefore and notAfter arguments should contain the time be‐
256 fore and after which (respectively) the certificate should be
257 considered invalid. The time should be encoded as something
258 clock format will accept (i.e., the results of clock seconds and
259 clock add).
260 The isCA argument is a boolean argument describing whether or
262 not the signed certificate should be a a CA certificate. If
263 specified as true the "id-ce-basicConstraints" extension is
264 added with the arguments of "critical" being true, "allowCA" be‐
265 ing true, and caDepth being -1 (infinite).
266 The extensions argument is a list of extensions and their param‐
268 eters that should be encoded into the created certificate.
269 Currently only one extension is understood ("id-ce-basic‐
270 Constraints"). It accepts three arguments critical allowCA
271 caDepth. The critical argument to this extension (and any ex‐
272 tension) whether or not the validator should reject the certifi‐
273 cate as invalid if it does not understand the extension (if set
274 to "true") or should ignore the extension (if set to "false").
275 The allowCA argument is used to specify as a boolean value
276 whether or not we can be used a certificate authority (CA). The
277 caDepth argument indicates how many children CAs can be children
278 of this CA in a depth-wise fashion. A value of "0" for the
279 caDepth argument means that this CA cannot sign a CA certificate
280 and have the result be valid. A value of "-1" indicates infi‐
281 nite depth.
282
284 The example below retrieves a certificate from www.example.com using
285 the TLS extension and dumps its content.
286 % set so [tls::socket www.example.com 443]
289 sock00000229EB84E710
290 % tls::handshake $so
291 1
292 % set status [tls::status $so]
293 ...output not shown...
294 % set cert_pem [dict get $status certificate]
295 ...output not shown...
296 % set cert [::pki::x509::parse_cert $cert_pem]
297 ...output not shown...
298 % dict get $cert subject
299 C=US, ST=California, L=Los Angeles, O=Internet Corporation for Assigned Names and Numbers, CN=www.example.org
300 % dict get $cert issuer
301 C=US, O=DigiCert Inc, CN=DigiCert TLS RSA SHA256 2020 CA1
302 % clock format [dict get $cert notAfter]
303 Sun Dec 26 05:29:59 +0530 2021
304 % set extensions [dict get $cert extensions]
305 ...output not shown...
306 % dict keys $extensions
307 authorityKeyIdentifier subjectKeyIdentifier subjectAltName keyUsage extKeyUsage cRLDistributionPoints certificatePolicies authorityInfoAccess id-ce-basicConstraints basicConstraints 1.3.6.1.4.1.11129.2.4.2
308 dict get $extensions basicConstraints
309 1 {0 -1}
310 % dict get $extensions keyUsage
311 1 {5 digitalSignature keyEncipherment}
312 % dict get $extensions extKeyUsage
313 0 {serverAuth clientAuth}
314 % dict get $extensions subjectAltName
315 0 {dNSName www.example.org dNSName example.com dNSName example.edu dNSName example.net dNSName example.org dNSName www.example.com dNSName www.example.edu dNSName www.example.net}
316 % dict get $extensions basicConstraints
317 1 {0 -1}
318 % dict get $extensions keyUsage
319 1 {5 digitalSignature keyEncipherment}
320 % dict get $extensions extKeyUsage
321 0 {serverAuth clientAuth}
322
325 [1] Internet X.509 Public Key Infrastructure Certificate and Cer‐
326 tificate Revocation List (CRL) Profile [https://www.rfc-edi‐
327 tor.org/rfc/rfc5280]
328 [2] New ASN.1 Modules for the Public Key Infrastructure Using X.509
330 (PKIX) [https://www.rfc-editor.org/rfc/rfc5912]
331 [3] PKCS #10: Certification Request Syntax Specification
333 [https://www.rfc-editor.org/rfc/rfc2986]
334
336 Roy Keene, Ashok P. Nadkarni
337
339 This document, and the package it describes, will undoubtedly contain
340 bugs and other problems. Please report such in the category rsa of the
341 Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also
342 report any ideas for enhancements you may have for either package
343 and/or documentation.
344 When proposing code changes, please provide unified diffs, i.e the out‐
346 put of diff -u.
347 Note further that attachments are strongly preferred over inlined
349 patches. Attachments can be made by going to the Edit form of the
350 ticket immediately after its creation, and then using the left-most
351 button in the secondary navigation bar.
352
354 aes(n), blowfish(n), des(n), md5(n), sha1(n)
355
357 cipher, data integrity, encryption, public key cipher, rsa, security
358
360 Hashes, checksums, and encryption
361
363 Copyright (c) 2010, 2011, 2012, 2013, 2021 Roy Keene, Andreas Kupries, Ashok P. Nadkarni
364tcllib 0.10 pki(n)