version 1.6, 2010/05/20 23:46:02 |
version 1.18, 2021/06/04 04:02:21 |
|
|
---------- |
---------- |
|
|
The SSH protocol currently supports a simple public key authentication |
The SSH protocol currently supports a simple public key authentication |
mechanism. Unlike other public key implementations, SSH eschews the |
mechanism. Unlike other public key implementations, SSH eschews the use |
use of X.509 certificates and uses raw keys. This approach has some |
of X.509 certificates and uses raw keys. This approach has some benefits |
benefits relating to simplicity of configuration and minimisation |
relating to simplicity of configuration and minimisation of attack |
of attack surface, but it does not support the important use-cases |
surface, but it does not support the important use-cases of centrally |
of centrally managed, passwordless authentication and centrally |
managed, passwordless authentication and centrally certified host keys. |
certified host keys. |
|
|
|
These protocol extensions build on the simple public key authentication |
These protocol extensions build on the simple public key authentication |
system already in SSH to allow certificate-based authentication. |
system already in SSH to allow certificate-based authentication. The |
The certificates used are not traditional X.509 certificates, with |
certificates used are not traditional X.509 certificates, with numerous |
numerous options and complex encoding rules, but something rather |
options and complex encoding rules, but something rather more minimal: a |
more minimal: a key, some identity information and usage options |
key, some identity information and usage options that have been signed |
that have been signed with some other trusted key. |
with some other trusted key. |
|
|
A sshd server may be configured to allow authentication via certified |
A sshd server may be configured to allow authentication via certified |
keys, by extending the existing ~/.ssh/authorized_keys mechanism |
keys, by extending the existing ~/.ssh/authorized_keys mechanism to |
to allow specification of certification authority keys in addition |
allow specification of certification authority keys in addition to |
to raw user keys. The ssh client will support automatic verification |
raw user keys. The ssh client will support automatic verification of |
of acceptance of certified host keys, by adding a similar ability |
acceptance of certified host keys, by adding a similar ability to |
to specify CA keys in ~/.ssh/known_hosts. |
specify CA keys in ~/.ssh/known_hosts. |
|
|
Certified keys are represented using two new key types: |
All certificate types include certification information along with the |
ssh-rsa-cert-v01@openssh.com and ssh-dss-cert-v01@openssh.com that |
public key that is used to sign challenges. In OpenSSH, ssh-keygen |
include certification information along with the public key that is used |
performs the CA signing operation. |
to sign challenges. 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 |
Protocol extensions |
------------------- |
------------------- |
|
|
|
|
New public key formats |
New public key formats |
---------------------- |
---------------------- |
|
|
The ssh-rsa-cert-v01@openssh.com and ssh-dss-cert-v01@openssh.com key |
The certificate key types take a similar high-level format (note: data |
types take a similar high-level format (note: data types and |
types and encoding are as per RFC4251 section 5). The serialised wire |
encoding are as per RFC4251 section 5). The serialised wire encoding of |
encoding of these certificates is also used for storing them on disk. |
these certificates is also used for storing them on disk. |
|
|
|
#define SSH_CERT_TYPE_USER 1 |
#define SSH_CERT_TYPE_USER 1 |
#define SSH_CERT_TYPE_HOST 2 |
#define SSH_CERT_TYPE_HOST 2 |
|
|
string signature key |
string signature key |
string signature |
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 |
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 |
(but typically 16 or 32 bytes) included to make attacks that depend on |
inducing collisions in the signature hash infeasible. |
inducing collisions in the signature hash infeasible. |
|
|
|
|
p, q, g, y are the DSA parameters as described in FIPS-186-2. |
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 |
serial is an optional certificate serial number set by the CA to |
provide an abbreviated way to refer to certificates from that CA. |
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 |
If a CA does not wish to number its certificates it must set this |
|
|
certificate is valid; hostnames for SSH_CERT_TYPE_HOST certificates and |
certificate is valid; hostnames for SSH_CERT_TYPE_HOST certificates and |
usernames for SSH_CERT_TYPE_USER certificates. As a special case, a |
usernames for SSH_CERT_TYPE_USER certificates. As a special case, a |
zero-length "valid principals" field means the certificate is valid for |
zero-length "valid principals" field means the certificate is valid for |
any principal of the specified type. XXX DNS wildcards? |
any principal of the specified type. |
|
|
"valid after" and "valid before" specify a validity period for the |
"valid after" and "valid before" specify a validity period for the |
certificate. Each represents a time in seconds since 1970-01-01 |
certificate. Each represents a time in seconds since 1970-01-01 |
00:00:00. A certificate is considered valid if: |
00:00:00. A certificate is considered valid if: |
valid after <= current time < valid before |
|
|
|
criticial options is a set of zero or more key options encoded as |
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 |
below. All such options are "critical" in the sense that an implementation |
must refuse to authorise a key that has an unrecognised option. |
must refuse to authorise a key that has an unrecognised option. |
|
|
|
|
are not critical, and an implementation that encounters one that it does |
are not critical, and an implementation that encounters one that it does |
not recognise may safely ignore it. |
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 reserved field is currently unused and is ignored in this version of |
the protocol. |
the protocol. |
|
|
signature key contains the CA key used to sign the certificate. |
The signature key field contains the CA key used to sign the |
The valid key types for CA keys are ssh-rsa and ssh-dss. "Chained" |
certificate. The valid key types for CA keys are ssh-rsa, |
certificates, where the signature key type is a certificate type itself |
ssh-dss, ssh-ed25519 and the ECDSA types ecdsa-sha2-nistp256, |
are NOT supported. Note that it is possible for a RSA certificate key to |
ecdsa-sha2-nistp384, ecdsa-sha2-nistp521. "Chained" certificates, where |
be signed by a DSS CA key and vice-versa. |
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 |
signature is computed over all preceding fields from the initial string |
up to, and including the signature key. Signatures are computed and |
up to, and including the signature key. Signatures are computed and |
encoded according to the rules defined for the CA's public key algorithm |
encoded according to the rules defined for the CA's public key algorithm |
(RFC4253 section 6.6 for ssh-rsa and ssh-dss). |
(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 |
Critical options |
---------------- |
---------------- |
|
|
string name |
string name |
string data |
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 |
The name field identifies the option and the data field encodes |
option-specific information (see below). All options are |
option-specific information (see below). All options are |
"critical", if an implementation does not recognise a option |
"critical", if an implementation does not recognise a option |
then the validating party should refuse to accept the certificate. |
then the validating party should refuse to accept the certificate. |
|
|
The supported options and the contents and structure of their |
Custom options should append the originating author or organisation's |
data fields are: |
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 |
Name Format Description |
----------------------------------------------------------------------------- |
----------------------------------------------------------------------------- |
force-command string Specifies a command that is executed |
force-command string Specifies a command that is executed |
|
|
certificates may be presented from any |
certificates may be presented from any |
source address. |
source address. |
|
|
|
verify-required empty Flag indicating that signatures made |
|
with this certificate must assert FIDO |
|
user verification (e.g. PIN or |
|
biometric). This option only make sense |
|
for the U2F/FIDO security key types that |
|
support this feature in their signature |
|
formats. |
|
|
Extensions |
Extensions |
---------- |
---------- |
|
|
The extensions section of the certificate specifies zero or more |
The extensions section of the certificate specifies zero or more |
non-critical certificate extensions. The encoding of extensions in this |
non-critical certificate extensions. The encoding and ordering of |
field is identical to that of the critical options. If an implementation |
extensions in this field is identical to that of the critical options, |
does not recognise an extension, then it should ignore it. |
as is the requirement that each name appear only once. |
|
|
The supported extensions and the contents and structure of their data |
If an implementation does not recognise an extension, then it should |
fields are: |
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 |
Name Format Description |
----------------------------------------------------------------------------- |
----------------------------------------------------------------------------- |
|
no-touch-required empty Flag indicating that signatures made |
|
with this certificate need not assert |
|
FIDO 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 |
permit-X11-forwarding empty Flag indicating that X11 forwarding |
should be permitted. X11 forwarding will |
should be permitted. X11 forwarding will |
be refused if this option is absent. |
be refused if this option is absent. |