sys/man/8/rsa

   1 .TH RSA 8
   2 .SH NAME
   3 rsagen, rsafill, asn12rsa, rsa2pub, rsa2ssh, rsa2x509 \- 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 .SH DESCRIPTION
  56 Plan 9 represents an RSA key as an attribute-value pair list
  57 prefixed with the string
  58 .BR key ;
  59 this is the generic key format used by
  60 .IR factotum (4).
  61 A full RSA private key has the following attributes:
  62 .TF proto
  63 .PD
  64 .TP
  65 .B proto
  66 must be
  67 .B rsa
  68 .TP
  69 .B size
  70 the number of significant bits in
  71 .B n
  72 .TP
  73 .B ek
  74 the encryption exponent
  75 .TP
  76 .B n
  77 the product of
  78 .B !p
  79 and
  80 .B !q
  81 .TP
  82 .B !dk
  83 the decryption exponent
  84 .TP
  85 .B !p
  86 a large prime
  87 .TP
  88 .B !q
  89 another large prime
  90 .TP
  91 .B "!kp\fR, \fL!kq\fR, \fL!c2
  92 parameters derived from the other attributes, cached to speed decryption
  93 .PD
  94 .LP
  95 All the numbers are in hexadecimal except
  96 .I size ,
  97 which is decimal.
  98 An RSA public key omits the attributes beginning with
  99 .L ! .
 100 A key may have other attributes as well (for example, a
 101 .B service
 102 attribute identifying how this key is typically used),
 103 but to these utilities such attributes are merely comments.
 104 .PP
 105 For example, a very small (and thus insecure) private key and corresponding
 106 public key might be:
 107 .IP
 108 .EX
 109 key proto=rsa size=8 ek=7 n=8F !dk=67 !p=B !q=D !kp=3 !kq=7 !c2=6
 110 key proto=rsa size=8 ek=7 n=8F
 111 .EE
 112 .LP
 113 Note that the order of the attributes does not matter.
 114 .PP
 115 .I Rsagen
 116 prints a randomly generated RSA private key
 117 whose
 118 .B n
 119 has exactly
 120 .I nbits
 121 (default 2048)
 122 significant bits.
 123 If
 124 .I tag
 125 is specified, it is printed between
 126 .B key
 127 and
 128 .BR proto=rsa ;
 129 typically,
 130 .I tag
 131 is a sequence of attribute-value comments describing the key.
 132 .PP
 133 .I Rsafill
 134 reads a private key,
 135 recomputes the
 136 .BR !kp ,
 137 .BR !kq ,
 138 and
 139 .BR !c2
 140 attributes if they are missing,
 141 and prints a full key.
 142 .PP
 143 .I Asn12rsa
 144 reads an RSA private key stored as ASN.1
 145 encoded in the binary Distinguished Encoding Rules (DER)
 146 and prints a Plan 9 RSA key,
 147 inserting
 148 .I tag
 149 exactly as
 150 .I rsagen
 151 does.
 152 ASN.1/DER is a popular key format on Unix and Windows;
 153 it is often encoded in text form using the Privacy Enhanced Mail (PEM) format
 154 in a section labeled as an
 155 .RB `` RSA
 156 .B PRIVATE
 157 .BR KEY .''
 158 The command:
 159 .IP
 160 .EX
 161 auth/pemdecode 'RSA PRIVATE KEY' | auth/asn12rsa
 162 .EE
 163 .LP
 164 extracts the key section from a textual ASN.1/DER/PEM key
 165 into binary ASN.1/DER format and then
 166 converts it to a Plan 9 RSA key.
 167 .PP
 168 .I Rsa2pub
 169 reads a Plan 9 RSA public or private key,
 170 removes the private attributes, and prints the resulting public key.
 171 Comment attributes are preserved.
 172 .PP
 173 .I Rsa2ssh
 174 reads a Plan 9 RSA public or private key and prints the public portion
 175 in the format used by SSH: three space-separated decimal numbers
 176 .BR size ,
 177 .BR ek ,
 178 and
 179 .BR n .
 180 The
 181 .B -2
 182 option will change the output to SSH2 RSA public key format. The
 183 .B -c
 184 option will set the comment.
 185 For compatibility with external SSH implementations, the public keys in
 186 .B /sys/lib/ssh/keyring
 187 and
 188 .B $home/lib/keyring
 189 are stored in this format.
 190 .PP
 191 .I Rsa2x509
 192 reads a Plan 9 RSA private key and writes a self-signed X.509 certificate
 193 encoded in ASN.1/DER format to standard output.
 194 (Note that ASN.1/DER X.509 certificates are different from ASN.1/DER private keys).
 195 The certificate uses the current time as its start time and expires
 196 .I expiretime
 197 seconds
 198 (default 3 years)
 199 later.
 200 It contains the public half of the key
 201 and includes
 202 .I certinfo
 203 as the issuer/subject string (also known as a ``Distinguished Name'').
 204 This info is typically in the form:
 205 .IP
 206 .EX
 207 C=US ST=NJ L=07974 O=Lucent OU='Bell Labs' CN=G.R.Emlin
 208 .EE
 209 .LP
 210 The X.509 ASN.1/DER format is often encoded in text using a PEM section
 211 labeled as a
 212 .RB `` CERTIFICATE .''
 213 The command:
 214 .IP
 215 .EX
 216 auth/rsa2x509 'C=US OU=''Bell Labs''' file |
 217 auth/pemencode CERTIFICATE
 218 .EE
 219 .LP
 220 generates such a textual certificate.
 221 Applications that serve TLS-encrypted sessions (for example,
 222 .IR httpd (8),
 223 .IR pop3 (8),
 224 and
 225 .IR tlssrv (8))
 226 expect certificates in ASN.1/DER/PEM format.
 227 .PP
 228 The Plan 9 RSA private key needs to be loaded into factotum
 229 for TLS server applications. It is recommended to put the key into
 230 .IR secstore (1),
 231 avoiding it being stored unencrypted on the filesystem.
 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 .SH SOURCE
 261 .B /sys/src/cmd/auth
 262 .SH "SEE ALSO
 263 .IR factotum (4),
 264 .IR pem (8),
 265 .IR ssh (1)
 266 .SH BUGS
 267 There are too many key formats.