Subversion Repositories planix.SVN

.TH RSA 8

.SH NAME

rsagen, rsafill, asn12rsa, rsa2pub, rsa2ssh, rsa2x509 \- generate and format rsa keys

.SH SYNOPSIS

.B auth/rsagen

[

.B -b

.I nbits

]

[

.B -t

.I tag

]

.PP

.B auth/rsafill

[

.I file

]

.PP

.B auth/asn12rsa

[

.B -t

.I tag

]

[

.I file

]

.PP

.B auth/rsa2pub

[

.I file

]

.PP

.B auth/rsa2ssh

[

.I file

]

.PP

.B auth/rsa2x509

[

.B -e

.I expiretime

]

.I certinfo

[

.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 1024)

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 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 Rsa2ssh

reads a Plan 9 RSA public or private key and prints the public portion 

in the format used by SSH: three space-separated decimal numbers

.BR size ,

.BR ek ,

and

.BR n .

For compatibility with external SSH implementations, the public keys in

.B /sys/lib/ssh/keyring

and

.B $home/lib/keyring

are stored in this format.

.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

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.

.SH EXAMPLES

Generate a fresh key and use it to start a TLS-enabled web server:

.IP

.EX

auth/rsagen -t 'service=tls 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' >key

auth/rsa2ssh key | ssh unix 'cat >>.ssh/authorized_keys'

cat key >/mnt/factotum/ctl

ssh unix

.EE

.SH SOURCE

.B /sys/src/cmd/auth

.SH "SEE ALSO

.IR ssh (1),

.IR factotum (4),

.IR dsa (8),

.IR pem (8)

.SH BUGS

There are too many key formats.