- OpenBSD CVS Sync
- djm@cvs.openbsd.org 2010/02/26 20:29:54
[PROTOCOL PROTOCOL.agent PROTOCOL.certkeys addrmatch.c auth-options.c]
[auth-options.h auth.h auth2-pubkey.c authfd.c dns.c dns.h hostfile.c]
[hostfile.h kex.h kexdhs.c kexgexs.c key.c key.h match.h monitor.c]
[myproposal.h servconf.c servconf.h ssh-add.c ssh-agent.c ssh-dss.c]
[ssh-keygen.1 ssh-keygen.c ssh-rsa.c ssh.1 ssh.c ssh2.h sshconnect.c]
[sshconnect2.c sshd.8 sshd.c sshd_config.5]
Add support for certificate key types for users and hosts.
OpenSSH certificate key types are not X.509 certificates, but a much
simpler format that encodes a public key, identity information and
some validity constraints and signs it with a CA key. CA keys are
regular SSH keys. This certificate style avoids the attack surface
of X.509 certificates and is very easy to deploy.
Certified host keys allow automatic acceptance of new host keys
when a CA certificate is marked as sh/known_hosts.
see VERIFYING HOST KEYS in ssh(1) for details.
Certified user keys allow authentication of users when the signing
CA key is marked as trusted in authorized_keys. See "AUTHORIZED_KEYS
FILE FORMAT" in sshd(8) for details.
Certificates are minted using ssh-keygen(1), documentation is in
the "CERTIFICATES" section of that manpage.
Documentation on the format of certificates is in the file
PROTOCOL.certkeys
feedback and ok markus@
diff --git a/ssh-keygen.1 b/ssh-keygen.1
index f09e1a1..772caf7 100644
--- a/ssh-keygen.1
+++ b/ssh-keygen.1
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ssh-keygen.1,v 1.83 2010/02/10 23:20:38 markus Exp $
+.\" $OpenBSD: ssh-keygen.1,v 1.84 2010/02/26 20:29:54 djm Exp $
.\"
.\" -*- nroff -*-
.\"
@@ -37,7 +37,7 @@
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd $Mdocdate: February 10 2010 $
+.Dd $Mdocdate: February 26 2010 $
.Dt SSH-KEYGEN 1
.Os
.Sh NAME
@@ -106,6 +106,14 @@
.Op Fl v
.Op Fl a Ar num_trials
.Op Fl W Ar generator
+.Nm ssh-keygen
+.Fl s Ar ca_key
+.Fl I Ar certificate_identity
+.Op Fl h
+.Op Fl n Ar principals
+.Op Fl O Ar constraint
+.Op Fl V Ar validity_interval
+.Ar
.Sh DESCRIPTION
.Nm
generates, manages and converts authentication keys for
@@ -245,6 +253,17 @@
be disclosed.
This option will not modify existing hashed hostnames and is therefore safe
to use on files that mix hashed and non-hashed names.
+.It Fl h
+When signing a key, create a host certificate instead of a user
+certificate.
+Please see the
+.Sx CERTIFICATES
+section for details.
+.It Fl I
+Specify the key identity when signing a public key.
+Please see the
+.Sx CERTIFICATES
+section for details.
.It Fl i
This option will read an unencrypted private (or public) key file
in SSH2-compatible format and print an OpenSSH compatible private
@@ -268,6 +287,67 @@
candidate moduli for DH-GEX.
.It Fl N Ar new_passphrase
Provides the new passphrase.
+.It Fl n Ar principals
+Specify one or more principals (user or host names) to be included in
+a certificate when signing a key.
+Multiple principals may be specified, separated by commas.
+Please see the
+.Sx CERTIFICATES
+section for details.
+.It Fl O Ar constraint
+Specify a certificate constraint when signing a key.
+This option may be specified multiple times.
+Please see the
+.Sx CERTIFICATES
+section for details.
+The constraints that are valid for user certificates are:
+.Bl -tag -width Ds
+.It Ic no-x11-forwarding
+Disable X11 forwarding. (permitted by default)
+.It Ic no-agent-forwarding
+Disable
+.Xr ssh-agent 1
+forwarding. (permitted by default)
+.It Ic no-port-forwarding
+Disable port forwarding. (permitted by default)
+.It Ic no-pty
+Disable PTY allocation. (permitted by default)
+.It Ic no-user-rc
+Disable execution of
+.Pa ~/.ssh/rc
+by
+.Xr sshd 8 .
+(permitted by default)
+.It Ic clear
+Clear all enabled permissions.
+This is useful for clearing the default set of permissions so permissions may
+be added individually.
+.It Ic permit-x11-forwarding
+Allows X11 forwarding.
+.It Ic permit-port-forwarding
+Allows port forwarding.
+.It Ic permit-pty
+Allows PTY allocation.
+.It Ic permit-user-rc
+Allows execution of
+.Pa ~/.ssh/rc
+by
+.Xr sshd 8 .
+.It Ic force-command=command
+Forces the execution of
+.Ar command
+instead of any shell or command specified by the user when
+the certificate is used for authentication.
+.It Ic source-address=address_list
+Restrict the source addresses from which the certificate is considered valid
+from.
+The
+.Ar address_list
+is a comma-separated list of one or more address/netmask pairs in CIDR
+format.
+.El
+.Pp
+At present, no constraints are valid for host keys.
.It Fl P Ar passphrase
Provides the (old) passphrase.
.It Fl p
@@ -297,6 +377,11 @@
for the specified public key file.
.It Fl S Ar start
Specify start point (in hex) when generating candidate moduli for DH-GEX.
+.It Fl s Ar ca_key
+Certify (sign) a public key using the specified CA key.
+Please see the
+.Sx CERTIFICATES
+section for details.
.It Fl T Ar output_file
Test DH group exchange candidate primes (generated using the
.Fl G
@@ -310,6 +395,29 @@
or
.Dq dsa
for protocol version 2.
+.It Fl V Ar validity_interval
+Specify a validity interval when signing a certificate.
+A validity interval may consist of a single time, indicating that the
+certificate is valid beginning now and expiring at that time, or may consist
+of two times separated by a colon to indicate an explicit time interval.
+The start time may be specified as a date in YYYYMMDD format, a time
+in YYYYMMDDHHMMSS format or a relative time (to the current time) consisting
+of a minus sign followed by a relative time in the format described in the
+.Sx TIME FORMATS
+section of
+.Xr ssh_config 5 .
+The end time may be specified as a YYYYMMDD date, a YYYYMMDDHHMMSS time or
+a relative time starting with a plus character.
+.Pp
+For example:
+.Dq +52w1d
+(valid from now to 52 weeks and one day from now),
+.Dq -4w:+4w
+(valid from four weeks ago to four weeks from now),
+.Dq 20100101123000:20110101123000
+(valid from 12:30 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011),
+.Dq -1d:20110101
+(valid from yesterday to midnight, January 1st, 2011).
.It Fl v
Verbose mode.
Causes
@@ -380,6 +488,72 @@
.Pa /etc/moduli .
It is important that this file contains moduli of a range of bit lengths and
that both ends of a connection share common moduli.
+.Sh CERTIFICATES
+.Nm
+supports signing of keys to produce certificates that may be used for
+user or host authentication.
+Certificates consist of a public key, some identity information, zero or
+more principal (user or host) names and an optional set of constraints that
+are signed by a Certification Authority (CA) key.
+Clients or servers may then trust only the CA key and verify its signature
+on a certificate rather than trusting many user/host keys.
+Note that OpenSSH certificates are a different, and much simpler, format to
+the X.509 certificates used in
+.Xr ssl 8 .
+.Pp
+.Nm
+supports two types of certificates: user and host.
+User certificates authenticate users to servers, whereas host certificates
+authenticate server hosts to users. To generate a user certificate:
+.Pp
+.Dl $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub
+.Pp
+The resultant certificate will be placed in
+.Pa /path/to/user_key_cert.pub .
+A host certificate requires the
+.Fl h
+option:
+.Pp
+.Dl $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub
+.Pp
+The host certificate will be output to
+.Pa /path/to/host_key_cert.pub .
+In both cases,
+.Ar key_id
+is a "key identifier" that is logged by the server when the certificate
+is used for authentication.
+.Pp
+Certificates may be limited to be valid for a set of principal (user/host)
+names.
+By default, generated certificates are valid for all users or hosts.
+To generate a certificate for a specified set of principals:
+.Pp
+.Dl $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub
+.Dl $ ssh-keygen -s ca_key -I key_id -h -n host.domain user_key.pub
+.Pp
+Additional limitations on the validity and use of user certificates may
+be specified through certificate constraints.
+A constrained certificate may disable features of the SSH session, may be
+valid only when presented from particular source addresses or may
+force the use of a specific command.
+For a list of valid certificate constraints, see the documentation for the
+.Fl O
+option above.
+.Pp
+Finally, certificates may be defined with a validity lifetime.
+The
+.Fl V
+option allows specification of certificate start and end times.
+A certificate that is presented at a time outside this range will not be
+considered valid.
+By default, certificates have a maximum validity interval.
+.Pp
+For certificates to be used for user or host authentication, the CA
+public key must be trusted by
+.Xr sshd 8
+or
+.Xr ssh 1 .
+Please refer to those manual pages for details.
.Sh FILES
.Bl -tag -width Ds
.It Pa ~/.ssh/identity