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