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 |
Damien Miller | eb8b60e | 2010-08-31 22:41:14 +1000 | [diff] [blame] | 8 | mechanism. Unlike other public key implementations, SSH eschews the use |
| 9 | of X.509 certificates and uses raw keys. This approach has some benefits |
| 10 | relating to simplicity of configuration and minimisation of attack |
| 11 | surface, but it does not support the important use-cases of centrally |
| 12 | managed, passwordless authentication and centrally certified host keys. |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 13 | |
| 14 | These protocol extensions build on the simple public key authentication |
Damien Miller | eb8b60e | 2010-08-31 22:41:14 +1000 | [diff] [blame] | 15 | system already in SSH to allow certificate-based authentication. The |
| 16 | certificates used are not traditional X.509 certificates, with numerous |
| 17 | options and complex encoding rules, but something rather more minimal: a |
| 18 | key, some identity information and usage options that have been signed |
| 19 | with some other trusted key. |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 20 | |
| 21 | A sshd server may be configured to allow authentication via certified |
Damien Miller | eb8b60e | 2010-08-31 22:41:14 +1000 | [diff] [blame] | 22 | keys, by extending the existing ~/.ssh/authorized_keys mechanism to |
| 23 | allow specification of certification authority keys in addition to |
| 24 | raw user keys. The ssh client will support automatic verification of |
| 25 | acceptance of certified host keys, by adding a similar ability to |
| 26 | specify CA keys in ~/.ssh/known_hosts. |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 27 | |
djm@openbsd.org | 4ba0d54 | 2018-07-03 11:39:54 +0000 | [diff] [blame] | 28 | All certificate types include certification information along with the |
| 29 | public key that is used to sign challenges. In OpenSSH, ssh-keygen |
| 30 | performs the CA signing operation. |
| 31 | |
Damien Miller | eb8b60e | 2010-08-31 22:41:14 +1000 | [diff] [blame] | 32 | Certified keys are represented using new key types: |
| 33 | |
| 34 | ssh-rsa-cert-v01@openssh.com |
| 35 | ssh-dss-cert-v01@openssh.com |
| 36 | ecdsa-sha2-nistp256-cert-v01@openssh.com |
| 37 | ecdsa-sha2-nistp384-cert-v01@openssh.com |
| 38 | ecdsa-sha2-nistp521-cert-v01@openssh.com |
| 39 | |
djm@openbsd.org | 4ba0d54 | 2018-07-03 11:39:54 +0000 | [diff] [blame] | 40 | Two additional types exist for RSA certificates to force use of |
| 41 | SHA-2 signatures (SHA-256 and SHA-512 respectively): |
| 42 | |
| 43 | rsa-sha2-256-cert-v01@openssh.com |
| 44 | rsa-sha2-512-cert-v01@openssh.com |
| 45 | |
| 46 | These RSA/SHA-2 types should not appear in keys at rest or transmitted |
| 47 | on their wire, but do appear in a SSH_MSG_KEXINIT's host-key algorithms |
| 48 | field or in the "public key algorithm name" field of a "publickey" |
| 49 | SSH_USERAUTH_REQUEST to indicate that the signature will use the |
| 50 | specified algorithm. |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 51 | |
| 52 | Protocol extensions |
| 53 | ------------------- |
| 54 | |
| 55 | The SSH wire protocol includes several extensibility mechanisms. |
| 56 | These modifications shall take advantage of namespaced public key |
| 57 | algorithm names to add support for certificate authentication without |
| 58 | breaking the protocol - implementations that do not support the |
| 59 | extensions will simply ignore them. |
| 60 | |
| 61 | Authentication using the new key formats described below proceeds |
| 62 | using the existing SSH "publickey" authentication method described |
| 63 | in RFC4252 section 7. |
| 64 | |
| 65 | New public key formats |
| 66 | ---------------------- |
| 67 | |
Damien Miller | eb8b60e | 2010-08-31 22:41:14 +1000 | [diff] [blame] | 68 | The certificate key types take a similar high-level format (note: data |
| 69 | types and encoding are as per RFC4251 section 5). The serialised wire |
| 70 | encoding of these certificates is also used for storing them on disk. |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 71 | |
| 72 | #define SSH_CERT_TYPE_USER 1 |
| 73 | #define SSH_CERT_TYPE_HOST 2 |
| 74 | |
| 75 | RSA certificate |
| 76 | |
Damien Miller | 4e270b0 | 2010-04-16 15:56:21 +1000 | [diff] [blame] | 77 | string "ssh-rsa-cert-v01@openssh.com" |
| 78 | string nonce |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 79 | mpint e |
| 80 | mpint n |
Damien Miller | 4e270b0 | 2010-04-16 15:56:21 +1000 | [diff] [blame] | 81 | uint64 serial |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 82 | uint32 type |
| 83 | string key id |
| 84 | string valid principals |
| 85 | uint64 valid after |
| 86 | uint64 valid before |
Damien Miller | 4e270b0 | 2010-04-16 15:56:21 +1000 | [diff] [blame] | 87 | string critical options |
| 88 | string extensions |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 89 | string reserved |
| 90 | string signature key |
| 91 | string signature |
| 92 | |
| 93 | DSA certificate |
| 94 | |
Damien Miller | 4e270b0 | 2010-04-16 15:56:21 +1000 | [diff] [blame] | 95 | string "ssh-dss-cert-v01@openssh.com" |
| 96 | string nonce |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 97 | mpint p |
| 98 | mpint q |
| 99 | mpint g |
| 100 | mpint y |
Damien Miller | 4e270b0 | 2010-04-16 15:56:21 +1000 | [diff] [blame] | 101 | uint64 serial |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 102 | uint32 type |
| 103 | string key id |
| 104 | string valid principals |
| 105 | uint64 valid after |
| 106 | uint64 valid before |
Damien Miller | 4e270b0 | 2010-04-16 15:56:21 +1000 | [diff] [blame] | 107 | string critical options |
| 108 | string extensions |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 109 | string reserved |
| 110 | string signature key |
| 111 | string signature |
| 112 | |
Damien Miller | eb8b60e | 2010-08-31 22:41:14 +1000 | [diff] [blame] | 113 | ECDSA certificate |
| 114 | |
djm@openbsd.org@openbsd.org | c357eed | 2017-11-03 02:32:19 +0000 | [diff] [blame] | 115 | string "ecdsa-sha2-nistp256-cert-v01@openssh.com" | |
| 116 | "ecdsa-sha2-nistp384-cert-v01@openssh.com" | |
| 117 | "ecdsa-sha2-nistp521-cert-v01@openssh.com" |
Damien Miller | eb8b60e | 2010-08-31 22:41:14 +1000 | [diff] [blame] | 118 | string nonce |
| 119 | string curve |
| 120 | string public_key |
| 121 | uint64 serial |
| 122 | uint32 type |
| 123 | string key id |
| 124 | string valid principals |
| 125 | uint64 valid after |
| 126 | uint64 valid before |
| 127 | string critical options |
| 128 | string extensions |
| 129 | string reserved |
| 130 | string signature key |
| 131 | string signature |
| 132 | |
djm@openbsd.org | fa58208 | 2016-05-03 10:27:59 +0000 | [diff] [blame] | 133 | ED25519 certificate |
| 134 | |
| 135 | string "ssh-ed25519-cert-v01@openssh.com" |
| 136 | string nonce |
| 137 | string pk |
| 138 | uint64 serial |
| 139 | uint32 type |
| 140 | string key id |
| 141 | string valid principals |
| 142 | uint64 valid after |
| 143 | uint64 valid before |
| 144 | string critical options |
| 145 | string extensions |
| 146 | string reserved |
| 147 | string signature key |
| 148 | string signature |
| 149 | |
Damien Miller | 4e270b0 | 2010-04-16 15:56:21 +1000 | [diff] [blame] | 150 | The nonce field is a CA-provided random bitstring of arbitrary length |
| 151 | (but typically 16 or 32 bytes) included to make attacks that depend on |
| 152 | inducing collisions in the signature hash infeasible. |
| 153 | |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 154 | e and n are the RSA exponent and public modulus respectively. |
| 155 | |
| 156 | p, q, g, y are the DSA parameters as described in FIPS-186-2. |
| 157 | |
Damien Miller | eb8b60e | 2010-08-31 22:41:14 +1000 | [diff] [blame] | 158 | curve and public key are respectively the ECDSA "[identifier]" and "Q" |
| 159 | defined in section 3.1 of RFC5656. |
| 160 | |
djm@openbsd.org | fa58208 | 2016-05-03 10:27:59 +0000 | [diff] [blame] | 161 | pk is the encoded Ed25519 public key as defined by |
| 162 | draft-josefsson-eddsa-ed25519-03. |
| 163 | |
Damien Miller | 4e270b0 | 2010-04-16 15:56:21 +1000 | [diff] [blame] | 164 | serial is an optional certificate serial number set by the CA to |
| 165 | provide an abbreviated way to refer to certificates from that CA. |
Damien Miller | 2725c21 | 2010-05-10 11:56:14 +1000 | [diff] [blame] | 166 | 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] | 167 | field to zero. |
| 168 | |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 169 | type specifies whether this certificate is for identification of a user |
| 170 | or a host using a SSH_CERT_TYPE_... value. |
| 171 | |
| 172 | key id is a free-form text field that is filled in by the CA at the time |
| 173 | of signing; the intention is that the contents of this field are used to |
| 174 | identify the identity principal in log messages. |
| 175 | |
| 176 | "valid principals" is a string containing zero or more principals as |
| 177 | strings packed inside it. These principals list the names for which this |
| 178 | certificate is valid; hostnames for SSH_CERT_TYPE_HOST certificates and |
| 179 | usernames for SSH_CERT_TYPE_USER certificates. As a special case, a |
| 180 | zero-length "valid principals" field means the certificate is valid for |
djm@openbsd.org | fa58208 | 2016-05-03 10:27:59 +0000 | [diff] [blame] | 181 | any principal of the specified type. |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 182 | |
| 183 | "valid after" and "valid before" specify a validity period for the |
| 184 | certificate. Each represents a time in seconds since 1970-01-01 |
| 185 | 00:00:00. A certificate is considered valid if: |
Damien Miller | eb8b60e | 2010-08-31 22:41:14 +1000 | [diff] [blame] | 186 | |
| 187 | valid after <= current time < valid before |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 188 | |
djm@openbsd.org | 001aa55 | 2018-04-10 00:10:49 +0000 | [diff] [blame] | 189 | critical options is a set of zero or more key options encoded as |
Damien Miller | 4e270b0 | 2010-04-16 15:56:21 +1000 | [diff] [blame] | 190 | below. All such options are "critical" in the sense that an implementation |
| 191 | must refuse to authorise a key that has an unrecognised option. |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 192 | |
Damien Miller | 4e270b0 | 2010-04-16 15:56:21 +1000 | [diff] [blame] | 193 | extensions is a set of zero or more optional extensions. These extensions |
| 194 | are not critical, and an implementation that encounters one that it does |
Damien Miller | d0e4a8e | 2010-05-21 14:58:32 +1000 | [diff] [blame] | 195 | not recognise may safely ignore it. |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 196 | |
Damien Miller | 48348fc | 2012-04-22 11:08:30 +1000 | [diff] [blame] | 197 | Generally, critical options are used to control features that restrict |
| 198 | access where extensions are used to enable features that grant access. |
| 199 | This ensures that certificates containing unknown restrictions do not |
| 200 | inadvertently grant access while allowing new protocol features to be |
| 201 | enabled via extensions without breaking certificates' backwards |
| 202 | compatibility. |
| 203 | |
Damien Miller | 4e270b0 | 2010-04-16 15:56:21 +1000 | [diff] [blame] | 204 | 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] | 205 | the protocol. |
| 206 | |
djm@openbsd.org | adb47ce | 2017-05-16 16:54:05 +0000 | [diff] [blame] | 207 | The signature key field contains the CA key used to sign the |
| 208 | certificate. The valid key types for CA keys are ssh-rsa, |
| 209 | ssh-dss, ssh-ed25519 and the ECDSA types ecdsa-sha2-nistp256, |
| 210 | ecdsa-sha2-nistp384, ecdsa-sha2-nistp521. "Chained" certificates, where |
| 211 | the signature key type is a certificate type itself are NOT supported. |
| 212 | Note that it is possible for a RSA certificate key to be signed by a |
| 213 | Ed25519 or ECDSA CA key and vice-versa. |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 214 | |
| 215 | signature is computed over all preceding fields from the initial string |
| 216 | up to, and including the signature key. Signatures are computed and |
| 217 | encoded according to the rules defined for the CA's public key algorithm |
Damien Miller | eb8b60e | 2010-08-31 22:41:14 +1000 | [diff] [blame] | 218 | (RFC4253 section 6.6 for ssh-rsa and ssh-dss, RFC5656 for the ECDSA |
djm@openbsd.org | fa58208 | 2016-05-03 10:27:59 +0000 | [diff] [blame] | 219 | types), and draft-josefsson-eddsa-ed25519-03 for Ed25519. |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 220 | |
Damien Miller | 4e270b0 | 2010-04-16 15:56:21 +1000 | [diff] [blame] | 221 | Critical options |
| 222 | ---------------- |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 223 | |
Damien Miller | 4e270b0 | 2010-04-16 15:56:21 +1000 | [diff] [blame] | 224 | The critical options section of the certificate specifies zero or more |
| 225 | options on the certificates validity. The format of this field |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 226 | is a sequence of zero or more tuples: |
| 227 | |
| 228 | string name |
| 229 | string data |
| 230 | |
Damien Miller | 1da6388 | 2010-08-05 13:03:51 +1000 | [diff] [blame] | 231 | Options must be lexically ordered by "name" if they appear in the |
Damien Miller | 48348fc | 2012-04-22 11:08:30 +1000 | [diff] [blame] | 232 | sequence. Each named option may only appear once in a certificate. |
Damien Miller | 1da6388 | 2010-08-05 13:03:51 +1000 | [diff] [blame] | 233 | |
Damien Miller | 4e270b0 | 2010-04-16 15:56:21 +1000 | [diff] [blame] | 234 | The name field identifies the option and the data field encodes |
| 235 | option-specific information (see below). All options are |
| 236 | "critical", if an implementation does not recognise a option |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 237 | then the validating party should refuse to accept the certificate. |
| 238 | |
djm@openbsd.org | d40dbdc | 2017-05-31 04:29:44 +0000 | [diff] [blame] | 239 | Custom options should append the originating author or organisation's |
| 240 | domain name to the option name, e.g. "my-option@example.com". |
| 241 | |
djm@openbsd.org | fa58208 | 2016-05-03 10:27:59 +0000 | [diff] [blame] | 242 | No critical options are defined for host certificates at present. The |
| 243 | supported user certificate options and the contents and structure of |
| 244 | their data fields are: |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 245 | |
| 246 | Name Format Description |
| 247 | ----------------------------------------------------------------------------- |
| 248 | force-command string Specifies a command that is executed |
| 249 | (replacing any the user specified on the |
| 250 | ssh command-line) whenever this key is |
| 251 | used for authentication. |
| 252 | |
Damien Miller | d0e4a8e | 2010-05-21 14:58:32 +1000 | [diff] [blame] | 253 | source-address string Comma-separated list of source addresses |
| 254 | from which this certificate is accepted |
| 255 | for authentication. Addresses are |
| 256 | specified in CIDR format (nn.nn.nn.nn/nn |
| 257 | or hhhh::hhhh/nn). |
| 258 | If this option is not present then |
| 259 | certificates may be presented from any |
| 260 | source address. |
| 261 | |
| 262 | Extensions |
| 263 | ---------- |
| 264 | |
| 265 | The extensions section of the certificate specifies zero or more |
Damien Miller | 1da6388 | 2010-08-05 13:03:51 +1000 | [diff] [blame] | 266 | non-critical certificate extensions. The encoding and ordering of |
Damien Miller | 48348fc | 2012-04-22 11:08:30 +1000 | [diff] [blame] | 267 | extensions in this field is identical to that of the critical options, |
| 268 | as is the requirement that each name appear only once. |
| 269 | |
Damien Miller | 1da6388 | 2010-08-05 13:03:51 +1000 | [diff] [blame] | 270 | If an implementation does not recognise an extension, then it should |
| 271 | ignore it. |
Damien Miller | d0e4a8e | 2010-05-21 14:58:32 +1000 | [diff] [blame] | 272 | |
djm@openbsd.org | d40dbdc | 2017-05-31 04:29:44 +0000 | [diff] [blame] | 273 | Custom options should append the originating author or organisation's |
| 274 | domain name to the option name, e.g. "my-option@example.com". |
| 275 | |
djm@openbsd.org | fa58208 | 2016-05-03 10:27:59 +0000 | [diff] [blame] | 276 | No extensions are defined for host certificates at present. The |
| 277 | supported user certificate extensions and the contents and structure of |
| 278 | their data fields are: |
Damien Miller | d0e4a8e | 2010-05-21 14:58:32 +1000 | [diff] [blame] | 279 | |
| 280 | Name Format Description |
| 281 | ----------------------------------------------------------------------------- |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 282 | permit-X11-forwarding empty Flag indicating that X11 forwarding |
| 283 | should be permitted. X11 forwarding will |
Damien Miller | 4e270b0 | 2010-04-16 15:56:21 +1000 | [diff] [blame] | 284 | be refused if this option is absent. |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 285 | |
| 286 | permit-agent-forwarding empty Flag indicating that agent forwarding |
| 287 | should be allowed. Agent forwarding |
| 288 | must not be permitted unless this |
Damien Miller | 4e270b0 | 2010-04-16 15:56:21 +1000 | [diff] [blame] | 289 | option is present. |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 290 | |
| 291 | permit-port-forwarding empty Flag indicating that port-forwarding |
Damien Miller | 4e270b0 | 2010-04-16 15:56:21 +1000 | [diff] [blame] | 292 | should be allowed. If this option is |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 293 | not present then no port forwarding will |
| 294 | be allowed. |
| 295 | |
| 296 | permit-pty empty Flag indicating that PTY allocation |
| 297 | should be permitted. In the absence of |
Damien Miller | 4e270b0 | 2010-04-16 15:56:21 +1000 | [diff] [blame] | 298 | this option PTY allocation will be |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 299 | disabled. |
| 300 | |
| 301 | permit-user-rc empty Flag indicating that execution of |
| 302 | ~/.ssh/rc should be permitted. Execution |
| 303 | of this script will not be permitted if |
Damien Miller | 4e270b0 | 2010-04-16 15:56:21 +1000 | [diff] [blame] | 304 | this option is not present. |
Damien Miller | 0a80ca1 | 2010-02-27 07:55:05 +1100 | [diff] [blame] | 305 | |
djm@openbsd.org | 4ba0d54 | 2018-07-03 11:39:54 +0000 | [diff] [blame] | 306 | $OpenBSD: PROTOCOL.certkeys,v 1.15 2018/07/03 11:39:54 djm Exp $ |