1 This document describes a simple public-key certificate authentication
7 The SSH protocol currently supports a simple public key authentication
8 mechanism. Unlike other public key implementations, SSH eschews the
9 use of X.509 certificates and uses raw keys. This approach has some
10 benefits relating to simplicity of configuration and minimisation
11 of attack surface, but it does not support the important use-cases
12 of centrally managed, passwordless authentication and centrally
15 These protocol extensions build on the simple public key authentication
16 system already in SSH to allow certificate-based authentication.
17 The certificates used are not traditional X.509 certificates, with
18 numerous options and complex encoding rules, but something rather
19 more minimal: a key, some identity information and usage options
20 that have been signed with some other trusted key.
22 A sshd server may be configured to allow authentication via certified
23 keys, by extending the existing ~/.ssh/authorized_keys mechanism
24 to allow specification of certification authority keys in addition
25 to raw user keys. The ssh client will support automatic verification
26 of acceptance of certified host keys, by adding a similar ability
27 to specify CA keys in ~/.ssh/known_hosts.
29 Certified keys are represented using two new key types:
30 ssh-rsa-cert-v01@openssh.com and ssh-dss-cert-v01@openssh.com that
31 include certification information along with the public key that is used
32 to sign challenges. ssh-keygen performs the CA signing operation.
37 The SSH wire protocol includes several extensibility mechanisms.
38 These modifications shall take advantage of namespaced public key
39 algorithm names to add support for certificate authentication without
40 breaking the protocol - implementations that do not support the
41 extensions will simply ignore them.
43 Authentication using the new key formats described below proceeds
44 using the existing SSH "publickey" authentication method described
47 New public key formats
48 ----------------------
50 The ssh-rsa-cert-v01@openssh.com and ssh-dss-cert-v01@openssh.com key
51 types take a similar high-level format (note: data types and
52 encoding are as per RFC4251 section 5). The serialised wire encoding of
53 these certificates is also used for storing them on disk.
55 #define SSH_CERT_TYPE_USER 1
56 #define SSH_CERT_TYPE_HOST 2
60 string "ssh-rsa-cert-v01@openssh.com"
67 string valid principals
70 string critical options
78 string "ssh-dss-cert-v01@openssh.com"
87 string valid principals
90 string critical options
96 The 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
98 inducing collisions in the signature hash infeasible.
100 e and n are the RSA exponent and public modulus respectively.
102 p, q, g, y are the DSA parameters as described in FIPS-186-2.
104 serial is an optional certificate serial number set by the CA to
105 provide an abbreviated way to refer to certificates from that CA.
106 If a CA does not wish to number its certificates it must set this
109 type specifies whether this certificate is for identification of a user
110 or a host using a SSH_CERT_TYPE_... value.
112 key id is a free-form text field that is filled in by the CA at the time
113 of signing; the intention is that the contents of this field are used to
114 identify the identity principal in log messages.
116 "valid principals" is a string containing zero or more principals as
117 strings packed inside it. These principals list the names for which this
118 certificate is valid; hostnames for SSH_CERT_TYPE_HOST certificates and
119 usernames for SSH_CERT_TYPE_USER certificates. As a special case, a
120 zero-length "valid principals" field means the certificate is valid for
121 any principal of the specified type. XXX DNS wildcards?
123 "valid after" and "valid before" specify a validity period for the
124 certificate. Each represents a time in seconds since 1970-01-01
125 00:00:00. A certificate is considered valid if:
126 valid after <= current time < valid before
128 criticial options is a set of zero or more key options encoded as
129 below. All such options are "critical" in the sense that an implementation
130 must refuse to authorise a key that has an unrecognised option.
132 extensions is a set of zero or more optional extensions. These extensions
133 are not critical, and an implementation that encounters one that it does
134 not recognise may safely ignore it.
136 The reserved field is currently unused and is ignored in this version of
139 signature key contains the CA key used to sign the certificate.
140 The valid key types for CA keys are ssh-rsa and ssh-dss. "Chained"
141 certificates, where the signature key type is a certificate type itself
142 are NOT supported. Note that it is possible for a RSA certificate key to
143 be signed by a DSS CA key and vice-versa.
145 signature is computed over all preceding fields from the initial string
146 up to, and including the signature key. Signatures are computed and
147 encoded according to the rules defined for the CA's public key algorithm
148 (RFC4253 section 6.6 for ssh-rsa and ssh-dss).
153 The critical options section of the certificate specifies zero or more
154 options on the certificates validity. The format of this field
155 is a sequence of zero or more tuples:
160 Options must be lexically ordered by "name" if they appear in the
163 The name field identifies the option and the data field encodes
164 option-specific information (see below). All options are
165 "critical", if an implementation does not recognise a option
166 then the validating party should refuse to accept the certificate.
168 The supported options and the contents and structure of their
171 Name Format Description
172 -----------------------------------------------------------------------------
173 force-command string Specifies a command that is executed
174 (replacing any the user specified on the
175 ssh command-line) whenever this key is
176 used for authentication.
178 source-address string Comma-separated list of source addresses
179 from which this certificate is accepted
180 for authentication. Addresses are
181 specified in CIDR format (nn.nn.nn.nn/nn
183 If this option is not present then
184 certificates may be presented from any
190 The extensions section of the certificate specifies zero or more
191 non-critical certificate extensions. The encoding and ordering of
192 extensions in this field is identical to that of the critical options.
193 If an implementation does not recognise an extension, then it should
196 The supported extensions and the contents and structure of their data
199 Name Format Description
200 -----------------------------------------------------------------------------
201 permit-X11-forwarding empty Flag indicating that X11 forwarding
202 should be permitted. X11 forwarding will
203 be refused if this option is absent.
205 permit-agent-forwarding empty Flag indicating that agent forwarding
206 should be allowed. Agent forwarding
207 must not be permitted unless this
210 permit-port-forwarding empty Flag indicating that port-forwarding
211 should be allowed. If this option is
212 not present then no port forwarding will
215 permit-pty empty Flag indicating that PTY allocation
216 should be permitted. In the absence of
217 this option PTY allocation will be
220 permit-user-rc empty Flag indicating that execution of
221 ~/.ssh/rc should be permitted. Execution
222 of this script will not be permitted if
223 this option is not present.
225 $OpenBSD: PROTOCOL.certkeys,v 1.7 2010/08/04 05:40:39 djm Exp $