1 .TH RSA 1
2 .SH NAME
3 dsagen, rsagen, rsafill, asn12dsa, asn12rsa, dsa2pub, rsa2csr, rsa2pub, dsa2ssh, rsa2ssh, rsa2x509 \- generate and format dsa and rsa keys
4 .SH SYNOPSIS
5 .PP
6 .B dsagen
7 [
8 .B -t
9 .I tag
10 ]
11 .PP
12 .B rsagen
13 [
14 .B -b
15 .I nbits
16 ]
17 [
18 .B -t
19 .I tag
20 ]
21 .PP
22 .B rsafill
23 [
24 .I file
25 ]
26 .PP
27 .B asn12dsa
28 [
29 .B -t
30 .I tag
31 ]
32 [
33 .I file
34 ]
35 .PP
36 .B asn12rsa
37 [
38 .B -t
39 .I tag
40 ]
41 [
42 .I file
43 ]
44 .PP
45 .B dsa2pub
46 [
47 .I file
48 ]
49 .PP
50 .B rsa2pub
51 [
52 .I file
53 ]
54 .PP
55 .B dsa2ssh
56 [
57 .I file
58 ]
59 .PP
60 .B rsa2ssh
61 [
62 .B -2
63 ]
64 [
65 .I file
66 ]
67 .PP
68 .B rsa2x509
69 [
70 .B -e
71 .I expiretime
72 ]
73 .I certinfo
74 [
75 .I file
76 ]
77 .PP
78 .B rsa2csr
79 .I certinfo
80 [
81 .I file
82 ]
83 .SH DESCRIPTION
84 Plan 9 represents DSA and RSA keys as attribute-value pair lists
85 prefixed with the string
86 .BR key ;
87 this is the generic key format used by
88 .MR factotum (4) .
89 A full DSA private key has the following attributes:
90 .TP
91 .B proto
92 must be
93 .B dsa
94 .TP
95 .B p
96 prime public modulus
97 .TP
98 .B q
99 prime group order; divides
100 .BR p -1
101 .TP
102 .B alpha
103 group generator
104 .TP
105 .B key
106 .BR alpha ^ !secret
107 mod
108 .B p
109 .TP
110 .B !secret
111 the secret exponent
112 .PD
113 .PP
114 A full RSA private key has the following attributes:
115 .TP
116 .B proto
117 must be
118 .B rsa
119 .TP
120 .B size
121 the number of significant bits in
122 .B n
123 .TP
124 .B ek
125 the encryption exponent
126 .TP
127 .B n
128 the product of
129 .B !p
130 and
131 .B !q
132 .TP
133 .B !dk
134 the decryption exponent
135 .TP
136 .B !p
137 a large prime
138 .TP
139 .B !q
140 another large prime
141 .TP
142 .B "!kp\fR, \fL!kq\fR, \fL!c2
143 parameters derived from the other attributes, cached to speed decryption
144 .PD
145 .LP
146 All the numbers in both keys are in hexadecimal except RSA's
147 .I size ,
148 which is decimal.
149 A public key omits the attributes beginning with
150 .L ! .
151 A key may have other attributes as well (for example, a
152 .B service
153 attribute identifying how this key is typically used),
154 but to these utilities such attributes are merely comments.
155 .PP
156 For example, a very small (and thus insecure) private key and corresponding
157 public key might be:
158 .IP
159 .EX
160 key proto=rsa size=8 ek=7 n=8F !dk=67 !p=B !q=D !kp=3 !kq=7 !c2=6
161 key proto=rsa size=8 ek=7 n=8F
162 .EE
163 .LP
164 Note that the order of the attributes does not matter.
165 .PP
166 .I Dsagen
167 prints a randomly generated DSA private key using the 
168 NIST-recommended algorithm.
169 If
170 .I tag
171 is specified, it is printed between
172 .B key
173 and
174 .BR proto=dsa ;
175 typically,
176 .I tag
177 is a sequence of attribute-value comments describing the key.
178 .PP
179 .I Rsagen
180 prints a randomly generated RSA private key
181 whose
182 .B n
183 has exactly
184 .I nbits
185 (default 1024)
186 significant bits.
187 .PP
188 .I Rsafill
189 reads a private key,
190 recomputes the
191 .BR !kp ,
192 .BR !kq ,
193 and
194 .BR !c2
195 attributes if they are missing,
196 and prints a full key.
197 .PP
198 .I Asn12dsa
199 reads an DSA private key stored as ASN.1
200 encoded in the binary Distinguished Encoding Rules (DER)
201 and prints a Plan 9 DSA key,
202 inserting
203 .I tag
204 exactly as
205 .I dsagen
206 does.
207 ASN.1/DER is a popular key format on Unix and Windows;
208 it is often encoded in text form using the Privacy Enhanced Mail (PEM) format
209 in a section labeled as an
210 .RB `` DSA
211 .B PRIVATE
212 .BR KEY .''
213 The command:
214 .IP
215 .EX
216 pemdecode 'DSA PRIVATE KEY' | asn12dsa
217 .EE
218 .LP
219 extracts the key section from a textual ASN.1/DER/PEM key
220 into binary ASN.1/DER format and then
221 converts it to a Plan 9 DSA key.
222 .PP
223 .I Asn12rsa
224 is similar but operates on RSA keys.
225 .PP
226 .I Dsa2pub
227 reads a Plan 9 DSA public or private key,
228 removes the private attributes, and prints the resulting public key.
229 Comment attribtes are preserved.
230 .PP
231 .I Rsa2pub
232 is similar but operates on RSA keys.
233 .PP
234 .I Dsa2ssh
235 reads a Plan 9 DSA public or private key and prints the 
236 public portion in the format used by SSH version 2 (version 1 did not support DSA).
237 If the key has a 
238 .B comment
239 attribute, that comment is appended to the key.
240 .PP
241 .I Rsa2ssh
242 is similar but operates on RSA keys.
243 It decides whether to print in version 1 or version 2 
244 format by inspecting the
245 .B service
246 attribute.
247 .PP
248 .I Dsa2ssh
249 and
250 .I rsa2ssh
251 are useful for generating SSH's 
252 .B authorized_keys
253 file.
254 .PP
255 .I Rsa2x509
256 reads a Plan 9 RSA private key and writes a self-signed X.509 certificate
257 encoded in ASN.1/DER format to standard output.
258 (Note that ASN.1/DER X.509 certificates are different from ASN.1/DER private keys).
259 The certificate uses the current time as its start time and expires
260 .I expiretime
261 seconds
262 (default 3 years)
263 later.
264 It contains the public half of the key
265 and includes
266 .I certinfo
267 as the issuer/subject string (also known as a ``Distinguished Name'').
268 This info is typically in the form:
269 .IP
270 .EX
271 C=US ST=NJ L=07974 O=Lucent OU='Bell Labs' CN=G.R.Emlin
272 .EE
273 .LP
274 The X.509 ASN.1/DER format is often encoded in text using a PEM section
275 labeled as a
276 .RB `` CERTIFICATE .''
277 The command:
278 .IP
279 .EX
280 rsa2x509 'C=US OU=''Bell Labs''' file |
281 pemencode CERTIFICATE
282 .EE
283 .LP
284 generates such a textual certificate.
285 Applications that serve TLS-encrypted sessions
286 typically expect certificates in ASN.1/DER/PEM format.
287 .PP
288 .I Rsa2csr
289 is like
290 .I rsa2x509
291 but writes an X.509 certificate request.
292 .SH EXAMPLES
293 Generate a fresh key and use it to start the Plan 9 TLS-enabled web server:
294 .IP
295 .EX
296 rsagen -t 'service=tls owner=*' >key
297 rsa2x509 'C=US CN=*.cs.bell-labs.com' key |
298 	pemencode CERTIFICATE >cert
299 cat key >/mnt/factotum/ctl
300 ip/httpd/httpd -c cert
301 .EE
302 .PP
303 Generate a fresh set of SSH keys (only one is necessary),
304 load them into factotum,
305 and configure a remote Unix system to allow those keys for logins:
306 .IP
307 .EX
308 rsagen -t 'service=ssh role=decrypt' >rsa1
309 rsagen -t 'service=ssh-rsa role=sign' >rsa2
310 dsagen -t 'service=ssh-dss role=sign' >dsa2
311 .EE
312 .PP
313 Convert existing Unix SSH version 2 keys instead of generating new ones:
314 .IP
315 .EX
316 cd $HOME/.ssh
317 pemdecode 'DSA PRIVATE KEY' id_dsa | asn12dsa >dsa2
318 pemdecode 'RSA PRIVATE KEY' id_rsa | asn12rsa >rsa2
319 .EE
320 .PP
321 Load those keys into factotum:
322 .IP
323 .EX
324 cat rsa1 rsa2 dsa2 | 9p write -l factotum/ctl
325 .EE
326 Allow use of those keys for logins on other systems:
327 .IP
328 .EX
329 rsa2ssh rsa1 >auth.keys
330 rsa2ssh rsa2 >>auth.keys
331 dsa2ssh dsa2 >>auth.keys
332 scp auth.keys unix:.ssh/authorized_keys
333 .EE
334 .SH SOURCE
335 .B \*9/src/cmd/auth
336 .SH "SEE ALSO
337 .MR factotum (4) ,
338 .MR pem (1) ,
339 .MR ssh (1)
340 .SH BUGS
341 There are too many key formats.
342 .PP
343 There is no program to convert SSH version 1 RSA private keys.