1This document describes a simple public-key certificate authentication 2system for use by SSH. 3 4Background 5---------- 6 7The SSH protocol currently supports a simple public key authentication 8mechanism. Unlike other public key implementations, SSH eschews the 9use of X.509 certificates and uses raw keys. This approach has some 10benefits relating to simplicity of configuration and minimisation 11of attack surface, but it does not support the important use-cases 12of centrally managed, passwordless authentication and centrally 13certified host keys. 14 15These protocol extensions build on the simple public key authentication 16system already in SSH to allow certificate-based authentication. 17The certificates used are not traditional X.509 certificates, with 18numerous options and complex encoding rules, but something rather 19more minimal: a key, some identity information and usage constraints 20that have been signed with some other trusted key. 21 22A sshd server may be configured to allow authentication via certified 23keys, by extending the existing ~/.ssh/authorized_keys mechanism 24to allow specification of certification authority keys in addition 25to raw user keys. The ssh client will support automatic verification 26of acceptance of certified host keys, by adding a similar ability 27to specify CA keys in ~/.ssh/known_hosts. 28 29Certified keys are represented using two new key types: 30ssh-rsa-cert-v00@openssh.com and ssh-dss-cert-v00@openssh.com that 31include certification information along with the public key that is used 32to sign challenges. ssh-keygen performs the CA signing operation. 33 34Protocol extensions 35------------------- 36 37The SSH wire protocol includes several extensibility mechanisms. 38These modifications shall take advantage of namespaced public key 39algorithm names to add support for certificate authentication without 40breaking the protocol - implementations that do not support the 41extensions will simply ignore them. 42 43Authentication using the new key formats described below proceeds 44using the existing SSH "publickey" authentication method described 45in RFC4252 section 7. 46 47New public key formats 48---------------------- 49 50The ssh-rsa-cert-v00@openssh.com and ssh-dss-cert-v00@openssh.com key 51types take a similar high-level format (note: data types and 52encoding are as per RFC4251 section 5). The serialised wire encoding of 53these certificates is also used for storing them on disk. 54 55#define SSH_CERT_TYPE_USER 1 56#define SSH_CERT_TYPE_HOST 2 57 58RSA certificate 59 60 string "ssh-rsa-cert-v00@openssh.com" 61 mpint e 62 mpint n 63 uint32 type 64 string key id 65 string valid principals 66 uint64 valid after 67 uint64 valid before 68 string constraints 69 string nonce 70 string reserved 71 string signature key 72 string signature 73 74DSA certificate 75 76 string "ssh-dss-cert-v00@openssh.com" 77 mpint p 78 mpint q 79 mpint g 80 mpint y 81 uint32 type 82 string key id 83 string valid principals 84 uint64 valid after 85 uint64 valid before 86 string constraints 87 string nonce 88 string reserved 89 string signature key 90 string signature 91 92e and n are the RSA exponent and public modulus respectively. 93 94p, q, g, y are the DSA parameters as described in FIPS-186-2. 95 96type specifies whether this certificate is for identification of a user 97or a host using a SSH_CERT_TYPE_... value. 98 99key id is a free-form text field that is filled in by the CA at the time 100of signing; the intention is that the contents of this field are used to 101identify the identity principal in log messages. 102 103"valid principals" is a string containing zero or more principals as 104strings packed inside it. These principals list the names for which this 105certificate is valid; hostnames for SSH_CERT_TYPE_HOST certificates and 106usernames for SSH_CERT_TYPE_USER certificates. As a special case, a 107zero-length "valid principals" field means the certificate is valid for 108any principal of the specified type. XXX DNS wildcards? 109 110"valid after" and "valid before" specify a validity period for the 111certificate. Each represents a time in seconds since 1970-01-01 11200:00:00. A certificate is considered valid if: 113 valid after <= current time < valid before 114 115constraints is a set of zero or more key constraints encoded as below. 116 117The nonce field is a CA-provided random bitstring of arbitrary length 118(but typically 16 or 32 bytes) included to make attacks that depend on 119inducing collisions in the signature hash infeasible. 120 121The reserved field is current unused and is ignored in this version of 122the protocol. 123 124signature key contains the CA key used to sign the certificate. 125The valid key types for CA keys are ssh-rsa and ssh-dss. "Chained" 126certificates, where the signature key type is a certificate type itself 127are NOT supported. Note that it is possible for a RSA certificate key to 128be signed by a DSS CA key and vice-versa. 129 130signature is computed over all preceding fields from the initial string 131up to, and including the signature key. Signatures are computed and 132encoded according to the rules defined for the CA's public key algorithm 133(RFC4253 section 6.6 for ssh-rsa and ssh-dss). 134 135Constraints 136----------- 137 138The constraints section of the certificate specifies zero or more 139constraints on the certificates validity. The format of this field 140is a sequence of zero or more tuples: 141 142 string name 143 string data 144 145The name field identifies the constraint and the data field encodes 146constraint-specific information (see below). All constraints are 147"critical", if an implementation does not recognise a constraint 148then the validating party should refuse to accept the certificate. 149 150The supported constraints and the contents and structure of their 151data fields are: 152 153Name Format Description 154----------------------------------------------------------------------------- 155force-command string Specifies a command that is executed 156 (replacing any the user specified on the 157 ssh command-line) whenever this key is 158 used for authentication. 159 160permit-X11-forwarding empty Flag indicating that X11 forwarding 161 should be permitted. X11 forwarding will 162 be refused if this constraint is absent. 163 164permit-agent-forwarding empty Flag indicating that agent forwarding 165 should be allowed. Agent forwarding 166 must not be permitted unless this 167 constraint is present. 168 169permit-port-forwarding empty Flag indicating that port-forwarding 170 should be allowed. If this constraint is 171 not present then no port forwarding will 172 be allowed. 173 174permit-pty empty Flag indicating that PTY allocation 175 should be permitted. In the absence of 176 this constraint PTY allocation will be 177 disabled. 178 179permit-user-rc empty Flag indicating that execution of 180 ~/.ssh/rc should be permitted. Execution 181 of this script will not be permitted if 182 this constraint is not present. 183 184source-address string Comma-separated list of source addresses 185 from which this certificate is accepted 186 for authentication. Addresses are 187 specified in CIDR format (nn.nn.nn.nn/nn 188 or hhhh::hhhh/nn). 189 If this constraint is not present then 190 certificates may be presented from any 191 source address. 192 193$OpenBSD: PROTOCOL.certkeys,v 1.3 2010/03/03 22:50:40 djm Exp $ 194