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