blob: 64cb18700ee10dd03928d6dd5f0a0c53a3ef7052 [file] [log] [blame]
Damien Miller0a80ca12010-02-27 07:55:05 +11001This document describes a simple public-key certificate authentication
2system for use by SSH.
3
4Background
5----------
6
7The SSH protocol currently supports a simple public key authentication
Damien Millereb8b60e2010-08-31 22:41:14 +10008mechanism. Unlike other public key implementations, SSH eschews the use
9of X.509 certificates and uses raw keys. This approach has some benefits
10relating to simplicity of configuration and minimisation of attack
11surface, but it does not support the important use-cases of centrally
12managed, passwordless authentication and centrally certified host keys.
Damien Miller0a80ca12010-02-27 07:55:05 +110013
14These protocol extensions build on the simple public key authentication
Damien Millereb8b60e2010-08-31 22:41:14 +100015system already in SSH to allow certificate-based authentication. The
16certificates used are not traditional X.509 certificates, with numerous
17options and complex encoding rules, but something rather more minimal: a
18key, some identity information and usage options that have been signed
19with some other trusted key.
Damien Miller0a80ca12010-02-27 07:55:05 +110020
21A sshd server may be configured to allow authentication via certified
Damien Millereb8b60e2010-08-31 22:41:14 +100022keys, by extending the existing ~/.ssh/authorized_keys mechanism to
23allow specification of certification authority keys in addition to
24raw user keys. The ssh client will support automatic verification of
25acceptance of certified host keys, by adding a similar ability to
26specify CA keys in ~/.ssh/known_hosts.
Damien Miller0a80ca12010-02-27 07:55:05 +110027
Damien Millereb8b60e2010-08-31 22:41:14 +100028Certified 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
36These include certification information along with the public key
37that is used to sign challenges. ssh-keygen performs the CA signing
38operation.
Damien Miller0a80ca12010-02-27 07:55:05 +110039
40Protocol extensions
41-------------------
42
43The SSH wire protocol includes several extensibility mechanisms.
44These modifications shall take advantage of namespaced public key
45algorithm names to add support for certificate authentication without
46breaking the protocol - implementations that do not support the
47extensions will simply ignore them.
48
49Authentication using the new key formats described below proceeds
50using the existing SSH "publickey" authentication method described
51in RFC4252 section 7.
52
53New public key formats
54----------------------
55
Damien Millereb8b60e2010-08-31 22:41:14 +100056The certificate key types take a similar high-level format (note: data
57types and encoding are as per RFC4251 section 5). The serialised wire
58encoding of these certificates is also used for storing them on disk.
Damien Miller0a80ca12010-02-27 07:55:05 +110059
60#define SSH_CERT_TYPE_USER 1
61#define SSH_CERT_TYPE_HOST 2
62
63RSA certificate
64
Damien Miller4e270b02010-04-16 15:56:21 +100065 string "ssh-rsa-cert-v01@openssh.com"
66 string nonce
Damien Miller0a80ca12010-02-27 07:55:05 +110067 mpint e
68 mpint n
Damien Miller4e270b02010-04-16 15:56:21 +100069 uint64 serial
Damien Miller0a80ca12010-02-27 07:55:05 +110070 uint32 type
71 string key id
72 string valid principals
73 uint64 valid after
74 uint64 valid before
Damien Miller4e270b02010-04-16 15:56:21 +100075 string critical options
76 string extensions
Damien Miller0a80ca12010-02-27 07:55:05 +110077 string reserved
78 string signature key
79 string signature
80
81DSA certificate
82
Damien Miller4e270b02010-04-16 15:56:21 +100083 string "ssh-dss-cert-v01@openssh.com"
84 string nonce
Damien Miller0a80ca12010-02-27 07:55:05 +110085 mpint p
86 mpint q
87 mpint g
88 mpint y
Damien Miller4e270b02010-04-16 15:56:21 +100089 uint64 serial
Damien Miller0a80ca12010-02-27 07:55:05 +110090 uint32 type
91 string key id
92 string valid principals
93 uint64 valid after
94 uint64 valid before
Damien Miller4e270b02010-04-16 15:56:21 +100095 string critical options
96 string extensions
Damien Miller0a80ca12010-02-27 07:55:05 +110097 string reserved
98 string signature key
99 string signature
100
Damien Millereb8b60e2010-08-31 22:41:14 +1000101ECDSA certificate
102
djm@openbsd.org@openbsd.orgc357eed2017-11-03 02:32:19 +0000103 string "ecdsa-sha2-nistp256-cert-v01@openssh.com" |
104 "ecdsa-sha2-nistp384-cert-v01@openssh.com" |
105 "ecdsa-sha2-nistp521-cert-v01@openssh.com"
Damien Millereb8b60e2010-08-31 22:41:14 +1000106 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
djm@openbsd.orgfa582082016-05-03 10:27:59 +0000121ED25519 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
Damien Miller4e270b02010-04-16 15:56:21 +1000138The 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
140inducing collisions in the signature hash infeasible.
141
Damien Miller0a80ca12010-02-27 07:55:05 +1100142e and n are the RSA exponent and public modulus respectively.
143
144p, q, g, y are the DSA parameters as described in FIPS-186-2.
145
Damien Millereb8b60e2010-08-31 22:41:14 +1000146curve and public key are respectively the ECDSA "[identifier]" and "Q"
147defined in section 3.1 of RFC5656.
148
djm@openbsd.orgfa582082016-05-03 10:27:59 +0000149pk is the encoded Ed25519 public key as defined by
150draft-josefsson-eddsa-ed25519-03.
151
Damien Miller4e270b02010-04-16 15:56:21 +1000152serial is an optional certificate serial number set by the CA to
153provide an abbreviated way to refer to certificates from that CA.
Damien Miller2725c212010-05-10 11:56:14 +1000154If a CA does not wish to number its certificates it must set this
Damien Miller4e270b02010-04-16 15:56:21 +1000155field to zero.
156
Damien Miller0a80ca12010-02-27 07:55:05 +1100157type specifies whether this certificate is for identification of a user
158or a host using a SSH_CERT_TYPE_... value.
159
160key id is a free-form text field that is filled in by the CA at the time
161of signing; the intention is that the contents of this field are used to
162identify the identity principal in log messages.
163
164"valid principals" is a string containing zero or more principals as
165strings packed inside it. These principals list the names for which this
166certificate is valid; hostnames for SSH_CERT_TYPE_HOST certificates and
167usernames for SSH_CERT_TYPE_USER certificates. As a special case, a
168zero-length "valid principals" field means the certificate is valid for
djm@openbsd.orgfa582082016-05-03 10:27:59 +0000169any principal of the specified type.
Damien Miller0a80ca12010-02-27 07:55:05 +1100170
171"valid after" and "valid before" specify a validity period for the
172certificate. Each represents a time in seconds since 1970-01-01
17300:00:00. A certificate is considered valid if:
Damien Millereb8b60e2010-08-31 22:41:14 +1000174
175 valid after <= current time < valid before
Damien Miller0a80ca12010-02-27 07:55:05 +1100176
Damien Miller4e270b02010-04-16 15:56:21 +1000177criticial options is a set of zero or more key options encoded as
178below. All such options are "critical" in the sense that an implementation
179must refuse to authorise a key that has an unrecognised option.
Damien Miller0a80ca12010-02-27 07:55:05 +1100180
Damien Miller4e270b02010-04-16 15:56:21 +1000181extensions is a set of zero or more optional extensions. These extensions
182are not critical, and an implementation that encounters one that it does
Damien Millerd0e4a8e2010-05-21 14:58:32 +1000183not recognise may safely ignore it.
Damien Miller0a80ca12010-02-27 07:55:05 +1100184
Damien Miller48348fc2012-04-22 11:08:30 +1000185Generally, critical options are used to control features that restrict
186access where extensions are used to enable features that grant access.
187This ensures that certificates containing unknown restrictions do not
188inadvertently grant access while allowing new protocol features to be
189enabled via extensions without breaking certificates' backwards
190compatibility.
191
Damien Miller4e270b02010-04-16 15:56:21 +1000192The reserved field is currently unused and is ignored in this version of
Damien Miller0a80ca12010-02-27 07:55:05 +1100193the protocol.
194
djm@openbsd.orgadb47ce2017-05-16 16:54:05 +0000195The signature key field contains the CA key used to sign the
196certificate. The valid key types for CA keys are ssh-rsa,
197ssh-dss, ssh-ed25519 and the ECDSA types ecdsa-sha2-nistp256,
198ecdsa-sha2-nistp384, ecdsa-sha2-nistp521. "Chained" certificates, where
199the signature key type is a certificate type itself are NOT supported.
200Note that it is possible for a RSA certificate key to be signed by a
201Ed25519 or ECDSA CA key and vice-versa.
Damien Miller0a80ca12010-02-27 07:55:05 +1100202
203signature is computed over all preceding fields from the initial string
204up to, and including the signature key. Signatures are computed and
205encoded according to the rules defined for the CA's public key algorithm
Damien Millereb8b60e2010-08-31 22:41:14 +1000206(RFC4253 section 6.6 for ssh-rsa and ssh-dss, RFC5656 for the ECDSA
djm@openbsd.orgfa582082016-05-03 10:27:59 +0000207types), and draft-josefsson-eddsa-ed25519-03 for Ed25519.
Damien Miller0a80ca12010-02-27 07:55:05 +1100208
Damien Miller4e270b02010-04-16 15:56:21 +1000209Critical options
210----------------
Damien Miller0a80ca12010-02-27 07:55:05 +1100211
Damien Miller4e270b02010-04-16 15:56:21 +1000212The critical options section of the certificate specifies zero or more
213options on the certificates validity. The format of this field
Damien Miller0a80ca12010-02-27 07:55:05 +1100214is a sequence of zero or more tuples:
215
216 string name
217 string data
218
Damien Miller1da63882010-08-05 13:03:51 +1000219Options must be lexically ordered by "name" if they appear in the
Damien Miller48348fc2012-04-22 11:08:30 +1000220sequence. Each named option may only appear once in a certificate.
Damien Miller1da63882010-08-05 13:03:51 +1000221
Damien Miller4e270b02010-04-16 15:56:21 +1000222The name field identifies the option and the data field encodes
223option-specific information (see below). All options are
224"critical", if an implementation does not recognise a option
Damien Miller0a80ca12010-02-27 07:55:05 +1100225then the validating party should refuse to accept the certificate.
226
djm@openbsd.orgd40dbdc2017-05-31 04:29:44 +0000227Custom options should append the originating author or organisation's
228domain name to the option name, e.g. "my-option@example.com".
229
djm@openbsd.orgfa582082016-05-03 10:27:59 +0000230No critical options are defined for host certificates at present. The
231supported user certificate options and the contents and structure of
232their data fields are:
Damien Miller0a80ca12010-02-27 07:55:05 +1100233
234Name Format Description
235-----------------------------------------------------------------------------
236force-command string Specifies a command that is executed
237 (replacing any the user specified on the
238 ssh command-line) whenever this key is
239 used for authentication.
240
Damien Millerd0e4a8e2010-05-21 14:58:32 +1000241source-address string Comma-separated list of source addresses
242 from which this certificate is accepted
243 for authentication. Addresses are
244 specified in CIDR format (nn.nn.nn.nn/nn
245 or hhhh::hhhh/nn).
246 If this option is not present then
247 certificates may be presented from any
248 source address.
249
250Extensions
251----------
252
253The extensions section of the certificate specifies zero or more
Damien Miller1da63882010-08-05 13:03:51 +1000254non-critical certificate extensions. The encoding and ordering of
Damien Miller48348fc2012-04-22 11:08:30 +1000255extensions in this field is identical to that of the critical options,
256as is the requirement that each name appear only once.
257
Damien Miller1da63882010-08-05 13:03:51 +1000258If an implementation does not recognise an extension, then it should
259ignore it.
Damien Millerd0e4a8e2010-05-21 14:58:32 +1000260
djm@openbsd.orgd40dbdc2017-05-31 04:29:44 +0000261Custom options should append the originating author or organisation's
262domain name to the option name, e.g. "my-option@example.com".
263
djm@openbsd.orgfa582082016-05-03 10:27:59 +0000264No extensions are defined for host certificates at present. The
265supported user certificate extensions and the contents and structure of
266their data fields are:
Damien Millerd0e4a8e2010-05-21 14:58:32 +1000267
268Name Format Description
269-----------------------------------------------------------------------------
Damien Miller0a80ca12010-02-27 07:55:05 +1100270permit-X11-forwarding empty Flag indicating that X11 forwarding
271 should be permitted. X11 forwarding will
Damien Miller4e270b02010-04-16 15:56:21 +1000272 be refused if this option is absent.
Damien Miller0a80ca12010-02-27 07:55:05 +1100273
274permit-agent-forwarding empty Flag indicating that agent forwarding
275 should be allowed. Agent forwarding
276 must not be permitted unless this
Damien Miller4e270b02010-04-16 15:56:21 +1000277 option is present.
Damien Miller0a80ca12010-02-27 07:55:05 +1100278
279permit-port-forwarding empty Flag indicating that port-forwarding
Damien Miller4e270b02010-04-16 15:56:21 +1000280 should be allowed. If this option is
Damien Miller0a80ca12010-02-27 07:55:05 +1100281 not present then no port forwarding will
282 be allowed.
283
284permit-pty empty Flag indicating that PTY allocation
285 should be permitted. In the absence of
Damien Miller4e270b02010-04-16 15:56:21 +1000286 this option PTY allocation will be
Damien Miller0a80ca12010-02-27 07:55:05 +1100287 disabled.
288
289permit-user-rc empty Flag indicating that execution of
290 ~/.ssh/rc should be permitted. Execution
291 of this script will not be permitted if
Damien Miller4e270b02010-04-16 15:56:21 +1000292 this option is not present.
Damien Miller0a80ca12010-02-27 07:55:05 +1100293
djm@openbsd.org@openbsd.orgc357eed2017-11-03 02:32:19 +0000294$OpenBSD: PROTOCOL.certkeys,v 1.13 2017/11/03 02:32:19 djm Exp $