PROTOCOL.certkeys

   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
  19 more minimal: a key, some identity information and usage constraints
  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:
  30 ssh-rsa-cert-v00@openssh.com and ssh-dss-cert-v00@openssh.com that
  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
  50 The ssh-rsa-cert-v00@openssh.com and ssh-dss-cert-v00@openssh.com key
  51 types take a similar high-level format (note: data types and
  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
  60     string    "ssh-rsa-cert-v00@openssh.com"
  61     mpint     e
  62     mpint     n
  63     uint32    type
  64     string    key id
  65     string    valid principals
  66     uint64    valid after
  67     uint64    valid before
  68     string    constraints
  69     string    nonce
  70     string    reserved
  71     string    signature key
  72     string    signature
  73
  74 DSA certificate
  75
  76     string    "ssh-dss-cert-v00@openssh.com"
  77     mpint     p
  78     mpint     q
  79     mpint     g
  80     mpint     y
  81     uint32    type
  82     string    key id
  83     string    valid principals
  84     uint64    valid after
  85     uint64    valid before
  86     string    constraints
  87     string    nonce
  88     string    reserved
  89     string    signature key
  90     string    signature
  91
  92 e and n are the RSA exponent and public modulus respectively.
  93
  94 p, q, g, y are the DSA parameters as described in FIPS-186-2.
  95
  96 type specifies whether this certificate is for identification of a user
  97 or a host using a SSH_CERT_TYPE_... value.
  98
  99 key id is a free-form text field that is filled in by the CA at the time
 100 of signing; the intention is that the contents of this field are used to
 101 identify the identity principal in log messages.
 102
 103 "valid principals" is a string containing zero or more principals as
 104 strings packed inside it. These principals list the names for which this
 105 certificate is valid; hostnames for SSH_CERT_TYPE_HOST certificates and
 106 usernames for SSH_CERT_TYPE_USER certificates. As a special case, a
 107 zero-length "valid principals" field means the certificate is valid for
 108 any principal of the specified type. XXX DNS wildcards?
 109
 110 "valid after" and "valid before" specify a validity period for the
 111 certificate. Each represents a time in seconds since 1970-01-01
 112 00:00:00. A certificate is considered valid if:
 113          valid after <= current time < valid before
 114
 115 constraints is a set of zero or more key constraints encoded as below.
 116
 117 The nonce field is a CA-provided random bitstring of arbitrary length
 118 (but typically 16 or 32 bytes) included to make attacks that depend on
 119 inducing collisions in the signature hash infeasible.
 120
 121 The reserved field is current unused and is ignored in this version of
 122 the protocol.
 123
 124 signature key contains the CA key used to sign the certificate.
 125 The valid key types for CA keys are ssh-rsa and ssh-dss. "Chained"
 126 certificates, where the signature key type is a certificate type itself
 127 are NOT supported. Note that it is possible for a RSA certificate key to
 128 be signed by a DSS CA key and vice-versa.
 129
 130 signature is computed over all preceding fields from the initial string
 131 up to, and including the signature key. Signatures are computed and
 132 encoded according to the rules defined for the CA's public key algorithm
 133 (RFC4253 section 6.6 for ssh-rsa and ssh-dss).
 134
 135 Constraints
 136 -----------
 137
 138 The constraints section of the certificate specifies zero or more
 139 constraints on the certificates validity. The format of this field
 140 is a sequence of zero or more tuples:
 141
 142     string       name
 143     string       data
 144
 145 The name field identifies the constraint and the data field encodes
 146 constraint-specific information (see below). All constraints are
 147 "critical", if an implementation does not recognise a constraint
 148 then the validating party should refuse to accept the certificate.
 149
 150 The supported constraints and the contents and structure of their
 151 data fields are:
 152
 153 Name                    Format        Description
 154 -----------------------------------------------------------------------------
 155 force-command           string        Specifies a command that is executed
 156                                       (replacing any the user specified on the
 157                                       ssh command-line) whenever this key is
 158                                       used for authentication.
 159
 160 permit-X11-forwarding   empty         Flag indicating that X11 forwarding
 161                                       should be permitted. X11 forwarding will
 162                                       be refused if this constraint is absent.
 163
 164 permit-agent-forwarding empty         Flag indicating that agent forwarding
 165                                       should be allowed. Agent forwarding
 166                                       must not be permitted unless this
 167                                       constraint is present.
 168
 169 permit-port-forwarding  empty         Flag indicating that port-forwarding
 170                                       should be allowed. If this constraint is
 171                                       not present then no port forwarding will
 172                                       be allowed.
 173
 174 permit-pty              empty         Flag indicating that PTY allocation
 175                                       should be permitted. In the absence of
 176                                       this constraint PTY allocation will be
 177                                       disabled.
 178
 179 permit-user-rc          empty         Flag indicating that execution of
 180                                       ~/.ssh/rc should be permitted. Execution
 181                                       of this script will not be permitted if
 182                                       this constraint is not present.
 183
 184 source-address          string        Comma-separated list of source addresses
 185                                       from which this certificate is accepted
 186                                       for authentication. Addresses are
 187                                       specified in CIDR format (nn.nn.nn.nn/nn
 188                                       or hhhh::hhhh/nn).
 189                                       If this constraint is not present then
 190                                       certificates may be presented from any
 191                                       source address.
 192
 193 $OpenBSD: PROTOCOL.certkeys,v 1.3 2010/03/03 22:50:40 djm Exp $