Annotation of src/usr.bin/ssh/PROTOCOL.certkeys, Revision 1.19
1.1 djm 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
1.8 djm 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.
1.1 djm 13:
14: These protocol extensions build on the simple public key authentication
1.8 djm 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.
1.1 djm 20:
21: A sshd server may be configured to allow authentication via certified
1.8 djm 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.
27:
1.15 djm 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:
1.8 djm 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
1.16 djm 39: ssh-ed25519-cert-v01@openssh.com
1.8 djm 40:
1.15 djm 41: Two additional types exist for RSA certificates to force use of
42: SHA-2 signatures (SHA-256 and SHA-512 respectively):
43:
44: rsa-sha2-256-cert-v01@openssh.com
45: rsa-sha2-512-cert-v01@openssh.com
46:
47: These RSA/SHA-2 types should not appear in keys at rest or transmitted
1.19 ! naddy 48: on the wire, but do appear in a SSH_MSG_KEXINIT's host-key algorithms
1.15 djm 49: field or in the "public key algorithm name" field of a "publickey"
50: SSH_USERAUTH_REQUEST to indicate that the signature will use the
51: specified algorithm.
1.1 djm 52:
53: Protocol extensions
54: -------------------
55:
56: The SSH wire protocol includes several extensibility mechanisms.
57: These modifications shall take advantage of namespaced public key
58: algorithm names to add support for certificate authentication without
59: breaking the protocol - implementations that do not support the
60: extensions will simply ignore them.
61:
62: Authentication using the new key formats described below proceeds
63: using the existing SSH "publickey" authentication method described
64: in RFC4252 section 7.
65:
66: New public key formats
67: ----------------------
68:
1.8 djm 69: The certificate key types take a similar high-level format (note: data
70: types and encoding are as per RFC4251 section 5). The serialised wire
71: encoding of these certificates is also used for storing them on disk.
1.1 djm 72:
73: #define SSH_CERT_TYPE_USER 1
74: #define SSH_CERT_TYPE_HOST 2
75:
76: RSA certificate
77:
1.4 djm 78: string "ssh-rsa-cert-v01@openssh.com"
79: string nonce
1.1 djm 80: mpint e
81: mpint n
1.4 djm 82: uint64 serial
1.1 djm 83: uint32 type
84: string key id
85: string valid principals
86: uint64 valid after
87: uint64 valid before
1.4 djm 88: string critical options
89: string extensions
1.1 djm 90: string reserved
91: string signature key
92: string signature
93:
94: DSA certificate
95:
1.4 djm 96: string "ssh-dss-cert-v01@openssh.com"
97: string nonce
1.1 djm 98: mpint p
99: mpint q
100: mpint g
101: mpint y
1.4 djm 102: uint64 serial
1.1 djm 103: uint32 type
104: string key id
105: string valid principals
106: uint64 valid after
107: uint64 valid before
1.4 djm 108: string critical options
109: string extensions
1.1 djm 110: string reserved
111: string signature key
112: string signature
113:
1.8 djm 114: ECDSA certificate
115:
1.13 djm 116: string "ecdsa-sha2-nistp256-cert-v01@openssh.com" |
117: "ecdsa-sha2-nistp384-cert-v01@openssh.com" |
118: "ecdsa-sha2-nistp521-cert-v01@openssh.com"
1.8 djm 119: string nonce
120: string curve
121: string public_key
122: uint64 serial
123: uint32 type
124: string key id
125: string valid principals
126: uint64 valid after
127: uint64 valid before
128: string critical options
129: string extensions
130: string reserved
131: string signature key
132: string signature
133:
1.10 djm 134: ED25519 certificate
135:
136: string "ssh-ed25519-cert-v01@openssh.com"
137: string nonce
138: string pk
139: uint64 serial
140: uint32 type
141: string key id
142: string valid principals
143: uint64 valid after
144: uint64 valid before
145: string critical options
146: string extensions
147: string reserved
148: string signature key
149: string signature
150:
1.4 djm 151: The nonce field is a CA-provided random bitstring of arbitrary length
152: (but typically 16 or 32 bytes) included to make attacks that depend on
153: inducing collisions in the signature hash infeasible.
154:
1.1 djm 155: e and n are the RSA exponent and public modulus respectively.
156:
157: p, q, g, y are the DSA parameters as described in FIPS-186-2.
158:
1.8 djm 159: curve and public key are respectively the ECDSA "[identifier]" and "Q"
160: defined in section 3.1 of RFC5656.
161:
1.19 ! naddy 162: pk is the encoded Ed25519 public key as defined by RFC8032.
1.10 djm 163:
1.4 djm 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.
1.19 ! naddy 166: If a CA does not wish to number its certificates, it must set this
1.4 djm 167: field to zero.
168:
1.1 djm 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
1.10 djm 181: any principal of the specified type.
1.1 djm 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:
1.8 djm 186:
187: valid after <= current time < valid before
1.1 djm 188:
1.14 djm 189: critical options is a set of zero or more key options encoded as
1.4 djm 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.
192:
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
1.6 djm 195: not recognise may safely ignore it.
1.1 djm 196:
1.9 djm 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:
1.4 djm 204: The reserved field is currently unused and is ignored in this version of
1.1 djm 205: the protocol.
206:
1.11 djm 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.
1.1 djm 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
1.8 djm 218: (RFC4253 section 6.6 for ssh-rsa and ssh-dss, RFC5656 for the ECDSA
1.19 ! naddy 219: types, and RFC8032 for Ed25519).
1.1 djm 220:
1.4 djm 221: Critical options
222: ----------------
1.1 djm 223:
1.4 djm 224: The critical options section of the certificate specifies zero or more
1.19 ! naddy 225: options on the certificate's validity. The format of this field
1.1 djm 226: is a sequence of zero or more tuples:
227:
228: string name
229: string data
230:
1.7 djm 231: Options must be lexically ordered by "name" if they appear in the
1.9 djm 232: sequence. Each named option may only appear once in a certificate.
1.7 djm 233:
1.4 djm 234: The name field identifies the option and the data field encodes
235: option-specific information (see below). All options are
1.19 ! naddy 236: "critical"; if an implementation does not recognise a option,
1.1 djm 237: then the validating party should refuse to accept the certificate.
238:
1.12 djm 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:
1.10 djm 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:
1.1 djm 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:
1.6 djm 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).
1.19 ! naddy 258: If this option is not present, then
1.6 djm 259: certificates may be presented from any
260: source address.
261:
1.18 djm 262: verify-required empty Flag indicating that signatures made
263: with this certificate must assert FIDO
264: user verification (e.g. PIN or
1.19 ! naddy 265: biometric). This option only makes sense
1.18 djm 266: for the U2F/FIDO security key types that
267: support this feature in their signature
268: formats.
269:
1.6 djm 270: Extensions
271: ----------
272:
273: The extensions section of the certificate specifies zero or more
1.7 djm 274: non-critical certificate extensions. The encoding and ordering of
1.9 djm 275: extensions in this field is identical to that of the critical options,
276: as is the requirement that each name appear only once.
277:
1.7 djm 278: If an implementation does not recognise an extension, then it should
279: ignore it.
1.6 djm 280:
1.12 djm 281: Custom options should append the originating author or organisation's
282: domain name to the option name, e.g. "my-option@example.com".
283:
1.10 djm 284: No extensions are defined for host certificates at present. The
285: supported user certificate extensions and the contents and structure of
286: their data fields are:
1.6 djm 287:
288: Name Format Description
289: -----------------------------------------------------------------------------
1.18 djm 290: no-touch-required empty Flag indicating that signatures made
1.17 djm 291: with this certificate need not assert
1.18 djm 292: FIDO user presence. This option only
1.19 ! naddy 293: makes sense for the U2F/FIDO security
1.18 djm 294: key types that support this feature in
1.17 djm 295: their signature formats.
296:
1.1 djm 297: permit-X11-forwarding empty Flag indicating that X11 forwarding
298: should be permitted. X11 forwarding will
1.4 djm 299: be refused if this option is absent.
1.1 djm 300:
301: permit-agent-forwarding empty Flag indicating that agent forwarding
302: should be allowed. Agent forwarding
303: must not be permitted unless this
1.4 djm 304: option is present.
1.1 djm 305:
306: permit-port-forwarding empty Flag indicating that port-forwarding
1.4 djm 307: should be allowed. If this option is
1.19 ! naddy 308: not present, then no port forwarding will
1.1 djm 309: be allowed.
310:
311: permit-pty empty Flag indicating that PTY allocation
312: should be permitted. In the absence of
1.4 djm 313: this option PTY allocation will be
1.1 djm 314: disabled.
315:
316: permit-user-rc empty Flag indicating that execution of
317: ~/.ssh/rc should be permitted. Execution
318: of this script will not be permitted if
1.4 djm 319: this option is not present.
1.1 djm 320:
1.19 ! naddy 321: $OpenBSD: PROTOCOL.certkeys,v 1.18 2021/06/04 04:02:21 djm Exp $