sys/man/8/rsa

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