mirror of
https://github.com/9fans/plan9port.git
synced 2025-01-24 11:41:58 +00:00
more docs
This commit is contained in:
rsc
parent
ef2eeaf3bd
commit
a784b110f5
2 changed files with 401 additions and 0 deletions
65
man/man1/pem.1
Normal file
65
man/man1/pem.1
Normal file
|
|
@ -0,0 +1,65 @@
|
|||
.TH PEM 8
|
||||
.SH NAME
|
||||
pemdecode, pemencode \- encode files in Privacy Enhanced Mail (PEM) format
|
||||
.SH SYNOPSIS
|
||||
.PP
|
||||
.B auth/pemdecode
|
||||
.I section
|
||||
[
|
||||
.I file
|
||||
]
|
||||
.PP
|
||||
.B auth/pemencode
|
||||
.I section
|
||||
[
|
||||
.I file
|
||||
]
|
||||
.SH DESCRIPTION
|
||||
PEM is a textual encoding for binary data originally used by the
|
||||
Privacy Enhanced Mail program but now commonly used for
|
||||
other applications, notably TLS.
|
||||
PEM encodes data in base 64
|
||||
(see
|
||||
.IR encode (2))
|
||||
between lines of the form:
|
||||
.IP
|
||||
.EX
|
||||
-----BEGIN SECTION-----
|
||||
-----END SECTION-----
|
||||
.EE
|
||||
.LP
|
||||
where
|
||||
.B SECTION
|
||||
may be any string describing the encoded data.
|
||||
The most common use of PEM format on Plan 9 is for encoding
|
||||
X.509 certificates; see
|
||||
.IR rsa (8).
|
||||
.PP
|
||||
.I Pemdecode
|
||||
extracts the named
|
||||
.I section
|
||||
and writes the decoded data to standard output.
|
||||
.PP
|
||||
.I Pemencode
|
||||
encodes its standard input, labels it as a
|
||||
.IR section ,
|
||||
and writes it to standard output.
|
||||
.SH EXAMPLES
|
||||
Encode and decode a simple greeting:
|
||||
.IP
|
||||
.EX
|
||||
% echo hello world |
|
||||
auth/pemencode GREETING
|
||||
-----BEGIN GREETING-----
|
||||
aGVsbG8gd29ybGQK
|
||||
-----END GREETING-----
|
||||
% echo hello world |
|
||||
auth/pemencode GREETING |
|
||||
auth/pemdecode GREETING
|
||||
hello world
|
||||
%
|
||||
.EE
|
||||
.SH SOURCE
|
||||
.B \*9/src/cmd/auth
|
||||
.SH "SEE ALSO
|
||||
.IR rsa (1)
|
||||
336
man/man1/rsa.1
Normal file
336
man/man1/rsa.1
Normal file
|
|
@ -0,0 +1,336 @@
|
|||
.TH RSA 8
|
||||
.SH NAME
|
||||
dsagen, rsagen, rsafill, asn12dsa, asn12rsa, dsa2pub, rsa2pub, dsa2ssh, rsa2ssh, rsa2x509 \- generate and format dsa and rsa keys
|
||||
.SH SYNOPSIS
|
||||
.PP
|
||||
.B dsagen
|
||||
[
|
||||
.B -t
|
||||
.I tag
|
||||
]
|
||||
.PP
|
||||
.B rsagen
|
||||
[
|
||||
.B -b
|
||||
.I nbits
|
||||
]
|
||||
[
|
||||
.B -t
|
||||
.I tag
|
||||
]
|
||||
.PP
|
||||
.B rsafill
|
||||
[
|
||||
.I file
|
||||
]
|
||||
.PP
|
||||
.B asn12dsa
|
||||
[
|
||||
.B -t
|
||||
.I tag
|
||||
]
|
||||
[
|
||||
.I file
|
||||
]
|
||||
.PP
|
||||
.B asn12rsa
|
||||
[
|
||||
.B -t
|
||||
.I tag
|
||||
]
|
||||
[
|
||||
.I file
|
||||
]
|
||||
.PP
|
||||
.B dsa2pub
|
||||
[
|
||||
.I file
|
||||
]
|
||||
.PP
|
||||
.B rsa2pub
|
||||
[
|
||||
.I file
|
||||
]
|
||||
.PP
|
||||
.B dsa2ssh
|
||||
[
|
||||
.I file
|
||||
]
|
||||
.PP
|
||||
.B rsa2ssh
|
||||
[
|
||||
.B -2
|
||||
]
|
||||
[
|
||||
.I file
|
||||
]
|
||||
.PP
|
||||
.B rsa2x509
|
||||
[
|
||||
.B -e
|
||||
.I expiretime
|
||||
]
|
||||
.I certinfo
|
||||
[
|
||||
.I file
|
||||
]
|
||||
.SH DESCRIPTION
|
||||
Plan 9 represents DSA and RSA keys as attribute-value pair lists
|
||||
prefixed with the string
|
||||
.BR key ;
|
||||
this is the generic key format used by
|
||||
.IR factotum (4).
|
||||
A full DSA private key has the following attributes:
|
||||
.TP
|
||||
.B proto
|
||||
must be
|
||||
.B dsa
|
||||
.TP
|
||||
.B p
|
||||
prime public modulus
|
||||
.TP
|
||||
.B q
|
||||
prime group order; divides
|
||||
.BR p -1
|
||||
.TP
|
||||
.B alpha
|
||||
group generator
|
||||
.TP
|
||||
.B key
|
||||
.BR alpha ^ !secret
|
||||
mod
|
||||
.B p
|
||||
.TP
|
||||
.B !secret
|
||||
the secret exponent
|
||||
.PD
|
||||
.PP
|
||||
A full RSA private key has the following attributes:
|
||||
.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 in both keys are in hexadecimal except RSA's
|
||||
.I size ,
|
||||
which is decimal.
|
||||
A public key omits the attributes beginning with
|
||||
.L ! .
|
||||
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 Dsagen
|
||||
prints a randomly generated DSA private key using the
|
||||
NIST-recommended algorithm.
|
||||
If
|
||||
.I tag
|
||||
is specified, it is printed between
|
||||
.B key
|
||||
and
|
||||
.BR proto=dsa ;
|
||||
typically,
|
||||
.I tag
|
||||
is a sequence of attribute-value comments describing the key.
|
||||
.PP
|
||||
.I Rsagen
|
||||
prints a randomly generated RSA private key
|
||||
whose
|
||||
.B n
|
||||
has exactly
|
||||
.I nbits
|
||||
(default 1024)
|
||||
significant bits.
|
||||
.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 Asn12dsa
|
||||
reads an DSA private key stored as ASN.1
|
||||
encoded in the binary Distinguished Encoding Rules (DER)
|
||||
and prints a Plan 9 DSA key,
|
||||
inserting
|
||||
.I tag
|
||||
exactly as
|
||||
.I dsagen
|
||||
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 `` DSA
|
||||
.B PRIVATE
|
||||
.BR KEY .''
|
||||
The command:
|
||||
.IP
|
||||
.EX
|
||||
pemdecode 'DSA PRIVATE KEY' | asn12dsa
|
||||
.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 DSA key.
|
||||
.PP
|
||||
.I Asn12rsa
|
||||
is similar but operates on RSA keys.
|
||||
.PP
|
||||
.I Dsa2pub
|
||||
reads a Plan 9 DSA public or private key,
|
||||
removes the private attributes, and prints the resulting public key.
|
||||
Comment attribtes are preserved.
|
||||
.PP
|
||||
.I Rsa2pub
|
||||
is similar but operates on RSA keys.
|
||||
.PP
|
||||
.I Dsa2ssh
|
||||
reads a Plan 9 DSA public or private key and prints the
|
||||
public portion in the format used by SSH version 2 (version 1 did not support DSA).
|
||||
If the key has a
|
||||
.B comment
|
||||
attribute, that comment is appended to the key.
|
||||
.PP
|
||||
.I Rsa2ssh
|
||||
is similar but operates on RSA keys.
|
||||
It decides whether to print in version 1 or version 2
|
||||
format by inspecting the
|
||||
.B service
|
||||
attribute.
|
||||
.PP
|
||||
.I Dsa2ssh
|
||||
and
|
||||
.I rsa2ssh
|
||||
are useful for generating SSH's
|
||||
.B authorized_keys
|
||||
file.
|
||||
.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
|
||||
rsa2x509 'C=US OU=''Bell Labs''' file |
|
||||
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
|
||||
rsagen -t 'service=tls owner=*' >key
|
||||
rsa2x509 'C=US CN=*.cs.bell-labs.com' key |
|
||||
pemencode CERTIFICATE >cert
|
||||
cat key >/mnt/factotum/ctl
|
||||
ip/httpd/httpd -c cert
|
||||
.EE
|
||||
.PP
|
||||
Generate a fresh set of SSH keys (only one is necessary),
|
||||
load them into factotum,
|
||||
and configure a remote Unix system to allow those keys for logins:
|
||||
.IP
|
||||
.EX
|
||||
rsagen -t 'service=ssh' >rsa1
|
||||
rsagen -t 'service=ssh-rsa' >rsa2
|
||||
dsagen -t 'service=ssh-dss' >dsa2
|
||||
.EE
|
||||
.PP
|
||||
Convert existing Unix SSH version 2 keys instead of generating new ones:
|
||||
.IP
|
||||
.EX
|
||||
cd $HOME/.ssh
|
||||
pemdecode 'DSA PRIVATE KEY' id_dsa | asn12dsa >dsa2
|
||||
pemdecode 'RSA PRIVATE KEY' id_rsa | asn12rsa >rsa2
|
||||
.EE
|
||||
.PP
|
||||
Load those keys into factotum:
|
||||
.IP
|
||||
.EX
|
||||
cat rsa1 rsa2 dsa2 | 9p write -l factotum/ctl
|
||||
.EE
|
||||
Allow use of those keys for logins on other systems:
|
||||
.IP
|
||||
.EX
|
||||
rsa2ssh rsa1 >auth.keys
|
||||
rsa2ssh rsa2 >>auth.keys
|
||||
dsa2ssh dsa2 >>auth.keys
|
||||
scp auth.keys unix:.ssh/authorized_keys
|
||||
.EE
|
||||
.SH SOURCE
|
||||
.B \*9/src/cmd/auth
|
||||
.SH "SEE ALSO
|
||||
.IR factotum (4),
|
||||
.IR pem (1),
|
||||
.IR ssh (1)
|
||||
.SH BUGS
|
||||
There are too many key formats.
|
||||
.PP
|
||||
There is no program to convert SSH version 1 RSA private keys.
|
||||
Loading…
Reference in a new issue