merging erik quanstros nupas

[plan9front.git] / sys / man / 8 / rsa

diff --git a/sys/man/8/rsa b/sys/man/8/rsa
old mode 100755 (executable)
new mode 100644 (file)
index cc0ca8a..a5d3657
--- a/sys/man/8/rsa
+++ b/sys/man/8/rsa
@@ -1,6 +1,6 @@
 .TH RSA 8
 .SH NAME
-rsagen, rsafill, asn12rsa, rsa2pub, rsa2ssh, rsa2x509 \- generate and format rsa keys
+rsagen, rsafill, asn12rsa, rsa2pub, rsa2ssh, rsa2x509, rsa2csr \- generate and format rsa keys
 .SH SYNOPSIS
 .B rsagen
 [
@@ -33,6 +33,13 @@ rsagen, rsafill, asn12rsa, rsa2pub, rsa2ssh, rsa2x509 \- generate and format rsa
 .PP
 .B rsa2ssh
 [
+.B -2
+]
+[
+.B -c
+.I comment
+]
+[
 .I file
 ]
 .PP
@@ -45,6 +52,12 @@ rsagen, rsafill, asn12rsa, rsa2pub, rsa2ssh, rsa2x509 \- generate and format rsa
 [
 .I file
 ]
+.PP
+.B rsa2csr
+.I subject
+[
+.I file
+]
 .SH DESCRIPTION
 Plan 9 represents an RSA key as an attribute-value pair list
 prefixed with the string
@@ -111,7 +124,7 @@ whose
 .B n
 has exactly
 .I nbits
-(default 1024)
+(default 2048)
 significant bits.
 If
 .I tag
@@ -170,6 +183,11 @@ in the format used by SSH: three space-separated decimal numbers
 .BR ek ,
 and
 .BR n .
+The
+.B -2
+option will change the output to SSH2 RSA public key format. The
+.B -c
+option will set the comment.
 For compatibility with external SSH implementations, the public keys in
 .B /sys/lib/ssh/keyring
 and
@@ -195,6 +213,10 @@ This info is typically in the form:
 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 .''
@@ -212,6 +234,16 @@ Applications that serve TLS-encrypted sessions (for example,
 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.
 .SH EXAMPLES
 Generate a fresh key and use it to start a TLS-enabled web server:
 .IP
@@ -232,11 +264,25 @@ 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
 .SH SOURCE
 .B /sys/src/cmd/auth
 .SH "SEE ALSO
 .IR factotum (4),
 .IR pem (8),
-.IR ssh (1)
 .SH BUGS
 There are too many key formats.