crypto/openssh/PROTOCOL.krl

   1 This describes the key/certificate revocation list format for OpenSSH.
   2
   3 1. Overall format
   4
   5 The KRL consists of a header and zero or more sections. The header is:
   6
   7 #define KRL_MAGIC               0x5353484b524c0a00ULL  /* "SSHKRL\n\0" */
   8 #define KRL_FORMAT_VERSION      1
   9
  10         uint64  KRL_MAGIC
  11         uint32  KRL_FORMAT_VERSION
  12         uint64  krl_version
  13         uint64  generated_date
  14         uint64  flags
  15         string  reserved
  16         string  comment
  17
  18 Where "krl_version" is a version number that increases each time the KRL
  19 is modified, "generated_date" is the time in seconds since 1970-01-01
  20 00:00:00 UTC that the KRL was generated, "comment" is an optional comment
  21 and "reserved" an extension field whose contents are currently ignored.
  22 No "flags" are currently defined.
  23
  24 Following the header are zero or more sections, each consisting of:
  25
  26         byte    section_type
  27         string  section_data
  28
  29 Where "section_type" indicates the type of the "section_data". An exception
  30 to this is the KRL_SECTION_SIGNATURE section, that has a slightly different
  31 format (see below).
  32
  33 The available section types are:
  34
  35 #define KRL_SECTION_CERTIFICATES                1
  36 #define KRL_SECTION_EXPLICIT_KEY                2
  37 #define KRL_SECTION_FINGERPRINT_SHA1            3
  38 #define KRL_SECTION_SIGNATURE                   4
  39
  40 2. Certificate section
  41
  42 These sections use type KRL_SECTION_CERTIFICATES to revoke certificates by
  43 serial number or key ID. The consist of the CA key that issued the
  44 certificates to be revoked and a reserved field whose contents is currently
  45 ignored.
  46
  47         string ca_key
  48         string reserved
  49
  50 Where "ca_key" is the standard SSH wire serialisation of the CA's
  51 public key. Alternately, "ca_key" may be an empty string to indicate
  52 the certificate section applies to all CAs (this is most useful when
  53 revoking key IDs).
  54
  55 Followed by one or more sections:
  56
  57         byte    cert_section_type
  58         string  cert_section_data
  59
  60 The certificate section types are:
  61
  62 #define KRL_SECTION_CERT_SERIAL_LIST    0x20
  63 #define KRL_SECTION_CERT_SERIAL_RANGE   0x21
  64 #define KRL_SECTION_CERT_SERIAL_BITMAP  0x22
  65 #define KRL_SECTION_CERT_KEY_ID         0x23
  66
  67 2.1 Certificate serial list section
  68
  69 This section is identified as KRL_SECTION_CERT_SERIAL_LIST. It revokes
  70 certificates by listing their serial numbers. The cert_section_data in this
  71 case contains:
  72
  73         uint64  revoked_cert_serial
  74         uint64  ...
  75
  76 This section may appear multiple times.
  77
  78 2.2. Certificate serial range section
  79
  80 These sections use type KRL_SECTION_CERT_SERIAL_RANGE and hold
  81 a range of serial numbers of certificates:
  82
  83         uint64  serial_min
  84         uint64  serial_max
  85
  86 All certificates in the range serial_min <= serial <= serial_max are
  87 revoked.
  88
  89 This section may appear multiple times.
  90
  91 2.3. Certificate serial bitmap section
  92
  93 Bitmap sections use type KRL_SECTION_CERT_SERIAL_BITMAP and revoke keys
  94 by listing their serial number in a bitmap.
  95
  96         uint64  serial_offset
  97         mpint   revoked_keys_bitmap
  98
  99 A bit set at index N in the bitmap corresponds to revocation of a keys with
 100 serial number (serial_offset + N).
 101
 102 This section may appear multiple times.
 103
 104 2.4. Revoked key ID sections
 105
 106 KRL_SECTION_CERT_KEY_ID sections revoke particular certificate "key
 107 ID" strings. This may be useful in revoking all certificates
 108 associated with a particular identity, e.g. a host or a user.
 109
 110         string  key_id[0]
 111         ...
 112
 113 This section must contain at least one "key_id". This section may appear
 114 multiple times.
 115
 116 3. Explicit key sections
 117
 118 These sections, identified as KRL_SECTION_EXPLICIT_KEY, revoke keys
 119 (not certificates). They are less space efficient than serial numbers,
 120 but are able to revoke plain keys.
 121
 122         string  public_key_blob[0]
 123         ....
 124
 125 This section must contain at least one "public_key_blob". The blob
 126 must be a raw key (i.e. not a certificate).
 127
 128 This section may appear multiple times.
 129
 130 4. SHA1 fingerprint sections
 131
 132 These sections, identified as KRL_SECTION_FINGERPRINT_SHA1, revoke
 133 plain keys (i.e. not certificates) by listing their SHA1 hashes:
 134
 135         string  public_key_hash[0]
 136         ....
 137
 138 This section must contain at least one "public_key_hash". The hash blob
 139 is obtained by taking the SHA1 hash of the public key blob. Hashes in
 140 this section must appear in numeric order, treating each hash as a big-
 141 endian integer.
 142
 143 This section may appear multiple times.
 144
 145 5. KRL signature sections
 146
 147 The KRL_SECTION_SIGNATURE section serves a different purpose to the
 148 preceeding ones: to provide cryptographic authentication of a KRL that
 149 is retrieved over a channel that does not provide integrity protection.
 150 Its format is slightly different to the previously-described sections:
 151 in order to simplify the signature generation, it includes as a "body"
 152 two string components instead of one.
 153
 154         byte    KRL_SECTION_SIGNATURE
 155         string  signature_key
 156         string  signature
 157
 158 The signature is calculated over the entire KRL from the KRL_MAGIC
 159 to this subsection's "signature_key", including both and using the
 160 signature generation rules appropriate for the type of "signature_key".
 161
 162 This section must appear last in the KRL. If multiple signature sections
 163 appear, they must appear consecutively at the end of the KRL file.
 164
 165 Implementations that retrieve KRLs over untrusted channels must verify
 166 signatures. Signature sections are optional for KRLs distributed by
 167 trusted means.
 168
 169 $OpenBSD: PROTOCOL.krl,v 1.3 2015/01/30 01:10:33 djm Exp $