1204861SdesThis document describes a simple public-key certificate authentication 2204861Sdessystem for use by SSH. 3204861Sdes 4204861SdesBackground 5204861Sdes---------- 6204861Sdes 7204861SdesThe SSH protocol currently supports a simple public key authentication 8221420Sdesmechanism. Unlike other public key implementations, SSH eschews the use 9221420Sdesof X.509 certificates and uses raw keys. This approach has some benefits 10221420Sdesrelating to simplicity of configuration and minimisation of attack 11221420Sdessurface, but it does not support the important use-cases of centrally 12221420Sdesmanaged, passwordless authentication and centrally certified host keys. 13204861Sdes 14204861SdesThese protocol extensions build on the simple public key authentication 15221420Sdessystem already in SSH to allow certificate-based authentication. The 16221420Sdescertificates used are not traditional X.509 certificates, with numerous 17221420Sdesoptions and complex encoding rules, but something rather more minimal: a 18221420Sdeskey, some identity information and usage options that have been signed 19221420Sdeswith some other trusted key. 20204861Sdes 21204861SdesA sshd server may be configured to allow authentication via certified 22221420Sdeskeys, by extending the existing ~/.ssh/authorized_keys mechanism to 23221420Sdesallow specification of certification authority keys in addition to 24221420Sdesraw user keys. The ssh client will support automatic verification of 25221420Sdesacceptance of certified host keys, by adding a similar ability to 26221420Sdesspecify CA keys in ~/.ssh/known_hosts. 27204861Sdes 28221420SdesCertified keys are represented using new key types: 29204861Sdes 30221420Sdes ssh-rsa-cert-v01@openssh.com 31221420Sdes ssh-dss-cert-v01@openssh.com 32221420Sdes ecdsa-sha2-nistp256-cert-v01@openssh.com 33221420Sdes ecdsa-sha2-nistp384-cert-v01@openssh.com 34221420Sdes ecdsa-sha2-nistp521-cert-v01@openssh.com 35221420Sdes 36221420SdesThese include certification information along with the public key 37221420Sdesthat is used to sign challenges. ssh-keygen performs the CA signing 38221420Sdesoperation. 39221420Sdes 40204861SdesProtocol extensions 41204861Sdes------------------- 42204861Sdes 43204861SdesThe SSH wire protocol includes several extensibility mechanisms. 44204861SdesThese modifications shall take advantage of namespaced public key 45204861Sdesalgorithm names to add support for certificate authentication without 46204861Sdesbreaking the protocol - implementations that do not support the 47204861Sdesextensions will simply ignore them. 48204861Sdes 49204861SdesAuthentication using the new key formats described below proceeds 50204861Sdesusing the existing SSH "publickey" authentication method described 51204861Sdesin RFC4252 section 7. 52204861Sdes 53204861SdesNew public key formats 54204861Sdes---------------------- 55204861Sdes 56221420SdesThe certificate key types take a similar high-level format (note: data 57221420Sdestypes and encoding are as per RFC4251 section 5). The serialised wire 58221420Sdesencoding of these certificates is also used for storing them on disk. 59204861Sdes 60204861Sdes#define SSH_CERT_TYPE_USER 1 61204861Sdes#define SSH_CERT_TYPE_HOST 2 62204861Sdes 63204861SdesRSA certificate 64204861Sdes 65215116Sdes string "ssh-rsa-cert-v01@openssh.com" 66215116Sdes string nonce 67204861Sdes mpint e 68204861Sdes mpint n 69215116Sdes uint64 serial 70204861Sdes uint32 type 71204861Sdes string key id 72204861Sdes string valid principals 73204861Sdes uint64 valid after 74204861Sdes uint64 valid before 75215116Sdes string critical options 76215116Sdes string extensions 77204861Sdes string reserved 78204861Sdes string signature key 79204861Sdes string signature 80204861Sdes 81204861SdesDSA certificate 82204861Sdes 83215116Sdes string "ssh-dss-cert-v01@openssh.com" 84215116Sdes string nonce 85204861Sdes mpint p 86204861Sdes mpint q 87204861Sdes mpint g 88204861Sdes mpint y 89215116Sdes uint64 serial 90204861Sdes uint32 type 91204861Sdes string key id 92204861Sdes string valid principals 93204861Sdes uint64 valid after 94204861Sdes uint64 valid before 95215116Sdes string critical options 96215116Sdes string extensions 97204861Sdes string reserved 98204861Sdes string signature key 99204861Sdes string signature 100204861Sdes 101221420SdesECDSA certificate 102221420Sdes 103323129Sdes string "ecdsa-sha2-nistp256-v01@openssh.com" | 104323129Sdes "ecdsa-sha2-nistp384-v01@openssh.com" | 105323129Sdes "ecdsa-sha2-nistp521-v01@openssh.com" 106221420Sdes string nonce 107221420Sdes string curve 108221420Sdes string public_key 109221420Sdes uint64 serial 110221420Sdes uint32 type 111221420Sdes string key id 112221420Sdes string valid principals 113221420Sdes uint64 valid after 114221420Sdes uint64 valid before 115221420Sdes string critical options 116221420Sdes string extensions 117221420Sdes string reserved 118221420Sdes string signature key 119221420Sdes string signature 120221420Sdes 121323129SdesED25519 certificate 122323129Sdes 123323129Sdes string "ssh-ed25519-cert-v01@openssh.com" 124323129Sdes string nonce 125323129Sdes string pk 126323129Sdes uint64 serial 127323129Sdes uint32 type 128323129Sdes string key id 129323129Sdes string valid principals 130323129Sdes uint64 valid after 131323129Sdes uint64 valid before 132323129Sdes string critical options 133323129Sdes string extensions 134323129Sdes string reserved 135323129Sdes string signature key 136323129Sdes string signature 137323129Sdes 138215116SdesThe nonce field is a CA-provided random bitstring of arbitrary length 139215116Sdes(but typically 16 or 32 bytes) included to make attacks that depend on 140215116Sdesinducing collisions in the signature hash infeasible. 141215116Sdes 142204861Sdese and n are the RSA exponent and public modulus respectively. 143204861Sdes 144204861Sdesp, q, g, y are the DSA parameters as described in FIPS-186-2. 145204861Sdes 146221420Sdescurve and public key are respectively the ECDSA "[identifier]" and "Q" 147221420Sdesdefined in section 3.1 of RFC5656. 148221420Sdes 149323129Sdespk is the encoded Ed25519 public key as defined by 150323129Sdesdraft-josefsson-eddsa-ed25519-03. 151323129Sdes 152215116Sdesserial is an optional certificate serial number set by the CA to 153215116Sdesprovide an abbreviated way to refer to certificates from that CA. 154215116SdesIf a CA does not wish to number its certificates it must set this 155215116Sdesfield to zero. 156215116Sdes 157204861Sdestype specifies whether this certificate is for identification of a user 158204861Sdesor a host using a SSH_CERT_TYPE_... value. 159204861Sdes 160204861Sdeskey id is a free-form text field that is filled in by the CA at the time 161204861Sdesof signing; the intention is that the contents of this field are used to 162204861Sdesidentify the identity principal in log messages. 163204861Sdes 164204861Sdes"valid principals" is a string containing zero or more principals as 165204861Sdesstrings packed inside it. These principals list the names for which this 166204861Sdescertificate is valid; hostnames for SSH_CERT_TYPE_HOST certificates and 167204861Sdesusernames for SSH_CERT_TYPE_USER certificates. As a special case, a 168204861Sdeszero-length "valid principals" field means the certificate is valid for 169323129Sdesany principal of the specified type. 170204861Sdes 171204861Sdes"valid after" and "valid before" specify a validity period for the 172204861Sdescertificate. Each represents a time in seconds since 1970-01-01 173204861Sdes00:00:00. A certificate is considered valid if: 174204861Sdes 175221420Sdes valid after <= current time < valid before 176221420Sdes 177215116Sdescriticial options is a set of zero or more key options encoded as 178215116Sdesbelow. All such options are "critical" in the sense that an implementation 179215116Sdesmust refuse to authorise a key that has an unrecognised option. 180204861Sdes 181215116Sdesextensions is a set of zero or more optional extensions. These extensions 182215116Sdesare not critical, and an implementation that encounters one that it does 183215116Sdesnot recognise may safely ignore it. 184204861Sdes 185240075SdesGenerally, critical options are used to control features that restrict 186240075Sdesaccess where extensions are used to enable features that grant access. 187240075SdesThis ensures that certificates containing unknown restrictions do not 188240075Sdesinadvertently grant access while allowing new protocol features to be 189240075Sdesenabled via extensions without breaking certificates' backwards 190240075Sdescompatibility. 191240075Sdes 192215116SdesThe reserved field is currently unused and is ignored in this version of 193204861Sdesthe protocol. 194204861Sdes 195204861Sdessignature key contains the CA key used to sign the certificate. 196221420SdesThe valid key types for CA keys are ssh-rsa, ssh-dss and the ECDSA types 197221420Sdesecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521. "Chained" 198204861Sdescertificates, where the signature key type is a certificate type itself 199204861Sdesare NOT supported. Note that it is possible for a RSA certificate key to 200221420Sdesbe signed by a DSS or ECDSA CA key and vice-versa. 201204861Sdes 202204861Sdessignature is computed over all preceding fields from the initial string 203204861Sdesup to, and including the signature key. Signatures are computed and 204204861Sdesencoded according to the rules defined for the CA's public key algorithm 205221420Sdes(RFC4253 section 6.6 for ssh-rsa and ssh-dss, RFC5656 for the ECDSA 206323129Sdestypes), and draft-josefsson-eddsa-ed25519-03 for Ed25519. 207204861Sdes 208215116SdesCritical options 209215116Sdes---------------- 210204861Sdes 211215116SdesThe critical options section of the certificate specifies zero or more 212215116Sdesoptions on the certificates validity. The format of this field 213204861Sdesis a sequence of zero or more tuples: 214204861Sdes 215204861Sdes string name 216204861Sdes string data 217204861Sdes 218215116SdesOptions must be lexically ordered by "name" if they appear in the 219240075Sdessequence. Each named option may only appear once in a certificate. 220215116Sdes 221215116SdesThe name field identifies the option and the data field encodes 222215116Sdesoption-specific information (see below). All options are 223215116Sdes"critical", if an implementation does not recognise a option 224204861Sdesthen the validating party should refuse to accept the certificate. 225204861Sdes 226323129SdesNo critical options are defined for host certificates at present. The 227323129Sdessupported user certificate options and the contents and structure of 228323129Sdestheir data fields are: 229204861Sdes 230204861SdesName Format Description 231204861Sdes----------------------------------------------------------------------------- 232204861Sdesforce-command string Specifies a command that is executed 233204861Sdes (replacing any the user specified on the 234204861Sdes ssh command-line) whenever this key is 235204861Sdes used for authentication. 236204861Sdes 237215116Sdessource-address string Comma-separated list of source addresses 238215116Sdes from which this certificate is accepted 239215116Sdes for authentication. Addresses are 240215116Sdes specified in CIDR format (nn.nn.nn.nn/nn 241215116Sdes or hhhh::hhhh/nn). 242215116Sdes If this option is not present then 243215116Sdes certificates may be presented from any 244215116Sdes source address. 245215116Sdes 246215116SdesExtensions 247215116Sdes---------- 248215116Sdes 249215116SdesThe extensions section of the certificate specifies zero or more 250215116Sdesnon-critical certificate extensions. The encoding and ordering of 251240075Sdesextensions in this field is identical to that of the critical options, 252240075Sdesas is the requirement that each name appear only once. 253240075Sdes 254215116SdesIf an implementation does not recognise an extension, then it should 255215116Sdesignore it. 256215116Sdes 257323129SdesNo extensions are defined for host certificates at present. The 258323129Sdessupported user certificate extensions and the contents and structure of 259323129Sdestheir data fields are: 260215116Sdes 261215116SdesName Format Description 262215116Sdes----------------------------------------------------------------------------- 263204861Sdespermit-X11-forwarding empty Flag indicating that X11 forwarding 264204861Sdes should be permitted. X11 forwarding will 265215116Sdes be refused if this option is absent. 266204861Sdes 267204861Sdespermit-agent-forwarding empty Flag indicating that agent forwarding 268204861Sdes should be allowed. Agent forwarding 269204861Sdes must not be permitted unless this 270215116Sdes option is present. 271204861Sdes 272204861Sdespermit-port-forwarding empty Flag indicating that port-forwarding 273215116Sdes should be allowed. If this option is 274204861Sdes not present then no port forwarding will 275204861Sdes be allowed. 276204861Sdes 277204861Sdespermit-pty empty Flag indicating that PTY allocation 278204861Sdes should be permitted. In the absence of 279215116Sdes this option PTY allocation will be 280204861Sdes disabled. 281204861Sdes 282204861Sdespermit-user-rc empty Flag indicating that execution of 283204861Sdes ~/.ssh/rc should be permitted. Execution 284204861Sdes of this script will not be permitted if 285215116Sdes this option is not present. 286204861Sdes 287323129Sdes$OpenBSD: PROTOCOL.certkeys,v 1.10 2016/05/03 10:27:59 djm Exp $ 288