summaryrefslogtreecommitdiff
path: root/PROTOCOL.certkeys
diff options
context:
space:
mode:
Diffstat (limited to 'PROTOCOL.certkeys')
-rw-r--r--PROTOCOL.certkeys193
1 files changed, 193 insertions, 0 deletions
diff --git a/PROTOCOL.certkeys b/PROTOCOL.certkeys
new file mode 100644
index 000000000..1ed9e2064
--- /dev/null
+++ b/PROTOCOL.certkeys
@@ -0,0 +1,193 @@
1This 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
19more minimal: a key, some identity information and usage constraints
20that 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:
30ssh-rsa-cert-v00@openssh.com and ssh-dss-cert-v00@openssh.com that
31include 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
50The ssh-rsa-cert-v00@openssh.com and ssh-dss-cert-v00@openssh.com key
51types take a similar high-level format (note: data types and
52encoding 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
60 string "ssh-rsa-cert-v00@openssh.com"
61 mpint e
62 mpint n
63 uint32 type
64 string key id
65 string valid principals
66 uint64 valid after
67 uint64 valid before
68 string constraints
69 string nonce
70 string reserved
71 string signature key
72 string signature
73
74DSA certificate
75
76 string "ssh-dss-cert-v00@openssh.com"
77 mpint p
78 mpint q
79 mpint g
80 mpint y
81 uint32 type
82 string key id
83 string valid principals
84 uint64 valid after
85 uint64 valid before
86 string constraints
87 string nonce
88 string reserved
89 string signature key
90 string signature
91
92e and n are the RSA exponent and public modulus respectively.
93
94p, q, g, y are the DSA parameters as described in FIPS-186-2.
95
96type specifies whether this certificate is for identification of a user
97or a host using a SSH_CERT_TYPE_... value.
98
99key id is a free-form text field that is filled in by the CA at the time
100of signing; the intention is that the contents of this field are used to
101identify the identity principal in log messages.
102
103"valid principals" is a string containing zero or more principals as
104strings packed inside it. These principals list the names for which this
105certificate is valid; hostnames for SSH_CERT_TYPE_HOST certificates and
106usernames for SSH_CERT_TYPE_USER certificates. As a special case, a
107zero-length "valid principals" field means the certificate is valid for
108any principal of the specified type. XXX DNS wildcards?
109
110"valid after" and "valid before" specify a validity period for the
111certificate. Each represents a time in seconds since 1970-01-01
11200:00:00. A certificate is considered valid if:
113 valid after <= current time < valid before
114
115constraints is a set of zero or more key constraints encoded as below.
116
117The nonce field is a CA-provided random bitstring of arbitrary length
118(but typically 16 or 32 bytes) included to make attacks that depend on
119inducing collisions in the signature hash infeasible.
120
121The reserved field is current unused and is ignored in this version of
122the protocol.
123
124signature key contains the CA key used to sign the certificate.
125The valid key types for CA keys are ssh-rsa and ssh-dss. "Chained"
126certificates, where the signature key type is a certificate type itself
127are NOT supported. Note that it is possible for a RSA certificate key to
128be signed by a DSS CA key and vice-versa.
129
130signature is computed over all preceding fields from the initial string
131up to, and including the signature key. Signatures are computed and
132encoded according to the rules defined for the CA's public key algorithm
133(RFC4253 section 6.6 for ssh-rsa and ssh-dss).
134
135Constraints
136-----------
137
138The constraints section of the certificate specifies zero or more
139constraints on the certificates validity. The format of this field
140is a sequence of zero or more tuples:
141
142 string name
143 string data
144
145The name field identifies the constraint and the data field encodes
146constraint-specific information (see below). All constraints are
147"critical", if an implementation does not recognise a constraint
148then the validating party should refuse to accept the certificate.
149
150The supported constraints and the contents and structure of their
151data fields are:
152
153Name Format Description
154-----------------------------------------------------------------------------
155force-command string Specifies a command that is executed
156 (replacing any the user specified on the
157 ssh command-line) whenever this key is
158 used for authentication.
159
160permit-X11-forwarding empty Flag indicating that X11 forwarding
161 should be permitted. X11 forwarding will
162 be refused if this constraint is absent.
163
164permit-agent-forwarding empty Flag indicating that agent forwarding
165 should be allowed. Agent forwarding
166 must not be permitted unless this
167 constraint is present.
168
169permit-port-forwarding empty Flag indicating that port-forwarding
170 should be allowed. If this constraint is
171 not present then no port forwarding will
172 be allowed.
173
174permit-pty empty Flag indicating that PTY allocation
175 should be permitted. In the absence of
176 this constraint PTY allocation will be
177 disabled.
178
179permit-user-rc empty Flag indicating that execution of
180 ~/.ssh/rc should be permitted. Execution
181 of this script will not be permitted if
182 this constraint is not present.
183
184source-address string Comma-separated list of source addresses
185 from which this certificate is accepted
186 for authentication. Addresses are
187 specified in CIDR format (nn.nn.nn.nn/nn
188 or hhhh::hhhh/nn).
189 If this constraint is not present then
190 certificates may be presented from any
191 source address.
192
193$OpenBSD: PROTOCOL.certkeys,v 1.3 2010/03/03 22:50:40 djm Exp $