ref: fb96a050f8a9d5f23da3557ba89251ffb73889bf
dir: /sys/man/8/rsa/
.TH RSA 8 .SH NAME rsagen, rsafill, asn12rsa, rsa2asn1, rsa2pub, rsa2ssh, rsa2x509, rsa2csr, rsa2jwk, x5092pub \- generate and format rsa keys .SH SYNOPSIS .B rsagen [ .B -b .I nbits ] [ .B -t .I tag ] .PP .B rsafill [ .I file ] .PP .B asn12rsa [ .B -t .I tag ] [ .I file ] .PP .B rsa2asn1 [ .B -a ] [ .B -f .I fmt ] [ .I file ] .PP .B rsa2pub [ .I file ] .PP .B ssh2rsa [ .I file ] .PP .B rsa2ssh [ .B -c .I comment ] [ .I file ] .PP .B rsa2jwk [ .I file ] .PP .B rsa2x509 [ .B -e .I expiretime ] .I certinfo [ .I file ] .PP .B rsa2csr .I subject [ .I file ] .PP .B x5092pub [ .B -r ] [ .I file ] .SH DESCRIPTION Plan 9 represents an RSA key as an attribute-value pair list prefixed with the string .BR key ; this is the generic key format used by .IR factotum (4). A full RSA private key has the following attributes: .TF proto .PD .TP .B proto must be .B rsa .TP .B size the number of significant bits in .B n .TP .B ek the encryption exponent .TP .B n the product of .B !p and .B !q .TP .B !dk the decryption exponent .TP .B !p a large prime .TP .B !q another large prime .TP .B "!kp\fR, \fL!kq\fR, \fL!c2 parameters derived from the other attributes, cached to speed decryption .PD .LP All the numbers are in hexadecimal except .IR size , which is decimal. An RSA public key omits the attributes beginning with .LR ! . A key may have other attributes as well (for example, a .B service attribute identifying how this key is typically used), but to these utilities such attributes are merely comments. .PP For example, a very small (and thus insecure) private key and corresponding public key might be: .IP .EX key proto=rsa size=8 ek=7 n=8F !dk=67 !p=B !q=D !kp=3 !kq=7 !c2=6 key proto=rsa size=8 ek=7 n=8F .EE .LP Note that the order of the attributes does not matter. .PP .I Rsagen prints a randomly generated RSA private key whose .B n has exactly .I nbits (default 2048) significant bits. If .I tag is specified, it is printed between .B key and .BR proto=rsa ; typically, .I tag is a sequence of attribute-value comments describing the key. .PP .I Rsafill reads a private key, recomputes the .BR !kp , .BR !kq , and .BR !c2 attributes if they are missing, and prints a full key. .PP .I Asn12rsa reads an RSA private or public key stored as ASN.1 encoded in the binary Distinguished Encoding Rules (DER) and prints a Plan 9 RSA key, inserting .I tag exactly as .I rsagen does. ASN.1/DER is a popular key format on Unix and Windows; it is often encoded in text form using the Privacy Enhanced Mail (PEM) format in a section labeled as an .RB `` RSA .B PRIVATE .BR KEY .'' The command: .IP .EX auth/pemdecode 'RSA PRIVATE KEY' | auth/asn12rsa .EE .LP extracts the key section from a textual ASN.1/DER/PEM key into binary ASN.1/DER format and then converts it to a Plan 9 RSA key. .PP .I Ssh2rsa reads an RSA private key stored in the binary OpenSSH key format and prints a Plan 9 RSA key. The command: .IP .EX auth/pemdecode 'OPENSSH PRIVATE KEY' id_rsa | auth/ssh2rsa .EE .LP converts an id_rsa, as output by Unix ssh-keygen, to a Plan 9 RSA key. .PP .I Rsa2pub reads a Plan 9 RSA public or private key, removes the private attributes, and prints the resulting public key. Comment attributes are preserved. .PP .I Rsa2asn1 is like .I rsa2pub but outputs the public key in ASN.1/DER format. With the .I -a flag a private key is read and encoded in ANS.1/DER format. With the .I -f flag, the format of the ASN.1/DER encoded key is selected. The supported formats are .I pkcs1 and .IR spki , which refer to RFC3447 RSAPublicKey and RFC5280 SubjectPublicKeyInfo formatted RSA keys respectively. The default format is pkcs1. .PP .I Rsa2ssh reads a Plan 9 RSA public or private key and prints the public portion in the format used by SSH2. The .B -c option will set the comment. .PP .I Rsa2jwk reads a Plan 9 RSA public or private key and prints the public portion as a RFC7517 formated JSON Web Key. .PP .I Rsa2x509 reads a Plan 9 RSA private key and writes a self-signed X.509 certificate encoded in ASN.1/DER format to standard output. (Note that ASN.1/DER X.509 certificates are different from ASN.1/DER private keys). The certificate uses the current time as its start time and expires .I expiretime seconds (default 3 years) later. It contains the public half of the key and includes .I certinfo as the issuer/subject string (also known as a ``Distinguished Name''). This info is typically in the form: .IP .EX C=US ST=NJ L=07974 O=Lucent OU='Bell Labs' CN=G.R.Emlin .EE .LP One can append further Distinguished Names, DNS Names and E-Mail addresses as a ``Subject Alternative Name'' separated with a comma after the main subject. .LP The X.509 ASN.1/DER format is often encoded in text using a PEM section labeled as a .RB `` CERTIFICATE .'' The command: .IP .EX auth/rsa2x509 'C=US OU=''Bell Labs''' file | auth/pemencode CERTIFICATE .EE .LP generates such a textual certificate. Applications that serve TLS-encrypted sessions (for example, .IR httpd (8), .IR pop3 (8), and .IR tlssrv (8)) expect certificates in ASN.1/DER/PEM format. .PP The Plan 9 RSA private key needs to be loaded into factotum for TLS server applications. It is recommended to put the key into .IR secstore (1), avoiding it being stored unencrypted on the filesystem. .PP .I Rsa2csr takes the .I subject and a RSA private key and outputs a signing request in ASN.1 format. .PP The program .I x5092pub converts a binary certificate (or certificate request when .B -r flag is given) read from .I file or stdin, and outputs the public key with a .B subject attribute on standard output. .SH EXAMPLES Generate a fresh key and use it to start a TLS-enabled web server: .IP .EX auth/rsagen -t 'service=tls role=client owner=*' >key auth/rsa2x509 'C=US CN=*.cs.bell-labs.com' key | auth/pemencode CERTIFICATE >cert cat key >/mnt/factotum/ctl ip/httpd/httpd -c cert .EE .PP Generate a fresh key and configure a remote Unix system to allow use of that key for logins: .IP .EX auth/rsagen -t 'service=ssh role=client' >key auth/rsa2ssh key | ssh unix 'cat >>.ssh/authorized_keys' cat key >/mnt/factotum/ctl ssh unix .EE .PP Convert a private key in PEM format (as generated by OpenSSL) and load it into factotum: .IP .EX auth/pemdecode 'PRIVATE KEY' key.pem | auth/asn12rsa -t 'service=tls' >/mnt/factotum/ctl .EE .PP Generate a certificate signing request (CSR) in PEM format: .IP .EX auth/rsa2csr 'CN=example.com' key | auth/pemencode 'CERTIFICATE REQUEST' .EE .PP Generate a tinc host key: .IP .EX auth/rsagen -t 'service=tinc role=client host=myhost' > myhost.key auth/rsa2pub < myhost.key | auth/rsa2asn1 | auth/pemencode 'RSA PUBLIC KEY' > hosts/myhost .EE .SH SOURCE .B /sys/src/cmd/auth .SH "SEE ALSO .IR factotum (4), .IR pem (8), .SH BUGS There are too many key formats.