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

1 files changed, 176 insertions, 2 deletions

diff --git a/ssh-keygen.1 b/ssh-keygen.1
index f09e1a100..772caf7ad 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 @@ but they do not reveal identifying information should the file's contents
 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 @@ Specify the amount of memory to use (in megabytes) when generating
 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 @@ Print the SSHFP fingerprint resource record named
 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 @@ for protocol version 1 and
 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 @@ Screened DH groups may be installed in
 .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