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