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