Annotation of src/usr.bin/ssh/PROTOCOL.certkeys, Revision 1.15
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
39:
1.15 ! djm 40: Two additional types exist for RSA certificates to force use of
! 41: SHA-2 signatures (SHA-256 and SHA-512 respectively):
! 42:
! 43: rsa-sha2-256-cert-v01@openssh.com
! 44: rsa-sha2-512-cert-v01@openssh.com
! 45:
! 46: These RSA/SHA-2 types should not appear in keys at rest or transmitted
! 47: on their wire, but do appear in a SSH_MSG_KEXINIT's host-key algorithms
! 48: field or in the "public key algorithm name" field of a "publickey"
! 49: SSH_USERAUTH_REQUEST to indicate that the signature will use the
! 50: specified algorithm.
1.1 djm 51:
52: Protocol extensions
53: -------------------
54:
55: The SSH wire protocol includes several extensibility mechanisms.
56: These modifications shall take advantage of namespaced public key
57: algorithm names to add support for certificate authentication without
58: breaking the protocol - implementations that do not support the
59: extensions will simply ignore them.
60:
61: Authentication using the new key formats described below proceeds
62: using the existing SSH "publickey" authentication method described
63: in RFC4252 section 7.
64:
65: New public key formats
66: ----------------------
67:
1.8 djm 68: The certificate key types take a similar high-level format (note: data
69: types and encoding are as per RFC4251 section 5). The serialised wire
70: encoding of these certificates is also used for storing them on disk.
1.1 djm 71:
72: #define SSH_CERT_TYPE_USER 1
73: #define SSH_CERT_TYPE_HOST 2
74:
75: RSA certificate
76:
1.4 djm 77: string "ssh-rsa-cert-v01@openssh.com"
78: string nonce
1.1 djm 79: mpint e
80: mpint n
1.4 djm 81: uint64 serial
1.1 djm 82: uint32 type
83: string key id
84: string valid principals
85: uint64 valid after
86: uint64 valid before
1.4 djm 87: string critical options
88: string extensions
1.1 djm 89: string reserved
90: string signature key
91: string signature
92:
93: DSA certificate
94:
1.4 djm 95: string "ssh-dss-cert-v01@openssh.com"
96: string nonce
1.1 djm 97: mpint p
98: mpint q
99: mpint g
100: mpint y
1.4 djm 101: uint64 serial
1.1 djm 102: uint32 type
103: string key id
104: string valid principals
105: uint64 valid after
106: uint64 valid before
1.4 djm 107: string critical options
108: string extensions
1.1 djm 109: string reserved
110: string signature key
111: string signature
112:
1.8 djm 113: ECDSA certificate
114:
1.13 djm 115: string "ecdsa-sha2-nistp256-cert-v01@openssh.com" |
116: "ecdsa-sha2-nistp384-cert-v01@openssh.com" |
117: "ecdsa-sha2-nistp521-cert-v01@openssh.com"
1.8 djm 118: string nonce
119: string curve
120: string public_key
121: uint64 serial
122: uint32 type
123: string key id
124: string valid principals
125: uint64 valid after
126: uint64 valid before
127: string critical options
128: string extensions
129: string reserved
130: string signature key
131: string signature
132:
1.10 djm 133: ED25519 certificate
134:
135: string "ssh-ed25519-cert-v01@openssh.com"
136: string nonce
137: string pk
138: uint64 serial
139: uint32 type
140: string key id
141: string valid principals
142: uint64 valid after
143: uint64 valid before
144: string critical options
145: string extensions
146: string reserved
147: string signature key
148: string signature
149:
1.4 djm 150: The nonce field is a CA-provided random bitstring of arbitrary length
151: (but typically 16 or 32 bytes) included to make attacks that depend on
152: inducing collisions in the signature hash infeasible.
153:
1.1 djm 154: e and n are the RSA exponent and public modulus respectively.
155:
156: p, q, g, y are the DSA parameters as described in FIPS-186-2.
157:
1.8 djm 158: curve and public key are respectively the ECDSA "[identifier]" and "Q"
159: defined in section 3.1 of RFC5656.
160:
1.10 djm 161: pk is the encoded Ed25519 public key as defined by
162: draft-josefsson-eddsa-ed25519-03.
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.5 djm 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.10 djm 219: types), and draft-josefsson-eddsa-ed25519-03 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
225: options on the certificates 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
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).
258: If this option is not present then
259: certificates may be presented from any
260: source address.
261:
262: Extensions
263: ----------
264:
265: The extensions section of the certificate specifies zero or more
1.7 djm 266: non-critical certificate extensions. The encoding and ordering of
1.9 djm 267: extensions in this field is identical to that of the critical options,
268: as is the requirement that each name appear only once.
269:
1.7 djm 270: If an implementation does not recognise an extension, then it should
271: ignore it.
1.6 djm 272:
1.12 djm 273: Custom options should append the originating author or organisation's
274: domain name to the option name, e.g. "my-option@example.com".
275:
1.10 djm 276: No extensions are defined for host certificates at present. The
277: supported user certificate extensions and the contents and structure of
278: their data fields are:
1.6 djm 279:
280: Name Format Description
281: -----------------------------------------------------------------------------
1.1 djm 282: permit-X11-forwarding empty Flag indicating that X11 forwarding
283: should be permitted. X11 forwarding will
1.4 djm 284: be refused if this option is absent.
1.1 djm 285:
286: permit-agent-forwarding empty Flag indicating that agent forwarding
287: should be allowed. Agent forwarding
288: must not be permitted unless this
1.4 djm 289: option is present.
1.1 djm 290:
291: permit-port-forwarding empty Flag indicating that port-forwarding
1.4 djm 292: should be allowed. If this option is
1.1 djm 293: not present then no port forwarding will
294: be allowed.
295:
296: permit-pty empty Flag indicating that PTY allocation
297: should be permitted. In the absence of
1.4 djm 298: this option PTY allocation will be
1.1 djm 299: disabled.
300:
301: permit-user-rc empty Flag indicating that execution of
302: ~/.ssh/rc should be permitted. Execution
303: of this script will not be permitted if
1.4 djm 304: this option is not present.
1.1 djm 305:
1.15 ! djm 306: $OpenBSD: PROTOCOL.certkeys,v 1.14 2018/04/10 00:10:49 djm Exp $
![[BACK]](/icons/back.gif){kind=icon}
Return to PROTOCOL.certkeys CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / ssh