1CLKEYS(1) Cryptlib Tools CLKEYS(1)
2
6 clkeys - public key management tool interoperating with Thunderbird and
7 openssl
8
10 clkeys generate [-DSA] KeysetName [-SIZE RSABits] [-CN YourName]
11 clkeys request KeysetName [-CN YourName]
13 clkeys import KeysetName CertFile
15 clkeys casign CA-KeysetName RequestFile
17
20 clkeys generates RSA and DSA asymmetric keys and stores keys in a file
21 in the PKCS#15 token format.
22 As both OpenSSL and standard E-mail clients expect private RSA keys in
24 a file based on the PKCS#12 format, keys generated by Cryptlib cannot
25 be exchanged between clkeys and those programs. Many will see this as a
26 disadvantage or detriment and maybe even as a reason not to use
27 Cryptlib, but this assessment is totally incorrect.
28 There is a reason why Cryptlib does not provide any other file storage
30 of private keys and a very important one. Storing private keys in the
31 PKCS#12 format exposes the key material to a number of weaknesses, de‐
32 scribed in a paper here:
33 (https://www.usenix.org/legacy/event/sec02/full_papers/gutmann/gut‐
34 mann.pdf)
35 In contrast, one of the principal design features of Cryptlib is that
37 it never exposes private keys to outside access. So do not wait (or
38 even wish) for a conversion tool that makes Cryptlib-generated keys
39 available in a p12 file. It makes no sense to deliberately reduce the
40 security of your private keys just because some E-mail client wants
41 them in a weak format only.
42 However, even if standard E-mail programs cannot import Cryptlib-gener‐
44 ated keys (which can be seen as a missing feature) a comprehensive ex‐
45 change of SMIME messages is nevertheless possible. Certificates based
46 on requests created by clkeys can be imported into standard E-mail pro‐
47 grams directly. And any messages in SMIME format can be decrypted and
48 signed with clkeys-generated keys using clsmime.
49 In addition to generating RSA and DSA public key pairs, clkeys can gen‐
51 erate certificate signing requests for a public key and also import
52 self-signed certificates or certificates signed by a CA into the p15
53 keyset file if a corresponding private key is found in the keyset file.
54 When clkeys generates a key pair, a self-signed certificate is created
56 that can be used for all kinds of purposes (Digital Signature, Non Re‐
57 pudiation, Key Encipherment, Certificate Sign, CRL Sign) and has a very
58 long lifespan (20 years). Any of these self-signed certificates can be
59 used together with the corresponding private key to sign certificate
60 requests for other keys used by PKI users for email or other purposes.
61 These self-signed certificates can also be imported in the CA section
63 of E-mail clients like Thunderbird, but they are not fit for identify‐
64 ing persons, as their Basic Constraint is set to CA:TRUE and they don't
65 have an email address included.
66 The process of producing valid email certificates for persons is de‐
68 scribed below.
69
72 -DSA generate a DSA public key pair instead of the (default) RSA keys
73 -RSABits number
75 specify the number of bits for the RSA modulus (between 1536 and
76 4096 bits)
77 -CN common name
79 without this option the generated key is stored under the KEYID
80 identical to the name of the keyset file. To store the keys
81 (private and public) under a different Name comprised of several
82 distinct name components (like James O´Connor Jr) the option -CN
83 can be used. This common name is also necessary to be included
84 in a certificate signing request. The character ' must be es‐
85 caped on the command line.
86
88 Full documentation <https://senderek.ie/cryptlib/tools>
89 This program depends on two packages providing the cryptlib shared ob‐
91 ject library and the python3-bindings to this library.
92 You can download both packages in RPM or DEB format at
94 https://senderek.ie/cryptlib/downloads
95 Using FEDORA you can install the packages cryptlib and cryptlib-python3
97 directly from the repository.
98 In addition the program /bin/systemd-ask-password is needed to read
100 sensible data from stdin. This program is part of the systemd package.
101
104 Thunderbird E-mail client (user certificates)
105 Thunderbird does accept certificates only when an email address
106 is present as a part of the CN (common name) or stored in the
107 SAN (subject alternative name). As clkeys always uses the SAN to
108 store the email address in certificate signing requests (CSR),
109 the CSR should normally be signed by a CA key made by clkeys.
110 This will ensure, that the user can import the resulting cer‐
111 tificate directly into an E-mail client. The user's certificate
112 will contain the email address in the SAN field.
113 To sign a CSR with the CA signing key generated by clkeys in a
115 p15 keyset you will use the following steps:
116 1) clkeys generate CAkey -SIZE 4096 -CN Your CAname
119 2) clkeys import CAkey.cert.pem
121 # without importing the self-signed cert the CA private key cannot sign requests
122 3) clkeys generate Joe -SIZE 2678 -CN Joe Doe Sen
124 4) clkeys request Joe -CN Joe Doe Sen
126 5) clkeys casign CAkey Joe.CSR.der
128 The resulting file Joe.newcert.pem can then be used to be imported into
130 Thunderbird in the persons section. Make sure the file
131 'CAkey.cert.pem' is already imported in the CA section and proper per‐
132 missions are being set.
133 On the other hand, if the user's certificate is being produced by an
135 external CA that does accept only fields of the DN in the request (and
136 not the SAN), the resulting certificate will not have an email address
137 and is useless for import into E-mail clients. The external CA should
138 therefore use the option "subjectAltName=email:${ENV::SAN}" in the [
139 usr_cert ] section of its config file and provide the email address via
140 the environment variable SAN.
141 To extract the subjectAltName from a request file (in DER format), you
143 can use the program here: https://senderek.ie/cryptlib/tools/selectSAN
144 All SMIME encrypted or signed messages produced by Thunderbird can be
146 handled by a separate program clsmime that uses keyset files generated
147 by clkeys.
148 OpenSSL
151 clkey generates self-signed certificates for RSA and DSA keys
153 and certificate signing requests that can be processed by
154 OpenSSL in PEM and DER format in the usual way.
155 FILES
158 /usr/bin/systemd-ask-password
160 This program is used to provide the passphrase based on a user's
161 input.
162 /lib64/libcl.so.3.4.7
164 The cryptlib library.
165 /usr/lib/python3.10/site-packages/cryptlib_py.so
167 Bindings to the cryptlib library used by python3.
168
170 Please report bugs to innovation@senderek.ie
171
174 clkeys is written by Ralf Senderek <innovation@senderek.ie>.
175 Cryptlib is written and maintained by Peter Gutmann <pgut001@cs.auckland.ac.nz>
176
179 Copyright © 2023 Ralf Senderek. All rights reserved.
180 License BSD: <https://senderek.ie/cryptlib/bsd.html>.
182 This is free software: you are free to change and redistribute it.
183 There is NO WARRANTY, to the extent permitted by law.
184
187 cryptlib, clrsa, clsmime, claes
188Cryptlib Tools October 2023 CLKEYS(1)