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 #define KRL_SECTION_EXTENSION                   255
  41
  42 2. Certificate section
  43
  44 These sections use type KRL_SECTION_CERTIFICATES to revoke certificates by
  45 serial number or key ID. The consist of the CA key that issued the
  46 certificates to be revoked and a reserved field whose contents is currently
  47 ignored.
  48
  49         string ca_key
  50         string reserved
  51
  52 Where "ca_key" is the standard SSH wire serialisation of the CA's
  53 public key. Alternately, "ca_key" may be an empty string to indicate
  54 the certificate section applies to all CAs (this is most useful when
  55 revoking key IDs).
  56
  57 Followed by one or more sections:
  58
  59         byte    cert_section_type
  60         string  cert_section_data
  61
  62 The certificate section types are:
  63
  64 #define KRL_SECTION_CERT_SERIAL_LIST    0x20
  65 #define KRL_SECTION_CERT_SERIAL_RANGE   0x21
  66 #define KRL_SECTION_CERT_SERIAL_BITMAP  0x22
  67 #define KRL_SECTION_CERT_KEY_ID         0x23
  68 #define KRL_SECTION_CERT_EXTENSION      0x39
  69
  70 2.1 Certificate serial list section
  71
  72 This section is identified as KRL_SECTION_CERT_SERIAL_LIST. It revokes
  73 certificates by listing their serial numbers. The cert_section_data in this
  74 case contains:
  75
  76         uint64  revoked_cert_serial
  77         uint64  ...
  78
  79 This section may appear multiple times.
  80
  81 2.2. Certificate serial range section
  82
  83 These sections use type KRL_SECTION_CERT_SERIAL_RANGE and hold
  84 a range of serial numbers of certificates:
  85
  86         uint64  serial_min
  87         uint64  serial_max
  88
  89 All certificates in the range serial_min <= serial <= serial_max are
  90 revoked.
  91
  92 This section may appear multiple times.
  93
  94 2.3. Certificate serial bitmap section
  95
  96 Bitmap sections use type KRL_SECTION_CERT_SERIAL_BITMAP and revoke keys
  97 by listing their serial number in a bitmap.
  98
  99         uint64  serial_offset
 100         mpint   revoked_keys_bitmap
 101
 102 A bit set at index N in the bitmap corresponds to revocation of a keys with
 103 serial number (serial_offset + N).
 104
 105 This section may appear multiple times.
 106
 107 2.4. Revoked key ID sections
 108
 109 KRL_SECTION_CERT_KEY_ID sections revoke particular certificate "key
 110 ID" strings. This may be useful in revoking all certificates
 111 associated with a particular identity, e.g. a host or a user.
 112
 113         string  key_id[0]
 114         ...
 115
 116 This section must contain at least one "key_id". This section may appear
 117 multiple times.
 118
 119 2.5. Certificate Extension subsections
 120
 121 This subsection type provides a generic extension mechanism to the
 122 certificates KRL section that may be used to provide optional or critical
 123 data.
 124
 125 Extensions are stored in subsections of type
 126 KRL_SECTION_CERT_EXTENSION with the following contents:
 127
 128         string  extension_name
 129         boolean is_critical
 130         string  extension_contents.
 131
 132 Where "extension_name" describes the type of extension. It is
 133 recommended that user extensions follow "cert-name@domain.org" naming.
 134
 135 The "is_critical" indicates whether this extension is mandatory or
 136 optional. If true, then any unsupported extension encountered should
 137 result in KRL parsing failure. If false, then it may be safely be
 138 ignored.
 139
 140 The "extension_contents" contains the body of the extension.
 141
 142 3. Explicit key sections
 143
 144 These sections, identified as KRL_SECTION_EXPLICIT_KEY, revoke keys
 145 (not certificates). They are less space efficient than serial numbers,
 146 but are able to revoke plain keys.
 147
 148         string  public_key_blob[0]
 149         ....
 150
 151 This section must contain at least one "public_key_blob". The blob
 152 must be a raw key (i.e. not a certificate).
 153
 154 This section may appear multiple times.
 155
 156 4. SHA1/SHA256 fingerprint sections
 157
 158 These sections, identified as KRL_SECTION_FINGERPRINT_SHA1 and
 159 KRL_SECTION_FINGERPRINT_SHA256, revoke plain keys (i.e. not
 160 certificates) by listing their hashes:
 161
 162         string  public_key_hash[0]
 163         ....
 164
 165 This section must contain at least one "public_key_hash". The hash blob
 166 is obtained by taking the SHA1 or SHA256 hash of the public key blob.
 167 Hashes in this section must appear in numeric order, treating each hash
 168 as a big-endian integer.
 169
 170 This section may appear multiple times.
 171
 172 5. Extension sections
 173
 174 This section type provides a generic extension mechanism to the KRL
 175 format that may be used to provide optional or critical data.
 176
 177 Extensions are recorded in sections of type KRL_SECTION_EXTENSION
 178 with the following contents:
 179
 180         string  extension_name
 181         boolean is_critical
 182         string  extension_contents.
 183
 184 Where "extension_name" describes the type of extension. It is
 185 recommended that user extensions follow "name@domain.org" naming.
 186
 187 The "is_critical" indicates whether this extension is mandatory or
 188 optional. If true, then any unsupported extension encountered should
 189 result in KRL parsing failure. If false, then it may be safely be
 190 ignored.
 191
 192 The "extension_contents" contains the body of the extension.
 193
 194 6. KRL signature sections
 195
 196 Note: KRL signatures are not supported by OpenSSH. OpenSSH >= 9.4 will
 197 refuse to load KRLs that contain signatures. We recommend the use
 198 of SSHSIG (`ssh-keygen -Y sign ...`) style signatures for KRLs instead.
 199
 200 The KRL_SECTION_SIGNATURE section serves a different purpose to the
 201 preceding ones: to provide cryptographic authentication of a KRL that
 202 is retrieved over a channel that does not provide integrity protection.
 203 Its format is slightly different to the previously-described sections:
 204 in order to simplify the signature generation, it includes as a "body"
 205 two string components instead of one.
 206
 207         byte    KRL_SECTION_SIGNATURE
 208         string  signature_key
 209         string  signature
 210
 211 The signature is calculated over the entire KRL from the KRL_MAGIC
 212 to this subsection's "signature_key", including both and using the
 213 signature generation rules appropriate for the type of "signature_key".
 214
 215 This section must appear last in the KRL. If multiple signature sections
 216 appear, they must appear consecutively at the end of the KRL file.
 217
 218 Implementations that retrieve KRLs over untrusted channels must verify
 219 signatures. Signature sections are optional for KRLs distributed by
 220 trusted means.
 221
 222 $OpenBSD: PROTOCOL.krl,v 1.7 2023/07/17 04:01:10 djm Exp $