Annotation of src/usr.bin/ssh/PROTOCOL.certkeys, Revision 1.4
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
1.4 ! djm 19: more minimal: a key, some identity information and usage options
1.1 djm 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:
1.4 ! djm 30: ssh-rsa-cert-v01@openssh.com and ssh-dss-cert-v01@openssh.com that
1.1 djm 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:
1.4 ! djm 50: The ssh-rsa-cert-v01@openssh.com and ssh-dss-cert-v01@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:
1.4 ! djm 60: string "ssh-rsa-cert-v01@openssh.com"
! 61: string nonce
1.1 djm 62: mpint e
63: mpint n
1.4 ! djm 64: uint64 serial
1.1 djm 65: uint32 type
66: string key id
67: string valid principals
68: uint64 valid after
69: uint64 valid before
1.4 ! djm 70: string critical options
! 71: string extensions
1.1 djm 72: string reserved
73: string signature key
74: string signature
75:
76: DSA certificate
77:
1.4 ! djm 78: string "ssh-dss-cert-v01@openssh.com"
! 79: string nonce
1.1 djm 80: mpint p
81: mpint q
82: mpint g
83: mpint y
1.4 ! djm 84: uint64 serial
1.1 djm 85: uint32 type
86: string key id
87: string valid principals
88: uint64 valid after
89: uint64 valid before
1.4 ! djm 90: string critical options
! 91: string extensions
1.1 djm 92: string reserved
93: string signature key
94: string signature
95:
1.4 ! djm 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.
! 99:
1.1 djm 100: e and n are the RSA exponent and public modulus respectively.
101:
102: p, q, g, y are the DSA parameters as described in FIPS-186-2.
103:
1.4 ! djm 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 with to number its certificates it must set this
! 107: field to zero.
! 108:
1.1 djm 109: type specifies whether this certificate is for identification of a user
110: or a host using a SSH_CERT_TYPE_... value.
111:
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.
115:
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?
122:
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
127:
1.4 ! djm 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.
! 131:
! 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. No extensions are defined at present.
1.1 djm 135:
1.4 ! djm 136: The reserved field is currently unused and is ignored in this version of
1.1 djm 137: the protocol.
138:
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.
144:
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).
149:
1.4 ! djm 150: Critical options
! 151: ----------------
1.1 djm 152:
1.4 ! djm 153: The critical options section of the certificate specifies zero or more
! 154: options on the certificates validity. The format of this field
1.1 djm 155: is a sequence of zero or more tuples:
156:
157: string name
158: string data
159:
1.4 ! djm 160: The name field identifies the option and the data field encodes
! 161: option-specific information (see below). All options are
! 162: "critical", if an implementation does not recognise a option
1.1 djm 163: then the validating party should refuse to accept the certificate.
164:
1.4 ! djm 165: The supported options and the contents and structure of their
1.1 djm 166: data fields are:
167:
168: Name Format Description
169: -----------------------------------------------------------------------------
170: force-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:
175: permit-X11-forwarding empty Flag indicating that X11 forwarding
176: should be permitted. X11 forwarding will
1.4 ! djm 177: be refused if this option is absent.
1.1 djm 178:
179: permit-agent-forwarding empty Flag indicating that agent forwarding
180: should be allowed. Agent forwarding
181: must not be permitted unless this
1.4 ! djm 182: option is present.
1.1 djm 183:
184: permit-port-forwarding empty Flag indicating that port-forwarding
1.4 ! djm 185: should be allowed. If this option is
1.1 djm 186: not present then no port forwarding will
187: be allowed.
188:
189: permit-pty empty Flag indicating that PTY allocation
190: should be permitted. In the absence of
1.4 ! djm 191: this option PTY allocation will be
1.1 djm 192: disabled.
193:
194: permit-user-rc empty Flag indicating that execution of
195: ~/.ssh/rc should be permitted. Execution
196: of this script will not be permitted if
1.4 ! djm 197: this option is not present.
1.1 djm 198:
199: source-address string Comma-separated list of source addresses
200: from which this certificate is accepted
201: for authentication. Addresses are
202: specified in CIDR format (nn.nn.nn.nn/nn
203: or hhhh::hhhh/nn).
1.4 ! djm 204: If this option is not present then
1.1 djm 205: certificates may be presented from any
206: source address.
1.2 djm 207:
1.4 ! djm 208: $OpenBSD: PROTOCOL.certkeys,v 1.3 2010/03/03 22:50:40 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