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