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