325 lines
6 KiB
Text
325 lines
6 KiB
Text
.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
|
|
[
|
|
-a
|
|
]
|
|
[
|
|
.I file
|
|
]
|
|
.PP
|
|
.B rsa2pub
|
|
[
|
|
.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 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.
|
|
.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.
|