blob: 81b02a078b75b375daf960632374fb8a536abefb [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
8mechanism. Unlike other public key implementations, SSH eschews the
9use of X.509 certificates and uses raw keys. This approach has some
10benefits relating to simplicity of configuration and minimisation
11of attack surface, but it does not support the important use-cases
12of centrally managed, passwordless authentication and centrally
13certified host keys.
14
15These protocol extensions build on the simple public key authentication
16system already in SSH to allow certificate-based authentication.
17The certificates used are not traditional X.509 certificates, with
18numerous options and complex encoding rules, but something rather
Damien Miller4e270b02010-04-16 15:56:21 +100019more minimal: a key, some identity information and usage options
Damien Miller0a80ca12010-02-27 07:55:05 +110020that have been signed with some other trusted key.
21
22A sshd server may be configured to allow authentication via certified
23keys, by extending the existing ~/.ssh/authorized_keys mechanism
24to allow specification of certification authority keys in addition
25to raw user keys. The ssh client will support automatic verification
26of acceptance of certified host keys, by adding a similar ability
27to specify CA keys in ~/.ssh/known_hosts.
28
29Certified keys are represented using two new key types:
Damien Miller4e270b02010-04-16 15:56:21 +100030ssh-rsa-cert-v01@openssh.com and ssh-dss-cert-v01@openssh.com that
Damien Miller0a80ca12010-02-27 07:55:05 +110031include certification information along with the public key that is used
32to sign challenges. ssh-keygen performs the CA signing operation.
33
34Protocol extensions
35-------------------
36
37The SSH wire protocol includes several extensibility mechanisms.
38These modifications shall take advantage of namespaced public key
39algorithm names to add support for certificate authentication without
40breaking the protocol - implementations that do not support the
41extensions will simply ignore them.
42
43Authentication using the new key formats described below proceeds
44using the existing SSH "publickey" authentication method described
45in RFC4252 section 7.
46
47New public key formats
48----------------------
49
Damien Miller4e270b02010-04-16 15:56:21 +100050The ssh-rsa-cert-v01@openssh.com and ssh-dss-cert-v01@openssh.com key
Damien Millerfe588e32010-03-04 21:52:00 +110051types take a similar high-level format (note: data types and
Damien Miller0a80ca12010-02-27 07:55:05 +110052encoding are as per RFC4251 section 5). The serialised wire encoding of
53these certificates is also used for storing them on disk.
54
55#define SSH_CERT_TYPE_USER 1
56#define SSH_CERT_TYPE_HOST 2
57
58RSA certificate
59
Damien Miller4e270b02010-04-16 15:56:21 +100060 string "ssh-rsa-cert-v01@openssh.com"
61 string nonce
Damien Miller0a80ca12010-02-27 07:55:05 +110062 mpint e
63 mpint n
Damien Miller4e270b02010-04-16 15:56:21 +100064 uint64 serial
Damien Miller0a80ca12010-02-27 07:55:05 +110065 uint32 type
66 string key id
67 string valid principals
68 uint64 valid after
69 uint64 valid before
Damien Miller4e270b02010-04-16 15:56:21 +100070 string critical options
71 string extensions
Damien Miller0a80ca12010-02-27 07:55:05 +110072 string reserved
73 string signature key
74 string signature
75
76DSA certificate
77
Damien Miller4e270b02010-04-16 15:56:21 +100078 string "ssh-dss-cert-v01@openssh.com"
79 string nonce
Damien Miller0a80ca12010-02-27 07:55:05 +110080 mpint p
81 mpint q
82 mpint g
83 mpint y
Damien Miller4e270b02010-04-16 15:56:21 +100084 uint64 serial
Damien Miller0a80ca12010-02-27 07:55:05 +110085 uint32 type
86 string key id
87 string valid principals
88 uint64 valid after
89 uint64 valid before
Damien Miller4e270b02010-04-16 15:56:21 +100090 string critical options
91 string extensions
Damien Miller0a80ca12010-02-27 07:55:05 +110092 string reserved
93 string signature key
94 string signature
95
Damien Miller4e270b02010-04-16 15:56:21 +100096The nonce field is a CA-provided random bitstring of arbitrary length
97(but typically 16 or 32 bytes) included to make attacks that depend on
98inducing collisions in the signature hash infeasible.
99
Damien Miller0a80ca12010-02-27 07:55:05 +1100100e and n are the RSA exponent and public modulus respectively.
101
102p, q, g, y are the DSA parameters as described in FIPS-186-2.
103
Damien Miller4e270b02010-04-16 15:56:21 +1000104serial is an optional certificate serial number set by the CA to
105provide an abbreviated way to refer to certificates from that CA.
Damien Miller2725c212010-05-10 11:56:14 +1000106If a CA does not wish to number its certificates it must set this
Damien Miller4e270b02010-04-16 15:56:21 +1000107field to zero.
108
Damien Miller0a80ca12010-02-27 07:55:05 +1100109type specifies whether this certificate is for identification of a user
110or a host using a SSH_CERT_TYPE_... value.
111
112key id is a free-form text field that is filled in by the CA at the time
113of signing; the intention is that the contents of this field are used to
114identify the identity principal in log messages.
115
116"valid principals" is a string containing zero or more principals as
117strings packed inside it. These principals list the names for which this
118certificate is valid; hostnames for SSH_CERT_TYPE_HOST certificates and
119usernames for SSH_CERT_TYPE_USER certificates. As a special case, a
120zero-length "valid principals" field means the certificate is valid for
121any principal of the specified type. XXX DNS wildcards?
122
123"valid after" and "valid before" specify a validity period for the
124certificate. Each represents a time in seconds since 1970-01-01
12500:00:00. A certificate is considered valid if:
126 valid after <= current time < valid before
127
Damien Miller4e270b02010-04-16 15:56:21 +1000128criticial options is a set of zero or more key options encoded as
129below. All such options are "critical" in the sense that an implementation
130must refuse to authorise a key that has an unrecognised option.
Damien Miller0a80ca12010-02-27 07:55:05 +1100131
Damien Miller4e270b02010-04-16 15:56:21 +1000132extensions is a set of zero or more optional extensions. These extensions
133are not critical, and an implementation that encounters one that it does
Damien Millerd0e4a8e2010-05-21 14:58:32 +1000134not recognise may safely ignore it.
Damien Miller0a80ca12010-02-27 07:55:05 +1100135
Damien Miller4e270b02010-04-16 15:56:21 +1000136The reserved field is currently unused and is ignored in this version of
Damien Miller0a80ca12010-02-27 07:55:05 +1100137the protocol.
138
139signature key contains the CA key used to sign the certificate.
140The valid key types for CA keys are ssh-rsa and ssh-dss. "Chained"
141certificates, where the signature key type is a certificate type itself
142are NOT supported. Note that it is possible for a RSA certificate key to
143be signed by a DSS CA key and vice-versa.
144
145signature is computed over all preceding fields from the initial string
146up to, and including the signature key. Signatures are computed and
147encoded according to the rules defined for the CA's public key algorithm
148(RFC4253 section 6.6 for ssh-rsa and ssh-dss).
149
Damien Miller4e270b02010-04-16 15:56:21 +1000150Critical options
151----------------
Damien Miller0a80ca12010-02-27 07:55:05 +1100152
Damien Miller4e270b02010-04-16 15:56:21 +1000153The critical options section of the certificate specifies zero or more
154options on the certificates validity. The format of this field
Damien Miller0a80ca12010-02-27 07:55:05 +1100155is a sequence of zero or more tuples:
156
157 string name
158 string data
159
Damien Miller4e270b02010-04-16 15:56:21 +1000160The name field identifies the option and the data field encodes
161option-specific information (see below). All options are
162"critical", if an implementation does not recognise a option
Damien Miller0a80ca12010-02-27 07:55:05 +1100163then the validating party should refuse to accept the certificate.
164
Damien Miller4e270b02010-04-16 15:56:21 +1000165The supported options and the contents and structure of their
Damien Miller0a80ca12010-02-27 07:55:05 +1100166data fields are:
167
168Name Format Description
169-----------------------------------------------------------------------------
170force-command string Specifies a command that is executed
171 (replacing any the user specified on the
172 ssh command-line) whenever this key is
173 used for authentication.
174
Damien Millerd0e4a8e2010-05-21 14:58:32 +1000175source-address string Comma-separated list of source addresses
176 from which this certificate is accepted
177 for authentication. Addresses are
178 specified in CIDR format (nn.nn.nn.nn/nn
179 or hhhh::hhhh/nn).
180 If this option is not present then
181 certificates may be presented from any
182 source address.
183
184Extensions
185----------
186
187The extensions section of the certificate specifies zero or more
188non-critical certificate extensions. The encoding of extensions in this
189field is identical to that of the critical options. If an implementation
190does not recognise an extension, then it should ignore it.
191
192The supported extensions and the contents and structure of their data
193fields are:
194
195Name Format Description
196-----------------------------------------------------------------------------
Damien Miller0a80ca12010-02-27 07:55:05 +1100197permit-X11-forwarding empty Flag indicating that X11 forwarding
198 should be permitted. X11 forwarding will
Damien Miller4e270b02010-04-16 15:56:21 +1000199 be refused if this option is absent.
Damien Miller0a80ca12010-02-27 07:55:05 +1100200
201permit-agent-forwarding empty Flag indicating that agent forwarding
202 should be allowed. Agent forwarding
203 must not be permitted unless this
Damien Miller4e270b02010-04-16 15:56:21 +1000204 option is present.
Damien Miller0a80ca12010-02-27 07:55:05 +1100205
206permit-port-forwarding empty Flag indicating that port-forwarding
Damien Miller4e270b02010-04-16 15:56:21 +1000207 should be allowed. If this option is
Damien Miller0a80ca12010-02-27 07:55:05 +1100208 not present then no port forwarding will
209 be allowed.
210
211permit-pty empty Flag indicating that PTY allocation
212 should be permitted. In the absence of
Damien Miller4e270b02010-04-16 15:56:21 +1000213 this option PTY allocation will be
Damien Miller0a80ca12010-02-27 07:55:05 +1100214 disabled.
215
216permit-user-rc empty Flag indicating that execution of
217 ~/.ssh/rc should be permitted. Execution
218 of this script will not be permitted if
Damien Miller4e270b02010-04-16 15:56:21 +1000219 this option is not present.
Damien Miller0a80ca12010-02-27 07:55:05 +1100220
Damien Millerd0e4a8e2010-05-21 14:58:32 +1000221$OpenBSD: PROTOCOL.certkeys,v 1.6 2010/05/20 23:46:02 djm Exp $