| PROTOCOL.certkeys (215116) | PROTOCOL.certkeys (221420) |
|---|---|
| 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 | 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. | 8mechanism. Unlike other public key implementations, SSH eschews the use 9of X.509 certificates and uses raw keys. This approach has some benefits 10relating to simplicity of configuration and minimisation of attack 11surface, but it does not support the important use-cases of centrally 12managed, passwordless authentication and centrally certified host keys. |
| 14 15These protocol extensions build on the simple public key authentication | 13 14These 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 options 20that have been signed with some other trusted key. | 15system already in SSH to allow certificate-based authentication. The 16certificates used are not traditional X.509 certificates, with numerous 17options and complex encoding rules, but something rather more minimal: a 18key, some identity information and usage options that have been signed 19with some other trusted key. |
| 21 22A sshd server may be configured to allow authentication via certified | 20 21A 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. | 22keys, by extending the existing ~/.ssh/authorized_keys mechanism to 23allow specification of certification authority keys in addition to 24raw user keys. The ssh client will support automatic verification of 25acceptance of certified host keys, by adding a similar ability to 26specify CA keys in ~/.ssh/known_hosts. |
| 28 | 27 |
| 29Certified keys are represented using two new key types: 30ssh-rsa-cert-v01@openssh.com and ssh-dss-cert-v01@openssh.com that 31include certification information along with the public key that is used 32to sign challenges. ssh-keygen performs the CA signing operation. | 28Certified keys are represented using new key types: |
| 33 | 29 |
| 30 ssh-rsa-cert-v01@openssh.com 31 ssh-dss-cert-v01@openssh.com 32 ecdsa-sha2-nistp256-cert-v01@openssh.com 33 ecdsa-sha2-nistp384-cert-v01@openssh.com 34 ecdsa-sha2-nistp521-cert-v01@openssh.com 35 36These include certification information along with the public key 37that is used to sign challenges. ssh-keygen performs the CA signing 38operation. 39 |
|
| 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 | 40Protocol extensions 41------------------- 42 43The SSH wire protocol includes several extensibility mechanisms. 44These modifications shall take advantage of namespaced public key 45algorithm names to add support for certificate authentication without 46breaking the protocol - implementations that do not support the 47extensions will simply ignore them. 48 49Authentication using the new key formats described below proceeds 50using the existing SSH "publickey" authentication method described 51in RFC4252 section 7. 52 53New public key formats 54---------------------- 55 |
| 50The ssh-rsa-cert-v01@openssh.com and ssh-dss-cert-v01@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. | 56The certificate key types take a similar high-level format (note: data 57types and encoding are as per RFC4251 section 5). The serialised wire 58encoding of 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 58RSA certificate 59 60 string "ssh-rsa-cert-v01@openssh.com" 61 string nonce --- 26 unchanged lines hidden (view full) --- 88 uint64 valid after 89 uint64 valid before 90 string critical options 91 string extensions 92 string reserved 93 string signature key 94 string signature 95 | 59 60#define SSH_CERT_TYPE_USER 1 61#define SSH_CERT_TYPE_HOST 2 62 63RSA certificate 64 65 string "ssh-rsa-cert-v01@openssh.com" 66 string nonce --- 26 unchanged lines hidden (view full) --- 93 uint64 valid after 94 uint64 valid before 95 string critical options 96 string extensions 97 string reserved 98 string signature key 99 string signature 100 |
| 101ECDSA certificate 102 103 string "ecdsa-sha2-nistp256@openssh.com" | 104 "ecdsa-sha2-nistp384@openssh.com" | 105 "ecdsa-sha2-nistp521@openssh.com" 106 string nonce 107 string curve 108 string public_key 109 uint64 serial 110 uint32 type 111 string key id 112 string valid principals 113 uint64 valid after 114 uint64 valid before 115 string critical options 116 string extensions 117 string reserved 118 string signature key 119 string signature 120 |
|
| 96The 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 98inducing collisions in the signature hash infeasible. 99 100e and n are the RSA exponent and public modulus respectively. 101 102p, q, g, y are the DSA parameters as described in FIPS-186-2. 103 | 121The nonce field is a CA-provided random bitstring of arbitrary length 122(but typically 16 or 32 bytes) included to make attacks that depend on 123inducing collisions in the signature hash infeasible. 124 125e and n are the RSA exponent and public modulus respectively. 126 127p, q, g, y are the DSA parameters as described in FIPS-186-2. 128 |
| 129curve and public key are respectively the ECDSA "[identifier]" and "Q" 130defined in section 3.1 of RFC5656. 131 |
|
| 104serial is an optional certificate serial number set by the CA to 105provide an abbreviated way to refer to certificates from that CA. 106If a CA does not wish to number its certificates it must set this 107field to zero. 108 109type specifies whether this certificate is for identification of a user 110or a host using a SSH_CERT_TYPE_... value. 111 --- 6 unchanged lines hidden (view full) --- 118certificate is valid; hostnames for SSH_CERT_TYPE_HOST certificates and 119usernames for SSH_CERT_TYPE_USER certificates. As a special case, a 120zero-length "valid principals" field means the certificate is valid for 121any principal of the specified type. XXX DNS wildcards? 122 123"valid after" and "valid before" specify a validity period for the 124certificate. Each represents a time in seconds since 1970-01-01 12500:00:00. A certificate is considered valid if: | 132serial is an optional certificate serial number set by the CA to 133provide an abbreviated way to refer to certificates from that CA. 134If a CA does not wish to number its certificates it must set this 135field to zero. 136 137type specifies whether this certificate is for identification of a user 138or a host using a SSH_CERT_TYPE_... value. 139 --- 6 unchanged lines hidden (view full) --- 146certificate is valid; hostnames for SSH_CERT_TYPE_HOST certificates and 147usernames for SSH_CERT_TYPE_USER certificates. As a special case, a 148zero-length "valid principals" field means the certificate is valid for 149any principal of the specified type. XXX DNS wildcards? 150 151"valid after" and "valid before" specify a validity period for the 152certificate. Each represents a time in seconds since 1970-01-01 15300:00:00. A certificate is considered valid if: |
| 126 valid after <= current time < valid before | |
| 127 | 154 |
| 155 valid after <= current time < valid before 156 |
|
| 128criticial options is a set of zero or more key options encoded as 129below. All such options are "critical" in the sense that an implementation 130must refuse to authorise a key that has an unrecognised option. 131 132extensions is a set of zero or more optional extensions. These extensions 133are not critical, and an implementation that encounters one that it does 134not recognise may safely ignore it. 135 136The reserved field is currently unused and is ignored in this version of 137the protocol. 138 139signature key contains the CA key used to sign the certificate. | 157criticial options is a set of zero or more key options encoded as 158below. All such options are "critical" in the sense that an implementation 159must refuse to authorise a key that has an unrecognised option. 160 161extensions is a set of zero or more optional extensions. These extensions 162are not critical, and an implementation that encounters one that it does 163not recognise may safely ignore it. 164 165The reserved field is currently unused and is ignored in this version of 166the protocol. 167 168signature key contains the CA key used to sign the certificate. |
| 140The valid key types for CA keys are ssh-rsa and ssh-dss. "Chained" | 169The valid key types for CA keys are ssh-rsa, ssh-dss and the ECDSA types 170ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521. "Chained" |
| 141certificates, where the signature key type is a certificate type itself 142are NOT supported. Note that it is possible for a RSA certificate key to | 171certificates, where the signature key type is a certificate type itself 172are NOT supported. Note that it is possible for a RSA certificate key to |
| 143be signed by a DSS CA key and vice-versa. | 173be signed by a DSS or ECDSA CA key and vice-versa. |
| 144 145signature is computed over all preceding fields from the initial string 146up to, and including the signature key. Signatures are computed and 147encoded according to the rules defined for the CA's public key algorithm | 174 175signature is computed over all preceding fields from the initial string 176up to, and including the signature key. Signatures are computed and 177encoded according to the rules defined for the CA's public key algorithm |
| 148(RFC4253 section 6.6 for ssh-rsa and ssh-dss). | 178(RFC4253 section 6.6 for ssh-rsa and ssh-dss, RFC5656 for the ECDSA 179types). |
| 149 150Critical options 151---------------- 152 153The critical options section of the certificate specifies zero or more 154options on the certificates validity. The format of this field 155is a sequence of zero or more tuples: 156 --- 60 unchanged lines hidden (view full) --- 217 this option PTY allocation will be 218 disabled. 219 220permit-user-rc empty Flag indicating that execution of 221 ~/.ssh/rc should be permitted. Execution 222 of this script will not be permitted if 223 this option is not present. 224 | 180 181Critical options 182---------------- 183 184The critical options section of the certificate specifies zero or more 185options on the certificates validity. The format of this field 186is a sequence of zero or more tuples: 187 --- 60 unchanged lines hidden (view full) --- 248 this option PTY allocation will be 249 disabled. 250 251permit-user-rc empty Flag indicating that execution of 252 ~/.ssh/rc should be permitted. Execution 253 of this script will not be permitted if 254 this option is not present. 255 |
| 225$OpenBSD: PROTOCOL.certkeys,v 1.7 2010/08/04 05:40:39 djm Exp $ | 256$OpenBSD: PROTOCOL.certkeys,v 1.8 2010/08/31 11:54:45 djm Exp $ |