sys/man/8/rsa

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