Permalink
This document describes a simple public-key certificate authentication | |
system for use by SSH. | |
Background | |
---------- | |
The SSH protocol currently supports a simple public key authentication | |
mechanism. Unlike other public key implementations, SSH eschews the use | |
of X.509 certificates and uses raw keys. This approach has some benefits | |
relating to simplicity of configuration and minimisation of attack | |
surface, but it does not support the important use-cases of centrally | |
managed, passwordless authentication and centrally certified host keys. | |
These protocol extensions build on the simple public key authentication | |
system already in SSH to allow certificate-based authentication. The | |
certificates used are not traditional X.509 certificates, with numerous | |
options and complex encoding rules, but something rather more minimal: a | |
key, some identity information and usage options that have been signed | |
with some other trusted key. | |
A sshd server may be configured to allow authentication via certified | |
keys, by extending the existing ~/.ssh/authorized_keys mechanism to | |
allow specification of certification authority keys in addition to | |
raw user keys. The ssh client will support automatic verification of | |
acceptance of certified host keys, by adding a similar ability to | |
specify CA keys in ~/.ssh/known_hosts. | |
All certificate types include certification information along with the | |
public key that is used to sign challenges. In OpenSSH, ssh-keygen | |
performs the CA signing operation. | |
Certified keys are represented using new key types: | |
ssh-rsa-cert-v01@openssh.com | |
ssh-dss-cert-v01@openssh.com | |
ecdsa-sha2-nistp256-cert-v01@openssh.com | |
ecdsa-sha2-nistp384-cert-v01@openssh.com | |
ecdsa-sha2-nistp521-cert-v01@openssh.com | |
ssh-ed25519-cert-v01@openssh.com | |
Two additional types exist for RSA certificates to force use of | |
SHA-2 signatures (SHA-256 and SHA-512 respectively): | |
rsa-sha2-256-cert-v01@openssh.com | |
rsa-sha2-512-cert-v01@openssh.com | |
These RSA/SHA-2 types should not appear in keys at rest or transmitted | |
on their wire, but do appear in a SSH_MSG_KEXINIT's host-key algorithms | |
field or in the "public key algorithm name" field of a "publickey" | |
SSH_USERAUTH_REQUEST to indicate that the signature will use the | |
specified algorithm. | |
Protocol extensions | |
------------------- | |
The SSH wire protocol includes several extensibility mechanisms. | |
These modifications shall take advantage of namespaced public key | |
algorithm names to add support for certificate authentication without | |
breaking the protocol - implementations that do not support the | |
extensions will simply ignore them. | |
Authentication using the new key formats described below proceeds | |
using the existing SSH "publickey" authentication method described | |
in RFC4252 section 7. | |
New public key formats | |
---------------------- | |
The certificate key types take a similar high-level format (note: data | |
types and encoding are as per RFC4251 section 5). The serialised wire | |
encoding of these certificates is also used for storing them on disk. | |
#define SSH_CERT_TYPE_USER 1 | |
#define SSH_CERT_TYPE_HOST 2 | |
RSA certificate | |
string "ssh-rsa-cert-v01@openssh.com" | |
string nonce | |
mpint e | |
mpint n | |
uint64 serial | |
uint32 type | |
string key id | |
string valid principals | |
uint64 valid after | |
uint64 valid before | |
string critical options | |
string extensions | |
string reserved | |
string signature key | |
string signature | |
DSA certificate | |
string "ssh-dss-cert-v01@openssh.com" | |
string nonce | |
mpint p | |
mpint q | |
mpint g | |
mpint y | |
uint64 serial | |
uint32 type | |
string key id | |
string valid principals | |
uint64 valid after | |
uint64 valid before | |
string critical options | |
string extensions | |
string reserved | |
string signature key | |
string signature | |
ECDSA certificate | |
string "ecdsa-sha2-nistp256-cert-v01@openssh.com" | | |
"ecdsa-sha2-nistp384-cert-v01@openssh.com" | | |
"ecdsa-sha2-nistp521-cert-v01@openssh.com" | |
string nonce | |
string curve | |
string public_key | |
uint64 serial | |
uint32 type | |
string key id | |
string valid principals | |
uint64 valid after | |
uint64 valid before | |
string critical options | |
string extensions | |
string reserved | |
string signature key | |
string signature | |
ED25519 certificate | |
string "ssh-ed25519-cert-v01@openssh.com" | |
string nonce | |
string pk | |
uint64 serial | |
uint32 type | |
string key id | |
string valid principals | |
uint64 valid after | |
uint64 valid before | |
string critical options | |
string extensions | |
string reserved | |
string signature key | |
string signature | |
The nonce field is a CA-provided random bitstring of arbitrary length | |
(but typically 16 or 32 bytes) included to make attacks that depend on | |
inducing collisions in the signature hash infeasible. | |
e and n are the RSA exponent and public modulus respectively. | |
p, q, g, y are the DSA parameters as described in FIPS-186-2. | |
curve and public key are respectively the ECDSA "[identifier]" and "Q" | |
defined in section 3.1 of RFC5656. | |
pk is the encoded Ed25519 public key as defined by | |
draft-josefsson-eddsa-ed25519-03. | |
serial is an optional certificate serial number set by the CA to | |
provide an abbreviated way to refer to certificates from that CA. | |
If a CA does not wish to number its certificates it must set this | |
field to zero. | |
type specifies whether this certificate is for identification of a user | |
or a host using a SSH_CERT_TYPE_... value. | |
key id is a free-form text field that is filled in by the CA at the time | |
of signing; the intention is that the contents of this field are used to | |
identify the identity principal in log messages. | |
"valid principals" is a string containing zero or more principals as | |
strings packed inside it. These principals list the names for which this | |
certificate is valid; hostnames for SSH_CERT_TYPE_HOST certificates and | |
usernames for SSH_CERT_TYPE_USER certificates. As a special case, a | |
zero-length "valid principals" field means the certificate is valid for | |
any principal of the specified type. | |
"valid after" and "valid before" specify a validity period for the | |
certificate. Each represents a time in seconds since 1970-01-01 | |
00:00:00. A certificate is considered valid if: | |
valid after <= current time < valid before | |
critical options is a set of zero or more key options encoded as | |
below. All such options are "critical" in the sense that an implementation | |
must refuse to authorise a key that has an unrecognised option. | |
extensions is a set of zero or more optional extensions. These extensions | |
are not critical, and an implementation that encounters one that it does | |
not recognise may safely ignore it. | |
Generally, critical options are used to control features that restrict | |
access where extensions are used to enable features that grant access. | |
This ensures that certificates containing unknown restrictions do not | |
inadvertently grant access while allowing new protocol features to be | |
enabled via extensions without breaking certificates' backwards | |
compatibility. | |
The reserved field is currently unused and is ignored in this version of | |
the protocol. | |
The signature key field contains the CA key used to sign the | |
certificate. The valid key types for CA keys are ssh-rsa, | |
ssh-dss, ssh-ed25519 and the ECDSA types ecdsa-sha2-nistp256, | |
ecdsa-sha2-nistp384, ecdsa-sha2-nistp521. "Chained" certificates, where | |
the signature key type is a certificate type itself are NOT supported. | |
Note that it is possible for a RSA certificate key to be signed by a | |
Ed25519 or ECDSA CA key and vice-versa. | |
signature is computed over all preceding fields from the initial string | |
up to, and including the signature key. Signatures are computed and | |
encoded according to the rules defined for the CA's public key algorithm | |
(RFC4253 section 6.6 for ssh-rsa and ssh-dss, RFC5656 for the ECDSA | |
types), and draft-josefsson-eddsa-ed25519-03 for Ed25519. | |
Critical options | |
---------------- | |
The critical options section of the certificate specifies zero or more | |
options on the certificates validity. The format of this field | |
is a sequence of zero or more tuples: | |
string name | |
string data | |
Options must be lexically ordered by "name" if they appear in the | |
sequence. Each named option may only appear once in a certificate. | |
The name field identifies the option and the data field encodes | |
option-specific information (see below). All options are | |
"critical", if an implementation does not recognise a option | |
then the validating party should refuse to accept the certificate. | |
Custom options should append the originating author or organisation's | |
domain name to the option name, e.g. "my-option@example.com". | |
No critical options are defined for host certificates at present. The | |
supported user certificate options and the contents and structure of | |
their data fields are: | |
Name Format Description | |
----------------------------------------------------------------------------- | |
force-command string Specifies a command that is executed | |
(replacing any the user specified on the | |
ssh command-line) whenever this key is | |
used for authentication. | |
source-address string Comma-separated list of source addresses | |
from which this certificate is accepted | |
for authentication. Addresses are | |
specified in CIDR format (nn.nn.nn.nn/nn | |
or hhhh::hhhh/nn). | |
If this option is not present then | |
certificates may be presented from any | |
source address. | |
Extensions | |
---------- | |
The extensions section of the certificate specifies zero or more | |
non-critical certificate extensions. The encoding and ordering of | |
extensions in this field is identical to that of the critical options, | |
as is the requirement that each name appear only once. | |
If an implementation does not recognise an extension, then it should | |
ignore it. | |
Custom options should append the originating author or organisation's | |
domain name to the option name, e.g. "my-option@example.com". | |
No extensions are defined for host certificates at present. The | |
supported user certificate extensions and the contents and structure of | |
their data fields are: | |
Name Format Description | |
----------------------------------------------------------------------------- | |
no-presence-required empty Flag indicating that signatures made | |
with this certificate need not assert | |
user presence. This option only make | |
sense for the U2F/FIDO security key | |
types that support this feature in | |
their signature formats. | |
permit-X11-forwarding empty Flag indicating that X11 forwarding | |
should be permitted. X11 forwarding will | |
be refused if this option is absent. | |
permit-agent-forwarding empty Flag indicating that agent forwarding | |
should be allowed. Agent forwarding | |
must not be permitted unless this | |
option is present. | |
permit-port-forwarding empty Flag indicating that port-forwarding | |
should be allowed. If this option is | |
not present then no port forwarding will | |
be allowed. | |
permit-pty empty Flag indicating that PTY allocation | |
should be permitted. In the absence of | |
this option PTY allocation will be | |
disabled. | |
permit-user-rc empty Flag indicating that execution of | |
~/.ssh/rc should be permitted. Execution | |
of this script will not be permitted if | |
this option is not present. | |
$OpenBSD: PROTOCOL.certkeys,v 1.17 2019/11/25 00:57:51 djm Exp $ |