summaryrefslogtreecommitdiffstats
path: root/PROTOCOL.certkeys
diff options
context:
space:
mode:
Diffstat (limited to 'PROTOCOL.certkeys')
-rw-r--r--PROTOCOL.certkeys321
1 files changed, 321 insertions, 0 deletions
diff --git a/PROTOCOL.certkeys b/PROTOCOL.certkeys
new file mode 100644
index 0000000..68622e6
--- /dev/null
+++ b/PROTOCOL.certkeys
@@ -0,0 +1,321 @@
+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 the 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 RFC8032.
+
+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 RFC8032 for Ed25519).
+
+Critical options
+----------------
+
+The critical options section of the certificate specifies zero or more
+options on the certificate's 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.
+
+verify-required empty Flag indicating that signatures made
+ with this certificate must assert FIDO
+ user verification (e.g. PIN or
+ biometric). This option only makes sense
+ for the U2F/FIDO security key types that
+ support this feature in their signature
+ formats.
+
+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-touch-required empty Flag indicating that signatures made
+ with this certificate need not assert
+ FIDO user presence. This option only
+ makes 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.19 2021/06/05 13:47:00 naddy Exp $
generated by cgit v1.2.3 (git 2.39.1) at 2024-05-03 16:01:01 +0000