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 (a] 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 (a] 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 $ 223
Indexes created Mon Apr 06 00:22:49 UTC 2026