Annotation of src/usr.bin/ssh/PROTOCOL.certkeys, Revision 1.11
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:
28: Certified keys are represented using new key types:
29:
30: ssh-rsa-cert-v01@openssh.com
31: ssh-dss-cert-v01@openssh.com
32: ecdsa-sha2-nistp256-cert-v01@openssh.com
33: ecdsa-sha2-nistp384-cert-v01@openssh.com
34: ecdsa-sha2-nistp521-cert-v01@openssh.com
35:
36: These include certification information along with the public key
37: that is used to sign challenges. ssh-keygen performs the CA signing
38: operation.
1.1 djm 39:
40: Protocol extensions
41: -------------------
42:
43: The SSH wire protocol includes several extensibility mechanisms.
44: These modifications shall take advantage of namespaced public key
45: algorithm names to add support for certificate authentication without
46: breaking the protocol - implementations that do not support the
47: extensions will simply ignore them.
48:
49: Authentication using the new key formats described below proceeds
50: using the existing SSH "publickey" authentication method described
51: in RFC4252 section 7.
52:
53: New public key formats
54: ----------------------
55:
1.8 djm 56: The certificate key types take a similar high-level format (note: data
57: types and encoding are as per RFC4251 section 5). The serialised wire
58: encoding of these certificates is also used for storing them on disk.
1.1 djm 59:
60: #define SSH_CERT_TYPE_USER 1
61: #define SSH_CERT_TYPE_HOST 2
62:
63: RSA certificate
64:
1.4 djm 65: string "ssh-rsa-cert-v01@openssh.com"
66: string nonce
1.1 djm 67: mpint e
68: mpint n
1.4 djm 69: uint64 serial
1.1 djm 70: uint32 type
71: string key id
72: string valid principals
73: uint64 valid after
74: uint64 valid before
1.4 djm 75: string critical options
76: string extensions
1.1 djm 77: string reserved
78: string signature key
79: string signature
80:
81: DSA certificate
82:
1.4 djm 83: string "ssh-dss-cert-v01@openssh.com"
84: string nonce
1.1 djm 85: mpint p
86: mpint q
87: mpint g
88: mpint y
1.4 djm 89: uint64 serial
1.1 djm 90: uint32 type
91: string key id
92: string valid principals
93: uint64 valid after
94: uint64 valid before
1.4 djm 95: string critical options
96: string extensions
1.1 djm 97: string reserved
98: string signature key
99: string signature
100:
1.8 djm 101: ECDSA certificate
102:
1.10 djm 103: string "ecdsa-sha2-nistp256-v01@openssh.com" |
104: "ecdsa-sha2-nistp384-v01@openssh.com" |
105: "ecdsa-sha2-nistp521-v01@openssh.com"
1.8 djm 106: string nonce
107: string curve
108: string public_key
109: uint64 serial
110: uint32 type
111: string key id
112: string valid principals
113: uint64 valid after
114: uint64 valid before
115: string critical options
116: string extensions
117: string reserved
118: string signature key
119: string signature
120:
1.10 djm 121: ED25519 certificate
122:
123: string "ssh-ed25519-cert-v01@openssh.com"
124: string nonce
125: string pk
126: uint64 serial
127: uint32 type
128: string key id
129: string valid principals
130: uint64 valid after
131: uint64 valid before
132: string critical options
133: string extensions
134: string reserved
135: string signature key
136: string signature
137:
1.4 djm 138: The nonce field is a CA-provided random bitstring of arbitrary length
139: (but typically 16 or 32 bytes) included to make attacks that depend on
140: inducing collisions in the signature hash infeasible.
141:
1.1 djm 142: e and n are the RSA exponent and public modulus respectively.
143:
144: p, q, g, y are the DSA parameters as described in FIPS-186-2.
145:
1.8 djm 146: curve and public key are respectively the ECDSA "[identifier]" and "Q"
147: defined in section 3.1 of RFC5656.
148:
1.10 djm 149: pk is the encoded Ed25519 public key as defined by
150: draft-josefsson-eddsa-ed25519-03.
151:
1.4 djm 152: serial is an optional certificate serial number set by the CA to
153: provide an abbreviated way to refer to certificates from that CA.
1.5 djm 154: If a CA does not wish to number its certificates it must set this
1.4 djm 155: field to zero.
156:
1.1 djm 157: type specifies whether this certificate is for identification of a user
158: or a host using a SSH_CERT_TYPE_... value.
159:
160: key id is a free-form text field that is filled in by the CA at the time
161: of signing; the intention is that the contents of this field are used to
162: identify the identity principal in log messages.
163:
164: "valid principals" is a string containing zero or more principals as
165: strings packed inside it. These principals list the names for which this
166: certificate is valid; hostnames for SSH_CERT_TYPE_HOST certificates and
167: usernames for SSH_CERT_TYPE_USER certificates. As a special case, a
168: zero-length "valid principals" field means the certificate is valid for
1.10 djm 169: any principal of the specified type.
1.1 djm 170:
171: "valid after" and "valid before" specify a validity period for the
172: certificate. Each represents a time in seconds since 1970-01-01
173: 00:00:00. A certificate is considered valid if:
1.8 djm 174:
175: valid after <= current time < valid before
1.1 djm 176:
1.4 djm 177: criticial options is a set of zero or more key options encoded as
178: below. All such options are "critical" in the sense that an implementation
179: must refuse to authorise a key that has an unrecognised option.
180:
181: extensions is a set of zero or more optional extensions. These extensions
182: are not critical, and an implementation that encounters one that it does
1.6 djm 183: not recognise may safely ignore it.
1.1 djm 184:
1.9 djm 185: Generally, critical options are used to control features that restrict
186: access where extensions are used to enable features that grant access.
187: This ensures that certificates containing unknown restrictions do not
188: inadvertently grant access while allowing new protocol features to be
189: enabled via extensions without breaking certificates' backwards
190: compatibility.
191:
1.4 djm 192: The reserved field is currently unused and is ignored in this version of
1.1 djm 193: the protocol.
194:
1.11 ! djm 195: The signature key field contains the CA key used to sign the
! 196: certificate. The valid key types for CA keys are ssh-rsa,
! 197: ssh-dss, ssh-ed25519 and the ECDSA types ecdsa-sha2-nistp256,
! 198: ecdsa-sha2-nistp384, ecdsa-sha2-nistp521. "Chained" certificates, where
! 199: the signature key type is a certificate type itself are NOT supported.
! 200: Note that it is possible for a RSA certificate key to be signed by a
! 201: Ed25519 or ECDSA CA key and vice-versa.
1.1 djm 202:
203: signature is computed over all preceding fields from the initial string
204: up to, and including the signature key. Signatures are computed and
205: encoded according to the rules defined for the CA's public key algorithm
1.8 djm 206: (RFC4253 section 6.6 for ssh-rsa and ssh-dss, RFC5656 for the ECDSA
1.10 djm 207: types), and draft-josefsson-eddsa-ed25519-03 for Ed25519.
1.1 djm 208:
1.4 djm 209: Critical options
210: ----------------
1.1 djm 211:
1.4 djm 212: The critical options section of the certificate specifies zero or more
213: options on the certificates validity. The format of this field
1.1 djm 214: is a sequence of zero or more tuples:
215:
216: string name
217: string data
218:
1.7 djm 219: Options must be lexically ordered by "name" if they appear in the
1.9 djm 220: sequence. Each named option may only appear once in a certificate.
1.7 djm 221:
1.4 djm 222: The name field identifies the option and the data field encodes
223: option-specific information (see below). All options are
224: "critical", if an implementation does not recognise a option
1.1 djm 225: then the validating party should refuse to accept the certificate.
226:
1.10 djm 227: No critical options are defined for host certificates at present. The
228: supported user certificate options and the contents and structure of
229: their data fields are:
1.1 djm 230:
231: Name Format Description
232: -----------------------------------------------------------------------------
233: force-command string Specifies a command that is executed
234: (replacing any the user specified on the
235: ssh command-line) whenever this key is
236: used for authentication.
237:
1.6 djm 238: source-address string Comma-separated list of source addresses
239: from which this certificate is accepted
240: for authentication. Addresses are
241: specified in CIDR format (nn.nn.nn.nn/nn
242: or hhhh::hhhh/nn).
243: If this option is not present then
244: certificates may be presented from any
245: source address.
246:
247: Extensions
248: ----------
249:
250: The extensions section of the certificate specifies zero or more
1.7 djm 251: non-critical certificate extensions. The encoding and ordering of
1.9 djm 252: extensions in this field is identical to that of the critical options,
253: as is the requirement that each name appear only once.
254:
1.7 djm 255: If an implementation does not recognise an extension, then it should
256: ignore it.
1.6 djm 257:
1.10 djm 258: No extensions are defined for host certificates at present. The
259: supported user certificate extensions and the contents and structure of
260: their data fields are:
1.6 djm 261:
262: Name Format Description
263: -----------------------------------------------------------------------------
1.1 djm 264: permit-X11-forwarding empty Flag indicating that X11 forwarding
265: should be permitted. X11 forwarding will
1.4 djm 266: be refused if this option is absent.
1.1 djm 267:
268: permit-agent-forwarding empty Flag indicating that agent forwarding
269: should be allowed. Agent forwarding
270: must not be permitted unless this
1.4 djm 271: option is present.
1.1 djm 272:
273: permit-port-forwarding empty Flag indicating that port-forwarding
1.4 djm 274: should be allowed. If this option is
1.1 djm 275: not present then no port forwarding will
276: be allowed.
277:
278: permit-pty empty Flag indicating that PTY allocation
279: should be permitted. In the absence of
1.4 djm 280: this option PTY allocation will be
1.1 djm 281: disabled.
282:
283: permit-user-rc empty Flag indicating that execution of
284: ~/.ssh/rc should be permitted. Execution
285: of this script will not be permitted if
1.4 djm 286: this option is not present.
1.1 djm 287:
1.11 ! djm 288: $OpenBSD: PROTOCOL.certkeys,v 1.10 2016/05/03 10:27:59 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