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 $ 170
