1856ea928SPeter AvalosThis document describes a simple public-key certificate authentication 2856ea928SPeter Avalossystem for use by SSH. 3856ea928SPeter Avalos 4856ea928SPeter AvalosBackground 5856ea928SPeter Avalos---------- 6856ea928SPeter Avalos 7856ea928SPeter AvalosThe SSH protocol currently supports a simple public key authentication 89f304aafSPeter Avalosmechanism. Unlike other public key implementations, SSH eschews the use 99f304aafSPeter Avalosof X.509 certificates and uses raw keys. This approach has some benefits 109f304aafSPeter Avalosrelating to simplicity of configuration and minimisation of attack 119f304aafSPeter Avalossurface, but it does not support the important use-cases of centrally 129f304aafSPeter Avalosmanaged, passwordless authentication and centrally certified host keys. 13856ea928SPeter Avalos 14856ea928SPeter AvalosThese protocol extensions build on the simple public key authentication 159f304aafSPeter Avalossystem already in SSH to allow certificate-based authentication. The 169f304aafSPeter Avaloscertificates used are not traditional X.509 certificates, with numerous 179f304aafSPeter Avalosoptions and complex encoding rules, but something rather more minimal: a 189f304aafSPeter Avaloskey, some identity information and usage options that have been signed 199f304aafSPeter Avaloswith some other trusted key. 20856ea928SPeter Avalos 21856ea928SPeter AvalosA sshd server may be configured to allow authentication via certified 229f304aafSPeter Avaloskeys, by extending the existing ~/.ssh/authorized_keys mechanism to 239f304aafSPeter Avalosallow specification of certification authority keys in addition to 249f304aafSPeter Avalosraw user keys. The ssh client will support automatic verification of 259f304aafSPeter Avalosacceptance of certified host keys, by adding a similar ability to 269f304aafSPeter Avalosspecify CA keys in ~/.ssh/known_hosts. 27856ea928SPeter Avalos 28664f4763SzrjAll certificate types include certification information along with the 29664f4763Szrjpublic key that is used to sign challenges. In OpenSSH, ssh-keygen 30664f4763Szrjperforms the CA signing operation. 31664f4763Szrj 329f304aafSPeter AvalosCertified keys are represented using new key types: 339f304aafSPeter Avalos 349f304aafSPeter Avalos ssh-rsa-cert-v01@openssh.com 359f304aafSPeter Avalos ssh-dss-cert-v01@openssh.com 369f304aafSPeter Avalos ecdsa-sha2-nistp256-cert-v01@openssh.com 379f304aafSPeter Avalos ecdsa-sha2-nistp384-cert-v01@openssh.com 389f304aafSPeter Avalos ecdsa-sha2-nistp521-cert-v01@openssh.com 39664f4763Szrj ssh-ed25519-cert-v01@openssh.com 409f304aafSPeter Avalos 41664f4763SzrjTwo additional types exist for RSA certificates to force use of 42664f4763SzrjSHA-2 signatures (SHA-256 and SHA-512 respectively): 43664f4763Szrj 44664f4763Szrj rsa-sha2-256-cert-v01@openssh.com 45664f4763Szrj rsa-sha2-512-cert-v01@openssh.com 46664f4763Szrj 47664f4763SzrjThese RSA/SHA-2 types should not appear in keys at rest or transmitted 4850a69bb5SSascha Wildneron the wire, but do appear in a SSH_MSG_KEXINIT's host-key algorithms 49664f4763Szrjfield or in the "public key algorithm name" field of a "publickey" 50664f4763SzrjSSH_USERAUTH_REQUEST to indicate that the signature will use the 51664f4763Szrjspecified algorithm. 52856ea928SPeter Avalos 53856ea928SPeter AvalosProtocol extensions 54856ea928SPeter Avalos------------------- 55856ea928SPeter Avalos 56856ea928SPeter AvalosThe SSH wire protocol includes several extensibility mechanisms. 57856ea928SPeter AvalosThese modifications shall take advantage of namespaced public key 58856ea928SPeter Avalosalgorithm names to add support for certificate authentication without 59856ea928SPeter Avalosbreaking the protocol - implementations that do not support the 60856ea928SPeter Avalosextensions will simply ignore them. 61856ea928SPeter Avalos 62856ea928SPeter AvalosAuthentication using the new key formats described below proceeds 63856ea928SPeter Avalosusing the existing SSH "publickey" authentication method described 64856ea928SPeter Avalosin RFC4252 section 7. 65856ea928SPeter Avalos 66856ea928SPeter AvalosNew public key formats 67856ea928SPeter Avalos---------------------- 68856ea928SPeter Avalos 699f304aafSPeter AvalosThe certificate key types take a similar high-level format (note: data 709f304aafSPeter Avalostypes and encoding are as per RFC4251 section 5). The serialised wire 719f304aafSPeter Avalosencoding of these certificates is also used for storing them on disk. 72856ea928SPeter Avalos 73856ea928SPeter Avalos#define SSH_CERT_TYPE_USER 1 74856ea928SPeter Avalos#define SSH_CERT_TYPE_HOST 2 75856ea928SPeter Avalos 76856ea928SPeter AvalosRSA certificate 77856ea928SPeter Avalos 78856ea928SPeter Avalos string "ssh-rsa-cert-v01@openssh.com" 79856ea928SPeter Avalos string nonce 80856ea928SPeter Avalos mpint e 81856ea928SPeter Avalos mpint n 82856ea928SPeter Avalos uint64 serial 83856ea928SPeter Avalos uint32 type 84856ea928SPeter Avalos string key id 85856ea928SPeter Avalos string valid principals 86856ea928SPeter Avalos uint64 valid after 87856ea928SPeter Avalos uint64 valid before 88856ea928SPeter Avalos string critical options 89856ea928SPeter Avalos string extensions 90856ea928SPeter Avalos string reserved 91856ea928SPeter Avalos string signature key 92856ea928SPeter Avalos string signature 93856ea928SPeter Avalos 94856ea928SPeter AvalosDSA certificate 95856ea928SPeter Avalos 96856ea928SPeter Avalos string "ssh-dss-cert-v01@openssh.com" 97856ea928SPeter Avalos string nonce 98856ea928SPeter Avalos mpint p 99856ea928SPeter Avalos mpint q 100856ea928SPeter Avalos mpint g 101856ea928SPeter Avalos mpint y 102856ea928SPeter Avalos uint64 serial 103856ea928SPeter Avalos uint32 type 104856ea928SPeter Avalos string key id 105856ea928SPeter Avalos string valid principals 106856ea928SPeter Avalos uint64 valid after 107856ea928SPeter Avalos uint64 valid before 108856ea928SPeter Avalos string critical options 109856ea928SPeter Avalos string extensions 110856ea928SPeter Avalos string reserved 111856ea928SPeter Avalos string signature key 112856ea928SPeter Avalos string signature 113856ea928SPeter Avalos 1149f304aafSPeter AvalosECDSA certificate 1159f304aafSPeter Avalos 116664f4763Szrj string "ecdsa-sha2-nistp256-cert-v01@openssh.com" | 117664f4763Szrj "ecdsa-sha2-nistp384-cert-v01@openssh.com" | 118664f4763Szrj "ecdsa-sha2-nistp521-cert-v01@openssh.com" 1199f304aafSPeter Avalos string nonce 1209f304aafSPeter Avalos string curve 1219f304aafSPeter Avalos string public_key 1229f304aafSPeter Avalos uint64 serial 1239f304aafSPeter Avalos uint32 type 1249f304aafSPeter Avalos string key id 1259f304aafSPeter Avalos string valid principals 1269f304aafSPeter Avalos uint64 valid after 1279f304aafSPeter Avalos uint64 valid before 1289f304aafSPeter Avalos string critical options 1299f304aafSPeter Avalos string extensions 1309f304aafSPeter Avalos string reserved 1319f304aafSPeter Avalos string signature key 1329f304aafSPeter Avalos string signature 1339f304aafSPeter Avalos 134e9778795SPeter AvalosED25519 certificate 135e9778795SPeter Avalos 136e9778795SPeter Avalos string "ssh-ed25519-cert-v01@openssh.com" 137e9778795SPeter Avalos string nonce 138e9778795SPeter Avalos string pk 139e9778795SPeter Avalos uint64 serial 140e9778795SPeter Avalos uint32 type 141e9778795SPeter Avalos string key id 142e9778795SPeter Avalos string valid principals 143e9778795SPeter Avalos uint64 valid after 144e9778795SPeter Avalos uint64 valid before 145e9778795SPeter Avalos string critical options 146e9778795SPeter Avalos string extensions 147e9778795SPeter Avalos string reserved 148e9778795SPeter Avalos string signature key 149e9778795SPeter Avalos string signature 150e9778795SPeter Avalos 151856ea928SPeter AvalosThe nonce field is a CA-provided random bitstring of arbitrary length 152856ea928SPeter Avalos(but typically 16 or 32 bytes) included to make attacks that depend on 153856ea928SPeter Avalosinducing collisions in the signature hash infeasible. 154856ea928SPeter Avalos 155856ea928SPeter Avalose and n are the RSA exponent and public modulus respectively. 156856ea928SPeter Avalos 157856ea928SPeter Avalosp, q, g, y are the DSA parameters as described in FIPS-186-2. 158856ea928SPeter Avalos 1599f304aafSPeter Avaloscurve and public key are respectively the ECDSA "[identifier]" and "Q" 1609f304aafSPeter Avalosdefined in section 3.1 of RFC5656. 1619f304aafSPeter Avalos 16250a69bb5SSascha Wildnerpk is the encoded Ed25519 public key as defined by RFC8032. 163e9778795SPeter Avalos 164856ea928SPeter Avalosserial is an optional certificate serial number set by the CA to 165856ea928SPeter Avalosprovide an abbreviated way to refer to certificates from that CA. 16650a69bb5SSascha WildnerIf a CA does not wish to number its certificates, it must set this 167856ea928SPeter Avalosfield to zero. 168856ea928SPeter Avalos 169856ea928SPeter Avalostype specifies whether this certificate is for identification of a user 170856ea928SPeter Avalosor a host using a SSH_CERT_TYPE_... value. 171856ea928SPeter Avalos 172856ea928SPeter Avaloskey id is a free-form text field that is filled in by the CA at the time 173856ea928SPeter Avalosof signing; the intention is that the contents of this field are used to 174856ea928SPeter Avalosidentify the identity principal in log messages. 175856ea928SPeter Avalos 176856ea928SPeter Avalos"valid principals" is a string containing zero or more principals as 177856ea928SPeter Avalosstrings packed inside it. These principals list the names for which this 178856ea928SPeter Avaloscertificate is valid; hostnames for SSH_CERT_TYPE_HOST certificates and 179856ea928SPeter Avalosusernames for SSH_CERT_TYPE_USER certificates. As a special case, a 180856ea928SPeter Avaloszero-length "valid principals" field means the certificate is valid for 181e9778795SPeter Avalosany principal of the specified type. 182856ea928SPeter Avalos 183856ea928SPeter Avalos"valid after" and "valid before" specify a validity period for the 184856ea928SPeter Avaloscertificate. Each represents a time in seconds since 1970-01-01 185856ea928SPeter Avalos00:00:00. A certificate is considered valid if: 1869f304aafSPeter Avalos 187856ea928SPeter Avalos valid after <= current time < valid before 188856ea928SPeter Avalos 189664f4763Szrjcritical options is a set of zero or more key options encoded as 190856ea928SPeter Avalosbelow. All such options are "critical" in the sense that an implementation 191856ea928SPeter Avalosmust refuse to authorise a key that has an unrecognised option. 192856ea928SPeter Avalos 193856ea928SPeter Avalosextensions is a set of zero or more optional extensions. These extensions 194856ea928SPeter Avalosare not critical, and an implementation that encounters one that it does 195856ea928SPeter Avalosnot recognise may safely ignore it. 196856ea928SPeter Avalos 19799e85e0dSPeter AvalosGenerally, critical options are used to control features that restrict 19899e85e0dSPeter Avalosaccess where extensions are used to enable features that grant access. 19999e85e0dSPeter AvalosThis ensures that certificates containing unknown restrictions do not 20099e85e0dSPeter Avalosinadvertently grant access while allowing new protocol features to be 20199e85e0dSPeter Avalosenabled via extensions without breaking certificates' backwards 20299e85e0dSPeter Avaloscompatibility. 20399e85e0dSPeter Avalos 204856ea928SPeter AvalosThe reserved field is currently unused and is ignored in this version of 205856ea928SPeter Avalosthe protocol. 206856ea928SPeter Avalos 207ce74bacaSMatthew DillonThe signature key field contains the CA key used to sign the 208ce74bacaSMatthew Dilloncertificate. The valid key types for CA keys are ssh-rsa, 209ce74bacaSMatthew Dillonssh-dss, ssh-ed25519 and the ECDSA types ecdsa-sha2-nistp256, 210ce74bacaSMatthew Dillonecdsa-sha2-nistp384, ecdsa-sha2-nistp521. "Chained" certificates, where 211ce74bacaSMatthew Dillonthe signature key type is a certificate type itself are NOT supported. 212ce74bacaSMatthew DillonNote that it is possible for a RSA certificate key to be signed by a 213ce74bacaSMatthew DillonEd25519 or ECDSA CA key and vice-versa. 214856ea928SPeter Avalos 215856ea928SPeter Avalossignature is computed over all preceding fields from the initial string 216856ea928SPeter Avalosup to, and including the signature key. Signatures are computed and 217856ea928SPeter Avalosencoded according to the rules defined for the CA's public key algorithm 2189f304aafSPeter Avalos(RFC4253 section 6.6 for ssh-rsa and ssh-dss, RFC5656 for the ECDSA 21950a69bb5SSascha Wildnertypes, and RFC8032 for Ed25519). 220856ea928SPeter Avalos 221856ea928SPeter AvalosCritical options 222856ea928SPeter Avalos---------------- 223856ea928SPeter Avalos 224856ea928SPeter AvalosThe critical options section of the certificate specifies zero or more 22550a69bb5SSascha Wildneroptions on the certificate's validity. The format of this field 226856ea928SPeter Avalosis a sequence of zero or more tuples: 227856ea928SPeter Avalos 228856ea928SPeter Avalos string name 229856ea928SPeter Avalos string data 230856ea928SPeter Avalos 231856ea928SPeter AvalosOptions must be lexically ordered by "name" if they appear in the 23299e85e0dSPeter Avalossequence. Each named option may only appear once in a certificate. 233856ea928SPeter Avalos 234856ea928SPeter AvalosThe name field identifies the option and the data field encodes 235856ea928SPeter Avalosoption-specific information (see below). All options are 23650a69bb5SSascha Wildner"critical"; if an implementation does not recognise a option, 237856ea928SPeter Avalosthen the validating party should refuse to accept the certificate. 238856ea928SPeter Avalos 239ce74bacaSMatthew DillonCustom options should append the originating author or organisation's 240ce74bacaSMatthew Dillondomain name to the option name, e.g. "my-option@example.com". 241ce74bacaSMatthew Dillon 242e9778795SPeter AvalosNo critical options are defined for host certificates at present. The 243e9778795SPeter Avalossupported user certificate options and the contents and structure of 244e9778795SPeter Avalostheir data fields are: 245856ea928SPeter Avalos 246856ea928SPeter AvalosName Format Description 247856ea928SPeter Avalos----------------------------------------------------------------------------- 248856ea928SPeter Avalosforce-command string Specifies a command that is executed 249856ea928SPeter Avalos (replacing any the user specified on the 250856ea928SPeter Avalos ssh command-line) whenever this key is 251856ea928SPeter Avalos used for authentication. 252856ea928SPeter Avalos 253856ea928SPeter Avalossource-address string Comma-separated list of source addresses 254856ea928SPeter Avalos from which this certificate is accepted 255856ea928SPeter Avalos for authentication. Addresses are 256856ea928SPeter Avalos specified in CIDR format (nn.nn.nn.nn/nn 257856ea928SPeter Avalos or hhhh::hhhh/nn). 25850a69bb5SSascha Wildner If this option is not present, then 259856ea928SPeter Avalos certificates may be presented from any 260856ea928SPeter Avalos source address. 261856ea928SPeter Avalos 26250a69bb5SSascha Wildnerverify-required empty Flag indicating that signatures made 26350a69bb5SSascha Wildner with this certificate must assert FIDO 26450a69bb5SSascha Wildner user verification (e.g. PIN or 26550a69bb5SSascha Wildner biometric). This option only makes sense 26650a69bb5SSascha Wildner for the U2F/FIDO security key types that 26750a69bb5SSascha Wildner support this feature in their signature 26850a69bb5SSascha Wildner formats. 26950a69bb5SSascha Wildner 270856ea928SPeter AvalosExtensions 271856ea928SPeter Avalos---------- 272856ea928SPeter Avalos 273856ea928SPeter AvalosThe extensions section of the certificate specifies zero or more 274856ea928SPeter Avalosnon-critical certificate extensions. The encoding and ordering of 27599e85e0dSPeter Avalosextensions in this field is identical to that of the critical options, 27699e85e0dSPeter Avalosas is the requirement that each name appear only once. 27799e85e0dSPeter Avalos 278856ea928SPeter AvalosIf an implementation does not recognise an extension, then it should 279856ea928SPeter Avalosignore it. 280856ea928SPeter Avalos 281ce74bacaSMatthew DillonCustom options should append the originating author or organisation's 282ce74bacaSMatthew Dillondomain name to the option name, e.g. "my-option@example.com". 283ce74bacaSMatthew Dillon 284e9778795SPeter AvalosNo extensions are defined for host certificates at present. The 285e9778795SPeter Avalossupported user certificate extensions and the contents and structure of 286e9778795SPeter Avalostheir data fields are: 287856ea928SPeter Avalos 288856ea928SPeter AvalosName Format Description 289856ea928SPeter Avalos----------------------------------------------------------------------------- 29050a69bb5SSascha Wildnerno-touch-required empty Flag indicating that signatures made 2910cbfa66cSDaniel Fojt with this certificate need not assert 29250a69bb5SSascha Wildner FIDO user presence. This option only 29350a69bb5SSascha Wildner makes sense for the U2F/FIDO security 29450a69bb5SSascha Wildner key types that support this feature in 2950cbfa66cSDaniel Fojt their signature formats. 2960cbfa66cSDaniel Fojt 297856ea928SPeter Avalospermit-X11-forwarding empty Flag indicating that X11 forwarding 298856ea928SPeter Avalos should be permitted. X11 forwarding will 299856ea928SPeter Avalos be refused if this option is absent. 300856ea928SPeter Avalos 301856ea928SPeter Avalospermit-agent-forwarding empty Flag indicating that agent forwarding 302856ea928SPeter Avalos should be allowed. Agent forwarding 303856ea928SPeter Avalos must not be permitted unless this 304856ea928SPeter Avalos option is present. 305856ea928SPeter Avalos 306856ea928SPeter Avalospermit-port-forwarding empty Flag indicating that port-forwarding 307856ea928SPeter Avalos should be allowed. If this option is 30850a69bb5SSascha Wildner not present, then no port forwarding will 309856ea928SPeter Avalos be allowed. 310856ea928SPeter Avalos 311856ea928SPeter Avalospermit-pty empty Flag indicating that PTY allocation 312856ea928SPeter Avalos should be permitted. In the absence of 313856ea928SPeter Avalos this option PTY allocation will be 314856ea928SPeter Avalos disabled. 315856ea928SPeter Avalos 316856ea928SPeter Avalospermit-user-rc empty Flag indicating that execution of 317856ea928SPeter Avalos ~/.ssh/rc should be permitted. Execution 318856ea928SPeter Avalos of this script will not be permitted if 319856ea928SPeter Avalos this option is not present. 320856ea928SPeter Avalos 32150a69bb5SSascha Wildner$OpenBSD: PROTOCOL.certkeys,v 1.19 2021/06/05 13:47:00 naddy Exp $ 322