| This document describes a simple public-key certificate authentication | |
| system for use by SSH. | |
| Background | |
| ---------- | |
| The SSH protocol currently supports a simple public key authentication | |
| mechanism. Unlike other public key implementations, SSH eschews the use | |
| of X.509 certificates and uses raw keys. This approach has some benefits | |
| relating to simplicity of configuration and minimisation of attack | |
| surface, but it does not support the important use-cases of centrally | |
| managed, passwordless authentication and centrally certified host keys. | |
| These protocol extensions build on the simple public key authentication | |
| system already in SSH to allow certificate-based authentication. The | |
| certificates used are not traditional X.509 certificates, with numerous | |
| options and complex encoding rules, but something rather more minimal: a | |
| key, some identity information and usage options that have been signed | |
| with some other trusted key. | |
| A sshd server may be configured to allow authentication via certified | |
| keys, by extending the existing ~/.ssh/authorized_keys mechanism to | |
| allow specification of certification authority keys in addition to | |
| raw user keys. The ssh client will support automatic verification of | |
| acceptance of certified host keys, by adding a similar ability to | |
| specify CA keys in ~/.ssh/known_hosts. | |
| Certified keys are represented using new key types: | |
| ssh-rsa-cert-v01@openssh.com | |
| ssh-dss-cert-v01@openssh.com | |
| ecdsa-sha2-nistp256-cert-v01@openssh.com | |
| ecdsa-sha2-nistp384-cert-v01@openssh.com | |
| ecdsa-sha2-nistp521-cert-v01@openssh.com | |
| These include certification information along with the public key | |
| that is used to sign challenges. ssh-keygen performs the CA signing | |
| operation. | |
| Protocol extensions | |
| ------------------- | |
| The SSH wire protocol includes several extensibility mechanisms. | |
| These modifications shall take advantage of namespaced public key | |
| algorithm names to add support for certificate authentication without | |
| breaking the protocol - implementations that do not support the | |
| extensions will simply ignore them. | |
| Authentication using the new key formats described below proceeds | |
| using the existing SSH "publickey" authentication method described | |
| in RFC4252 section 7. | |
| New public key formats | |
| ---------------------- | |
| The certificate key types take a similar high-level format (note: data | |
| types and encoding are as per RFC4251 section 5). The serialised wire | |
| encoding of these certificates is also used for storing them on disk. | |
| #define SSH_CERT_TYPE_USER 1 | |
| #define SSH_CERT_TYPE_HOST 2 | |
| RSA certificate | |
| string "ssh-rsa-cert-v01@openssh.com" | |
| string nonce | |
| mpint e | |
| mpint n | |
| uint64 serial | |
| uint32 type | |
| string key id | |
| string valid principals | |
| uint64 valid after | |
| uint64 valid before | |
| string critical options | |
| string extensions | |
| string reserved | |
| string signature key | |
| string signature | |
| DSA certificate | |
| string "ssh-dss-cert-v01@openssh.com" | |
| string nonce | |
| mpint p | |
| mpint q | |
| mpint g | |
| mpint y | |
| uint64 serial | |
| uint32 type | |
| string key id | |
| string valid principals | |
| uint64 valid after | |
| uint64 valid before | |
| string critical options | |
| string extensions | |
| string reserved | |
| string signature key | |
| string signature | |
| ECDSA certificate | |
| string "ecdsa-sha2-nistp256@openssh.com" | | |
| "ecdsa-sha2-nistp384@openssh.com" | | |
| "ecdsa-sha2-nistp521@openssh.com" | |
| string nonce | |
| string curve | |
| string public_key | |
| uint64 serial | |
| uint32 type | |
| string key id | |
| string valid principals | |
| uint64 valid after | |
| uint64 valid before | |
| string critical options | |
| string extensions | |
| string reserved | |
| string signature key | |
| string signature | |
| The nonce field is a CA-provided random bitstring of arbitrary length | |
| (but typically 16 or 32 bytes) included to make attacks that depend on | |
| inducing collisions in the signature hash infeasible. | |
| e and n are the RSA exponent and public modulus respectively. | |
| p, q, g, y are the DSA parameters as described in FIPS-186-2. | |
| curve and public key are respectively the ECDSA "[identifier]" and "Q" | |
| defined in section 3.1 of RFC5656. | |
| serial is an optional certificate serial number set by the CA to | |
| provide an abbreviated way to refer to certificates from that CA. | |
| If a CA does not wish to number its certificates it must set this | |
| field to zero. | |
| type specifies whether this certificate is for identification of a user | |
| or a host using a SSH_CERT_TYPE_... value. | |
| key id is a free-form text field that is filled in by the CA at the time | |
| of signing; the intention is that the contents of this field are used to | |
| identify the identity principal in log messages. | |
| "valid principals" is a string containing zero or more principals as | |
| strings packed inside it. These principals list the names for which this | |
| certificate is valid; hostnames for SSH_CERT_TYPE_HOST certificates and | |
| usernames for SSH_CERT_TYPE_USER certificates. As a special case, a | |
| zero-length "valid principals" field means the certificate is valid for | |
| any principal of the specified type. XXX DNS wildcards? | |
| "valid after" and "valid before" specify a validity period for the | |
| certificate. Each represents a time in seconds since 1970-01-01 | |
| 00:00:00. A certificate is considered valid if: | |
| valid after <= current time < valid before | |
| criticial options is a set of zero or more key options encoded as | |
| below. All such options are "critical" in the sense that an implementation | |
| must refuse to authorise a key that has an unrecognised option. | |
| extensions is a set of zero or more optional extensions. These extensions | |
| are not critical, and an implementation that encounters one that it does | |
| not recognise may safely ignore it. | |
| The reserved field is currently unused and is ignored in this version of | |
| the protocol. | |
| signature key contains the CA key used to sign the certificate. | |
| The valid key types for CA keys are ssh-rsa, ssh-dss and the ECDSA types | |
| ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521. "Chained" | |
| certificates, where the signature key type is a certificate type itself | |
| are NOT supported. Note that it is possible for a RSA certificate key to | |
| be signed by a DSS or ECDSA CA key and vice-versa. | |
| signature is computed over all preceding fields from the initial string | |
| up to, and including the signature key. Signatures are computed and | |
| encoded according to the rules defined for the CA's public key algorithm | |
| (RFC4253 section 6.6 for ssh-rsa and ssh-dss, RFC5656 for the ECDSA | |
| types). | |
| Critical options | |
| ---------------- | |
| The critical options section of the certificate specifies zero or more | |
| options on the certificates validity. The format of this field | |
| is a sequence of zero or more tuples: | |
| string name | |
| string data | |
| Options must be lexically ordered by "name" if they appear in the | |
| sequence. | |
| The name field identifies the option and the data field encodes | |
| option-specific information (see below). All options are | |
| "critical", if an implementation does not recognise a option | |
| then the validating party should refuse to accept the certificate. | |
| The supported options and the contents and structure of their | |
| data fields are: | |
| Name Format Description | |
| ----------------------------------------------------------------------------- | |
| force-command string Specifies a command that is executed | |
| (replacing any the user specified on the | |
| ssh command-line) whenever this key is | |
| used for authentication. | |
| source-address string Comma-separated list of source addresses | |
| from which this certificate is accepted | |
| for authentication. Addresses are | |
| specified in CIDR format (nn.nn.nn.nn/nn | |
| or hhhh::hhhh/nn). | |
| If this option is not present then | |
| certificates may be presented from any | |
| source address. | |
| Extensions | |
| ---------- | |
| The extensions section of the certificate specifies zero or more | |
| non-critical certificate extensions. The encoding and ordering of | |
| extensions in this field is identical to that of the critical options. | |
| If an implementation does not recognise an extension, then it should | |
| ignore it. | |
| The supported extensions and the contents and structure of their data | |
| fields are: | |
| Name Format Description | |
| ----------------------------------------------------------------------------- | |
| permit-X11-forwarding empty Flag indicating that X11 forwarding | |
| should be permitted. X11 forwarding will | |
| be refused if this option is absent. | |
| permit-agent-forwarding empty Flag indicating that agent forwarding | |
| should be allowed. Agent forwarding | |
| must not be permitted unless this | |
| option is present. | |
| permit-port-forwarding empty Flag indicating that port-forwarding | |
| should be allowed. If this option is | |
| not present then no port forwarding will | |
| be allowed. | |
| permit-pty empty Flag indicating that PTY allocation | |
| should be permitted. In the absence of | |
| this option PTY allocation will be | |
| disabled. | |
| permit-user-rc empty Flag indicating that execution of | |
| ~/.ssh/rc should be permitted. Execution | |
| of this script will not be permitted if | |
| this option is not present. | |
| $OpenBSD: PROTOCOL.certkeys,v 1.8 2010/08/31 11:54:45 djm Exp $ |