sys/man/8/rsa

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