=================================================================== RCS file: /cvsrepo/anoncvs/cvs/src/usr.bin/ssh/PROTOCOL.certkeys,v retrieving revision 1.10 retrieving revision 1.19 diff -u -r1.10 -r1.19 --- src/usr.bin/ssh/PROTOCOL.certkeys 2016/05/03 10:27:59 1.10 +++ src/usr.bin/ssh/PROTOCOL.certkeys 2021/06/05 13:47:00 1.19 @@ -25,6 +25,10 @@ acceptance of certified host keys, by adding a similar ability to specify CA keys in ~/.ssh/known_hosts. +All certificate types include certification information along with the +public key that is used to sign challenges. In OpenSSH, ssh-keygen +performs the CA signing operation. + Certified keys are represented using new key types: ssh-rsa-cert-v01@openssh.com @@ -32,11 +36,20 @@ ecdsa-sha2-nistp256-cert-v01@openssh.com ecdsa-sha2-nistp384-cert-v01@openssh.com ecdsa-sha2-nistp521-cert-v01@openssh.com + ssh-ed25519-cert-v01@openssh.com -These include certification information along with the public key -that is used to sign challenges. ssh-keygen performs the CA signing -operation. +Two additional types exist for RSA certificates to force use of +SHA-2 signatures (SHA-256 and SHA-512 respectively): + rsa-sha2-256-cert-v01@openssh.com + rsa-sha2-512-cert-v01@openssh.com + +These RSA/SHA-2 types should not appear in keys at rest or transmitted +on the wire, but do appear in a SSH_MSG_KEXINIT's host-key algorithms +field or in the "public key algorithm name" field of a "publickey" +SSH_USERAUTH_REQUEST to indicate that the signature will use the +specified algorithm. + Protocol extensions ------------------- @@ -100,9 +113,9 @@ ECDSA certificate - string "ecdsa-sha2-nistp256-v01@openssh.com" | - "ecdsa-sha2-nistp384-v01@openssh.com" | - "ecdsa-sha2-nistp521-v01@openssh.com" + string "ecdsa-sha2-nistp256-cert-v01@openssh.com" | + "ecdsa-sha2-nistp384-cert-v01@openssh.com" | + "ecdsa-sha2-nistp521-cert-v01@openssh.com" string nonce string curve string public_key @@ -146,12 +159,11 @@ curve and public key are respectively the ECDSA "[identifier]" and "Q" defined in section 3.1 of RFC5656. -pk is the encoded Ed25519 public key as defined by -draft-josefsson-eddsa-ed25519-03. +pk is the encoded Ed25519 public key as defined by RFC8032. serial is an optional certificate serial number set by the CA to provide an abbreviated way to refer to certificates from that CA. -If a CA does not wish to number its certificates it must set this +If a CA does not wish to number its certificates, it must set this field to zero. type specifies whether this certificate is for identification of a user @@ -174,7 +186,7 @@ valid after <= current time < valid before -criticial options is a set of zero or more key options encoded as +critical options is a set of zero or more key options encoded as below. All such options are "critical" in the sense that an implementation must refuse to authorise a key that has an unrecognised option. @@ -192,24 +204,25 @@ The reserved field is currently unused and is ignored in this version of the protocol. -signature key contains the CA key used to sign the certificate. -The valid key types for CA keys are ssh-rsa, ssh-dss and the ECDSA types -ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521. "Chained" -certificates, where the signature key type is a certificate type itself -are NOT supported. Note that it is possible for a RSA certificate key to -be signed by a DSS or ECDSA CA key and vice-versa. +The signature key field contains the CA key used to sign the +certificate. The valid key types for CA keys are ssh-rsa, +ssh-dss, ssh-ed25519 and the ECDSA types ecdsa-sha2-nistp256, +ecdsa-sha2-nistp384, ecdsa-sha2-nistp521. "Chained" certificates, where +the signature key type is a certificate type itself are NOT supported. +Note that it is possible for a RSA certificate key to be signed by a +Ed25519 or ECDSA CA key and vice-versa. signature is computed over all preceding fields from the initial string up to, and including the signature key. Signatures are computed and encoded according to the rules defined for the CA's public key algorithm (RFC4253 section 6.6 for ssh-rsa and ssh-dss, RFC5656 for the ECDSA -types), and draft-josefsson-eddsa-ed25519-03 for Ed25519. +types, and RFC8032 for Ed25519). Critical options ---------------- The critical options section of the certificate specifies zero or more -options on the certificates validity. The format of this field +options on the certificate's validity. The format of this field is a sequence of zero or more tuples: string name @@ -220,9 +233,12 @@ The name field identifies the option and the data field encodes option-specific information (see below). All options are -"critical", if an implementation does not recognise a option +"critical"; if an implementation does not recognise a option, then the validating party should refuse to accept the certificate. +Custom options should append the originating author or organisation's +domain name to the option name, e.g. "my-option@example.com". + No critical options are defined for host certificates at present. The supported user certificate options and the contents and structure of their data fields are: @@ -239,10 +255,18 @@ for authentication. Addresses are specified in CIDR format (nn.nn.nn.nn/nn or hhhh::hhhh/nn). - If this option is not present then + If this option is not present, then certificates may be presented from any source address. +verify-required empty Flag indicating that signatures made + with this certificate must assert FIDO + user verification (e.g. PIN or + biometric). This option only makes sense + for the U2F/FIDO security key types that + support this feature in their signature + formats. + Extensions ---------- @@ -254,12 +278,22 @@ If an implementation does not recognise an extension, then it should ignore it. +Custom options should append the originating author or organisation's +domain name to the option name, e.g. "my-option@example.com". + No extensions are defined for host certificates at present. The supported user certificate extensions and the contents and structure of their data fields are: Name Format Description ----------------------------------------------------------------------------- +no-touch-required empty Flag indicating that signatures made + with this certificate need not assert + FIDO user presence. This option only + makes sense for the U2F/FIDO security + key types that support this feature in + their signature formats. + permit-X11-forwarding empty Flag indicating that X11 forwarding should be permitted. X11 forwarding will be refused if this option is absent. @@ -271,7 +305,7 @@ permit-port-forwarding empty Flag indicating that port-forwarding should be allowed. If this option is - not present then no port forwarding will + not present, then no port forwarding will be allowed. permit-pty empty Flag indicating that PTY allocation @@ -284,4 +318,4 @@ of this script will not be permitted if this option is not present. -$OpenBSD: PROTOCOL.certkeys,v 1.10 2016/05/03 10:27:59 djm Exp $ +$OpenBSD: PROTOCOL.certkeys,v 1.19 2021/06/05 13:47:00 naddy Exp $