1 files changed, 193 insertions, 0 deletions

diff --git a/PROTOCOL.certkeys b/PROTOCOL.certkeys
new file mode 100644
index 000000000..1ed9e2064
--- /dev/null
+++ b/PROTOCOL.certkeys
@@ -0,0 +1,193 @@
+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 constraints
+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.
+
+Certified keys are represented using two new key types:
+ssh-rsa-cert-v00@openssh.com and ssh-dss-cert-v00@openssh.com that
+include certification information along with the public key that is used
+to sign challenges. ssh-keygen performs the CA signing operation.
+
+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 ssh-rsa-cert-v00@openssh.com and ssh-dss-cert-v00@openssh.com 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-v00@openssh.com"
+    mpint     e
+    mpint     n
+    uint32    type
+    string    key id
+    string    valid principals
+    uint64    valid after
+    uint64    valid before
+    string    constraints
+    string    nonce
+    string    reserved
+    string    signature key
+    string    signature
+
+DSA certificate
+
+    string    "ssh-dss-cert-v00@openssh.com"
+    mpint     p
+    mpint     q
+    mpint     g
+    mpint     y
+    uint32    type
+    string    key id
+    string    valid principals
+    uint64    valid after
+    uint64    valid before
+    string    constraints
+    string    nonce
+    string    reserved
+    string    signature key
+    string    signature
+
+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.
+
+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. XXX DNS wildcards?
+
+"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
+
+constraints is a set of zero or more key constraints encoded as below.
+
+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.
+
+The reserved field is current unused and is ignored in this version of
+the protocol.
+
+signature key contains the CA key used to sign the certificate.
+The valid key types for CA keys are ssh-rsa and ssh-dss. "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 DSS 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).
+
+Constraints
+-----------
+
+The constraints section of the certificate specifies zero or more
+constraints on the certificates validity. The format of this field
+is a sequence of zero or more tuples:
+
+    string       name
+    string       data
+
+The name field identifies the constraint and the data field encodes
+constraint-specific information (see below). All constraints are
+"critical", if an implementation does not recognise a constraint
+then the validating party should refuse to accept the certificate.
+
+The supported constraints 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.
+
+permit-X11-forwarding   empty         Flag indicating that X11 forwarding
+                                      should be permitted. X11 forwarding will
+                                      be refused if this constraint is absent.
+
+permit-agent-forwarding empty         Flag indicating that agent forwarding
+                                      should be allowed. Agent forwarding
+                                      must not be permitted unless this
+                                      constraint is present.
+
+permit-port-forwarding  empty         Flag indicating that port-forwarding
+                                      should be allowed. If this constraint 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 constraint 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 constraint is not present.
+
+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 constraint is not present then
+                                      certificates may be presented from any
+                                      source address.
+
+$OpenBSD: PROTOCOL.certkeys,v 1.3 2010/03/03 22:50:40 djm Exp $