Annotation of src/usr.bin/ssh/PROTOCOL.certkeys, Revision 1.3
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
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
13: certified host keys.
14:
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 constraints
20: that have been signed with some other trusted key.
21:
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.
28:
29: Certified keys are represented using two new key types:
30: ssh-rsa-cert-v00@openssh.com and ssh-dss-cert-v00@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.
33:
34: Protocol extensions
35: -------------------
36:
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.
42:
43: Authentication using the new key formats described below proceeds
44: using the existing SSH "publickey" authentication method described
45: in RFC4252 section 7.
46:
47: New public key formats
48: ----------------------
49:
50: The ssh-rsa-cert-v00@openssh.com and ssh-dss-cert-v00@openssh.com key
1.3 ! djm 51: types take a similar high-level format (note: data types and
1.1 djm 52: encoding are as per RFC4251 section 5). The serialised wire encoding of
53: these 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:
58: RSA 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:
74: DSA 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:
92: e and n are the RSA exponent and public modulus respectively.
93:
94: p, q, g, y are the DSA parameters as described in FIPS-186-2.
95:
96: type specifies whether this certificate is for identification of a user
97: or a host using a SSH_CERT_TYPE_... value.
98:
99: key id is a free-form text field that is filled in by the CA at the time
100: of signing; the intention is that the contents of this field are used to
101: identify the identity principal in log messages.
102:
103: "valid principals" is a string containing zero or more principals as
104: strings packed inside it. These principals list the names for which this
105: certificate is valid; hostnames for SSH_CERT_TYPE_HOST certificates and
106: usernames for SSH_CERT_TYPE_USER certificates. As a special case, a
107: zero-length "valid principals" field means the certificate is valid for
108: any principal of the specified type. XXX DNS wildcards?
109:
110: "valid after" and "valid before" specify a validity period for the
111: certificate. Each represents a time in seconds since 1970-01-01
112: 00:00:00. A certificate is considered valid if:
113: valid after <= current time < valid before
114:
115: constraints is a set of zero or more key constraints encoded as below.
116:
117: The 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
119: inducing collisions in the signature hash infeasible.
120:
121: The reserved field is current unused and is ignored in this version of
122: the protocol.
123:
124: signature key contains the CA key used to sign the certificate.
125: The valid key types for CA keys are ssh-rsa and ssh-dss. "Chained"
126: certificates, where the signature key type is a certificate type itself
127: are NOT supported. Note that it is possible for a RSA certificate key to
128: be signed by a DSS CA key and vice-versa.
129:
130: signature is computed over all preceding fields from the initial string
131: up to, and including the signature key. Signatures are computed and
132: encoded according to the rules defined for the CA's public key algorithm
133: (RFC4253 section 6.6 for ssh-rsa and ssh-dss).
134:
135: Constraints
136: -----------
137:
138: The constraints section of the certificate specifies zero or more
139: constraints on the certificates validity. The format of this field
140: is a sequence of zero or more tuples:
141:
142: string name
143: string data
144:
145: The name field identifies the constraint and the data field encodes
146: constraint-specific information (see below). All constraints are
147: "critical", if an implementation does not recognise a constraint
148: then the validating party should refuse to accept the certificate.
149:
150: The supported constraints and the contents and structure of their
151: data fields are:
152:
153: Name Format Description
154: -----------------------------------------------------------------------------
155: force-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:
160: permit-X11-forwarding empty Flag indicating that X11 forwarding
161: should be permitted. X11 forwarding will
162: be refused if this constraint is absent.
163:
164: permit-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:
169: permit-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:
174: permit-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:
179: permit-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:
184: source-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.
1.2 djm 192:
1.3 ! djm 193: $OpenBSD: PROTOCOL.certkeys,v 1.2 2010/03/02 23:22:44 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