1248613SdesThis describes the key/certificate revocation list format for OpenSSH. 2248613Sdes 3248613Sdes1. Overall format 4248613Sdes 5248613SdesThe KRL consists of a header and zero or more sections. The header is: 6248613Sdes 7248613Sdes#define KRL_MAGIC 0x5353484b524c0a00ULL /* "SSHKRL\n\0" */ 8248613Sdes#define KRL_FORMAT_VERSION 1 9248613Sdes 10248613Sdes uint64 KRL_MAGIC 11248613Sdes uint32 KRL_FORMAT_VERSION 12248613Sdes uint64 krl_version 13248613Sdes uint64 generated_date 14248613Sdes uint64 flags 15248613Sdes string reserved 16248613Sdes string comment 17248613Sdes 18248613SdesWhere "krl_version" is a version number that increases each time the KRL 19248613Sdesis modified, "generated_date" is the time in seconds since 1970-01-01 20248613Sdes00:00:00 UTC that the KRL was generated, "comment" is an optional comment 21248613Sdesand "reserved" an extension field whose contents are currently ignored. 22248613SdesNo "flags" are currently defined. 23248613Sdes 24248613SdesFollowing the header are zero or more sections, each consisting of: 25248613Sdes 26248613Sdes byte section_type 27248613Sdes string section_data 28248613Sdes 29248613SdesWhere "section_type" indicates the type of the "section_data". An exception 30248613Sdesto this is the KRL_SECTION_SIGNATURE section, that has a slightly different 31248613Sdesformat (see below). 32248613Sdes 33248613SdesThe available section types are: 34248613Sdes 35248613Sdes#define KRL_SECTION_CERTIFICATES 1 36248613Sdes#define KRL_SECTION_EXPLICIT_KEY 2 37248613Sdes#define KRL_SECTION_FINGERPRINT_SHA1 3 38248613Sdes#define KRL_SECTION_SIGNATURE 4 39248613Sdes 40295367Sdes2. Certificate section 41248613Sdes 42248613SdesThese sections use type KRL_SECTION_CERTIFICATES to revoke certificates by 43248613Sdesserial number or key ID. The consist of the CA key that issued the 44248613Sdescertificates to be revoked and a reserved field whose contents is currently 45248613Sdesignored. 46248613Sdes 47248613Sdes string ca_key 48248613Sdes string reserved 49248613Sdes 50295367SdesWhere "ca_key" is the standard SSH wire serialisation of the CA's 51295367Sdespublic key. Alternately, "ca_key" may be an empty string to indicate 52295367Sdesthe certificate section applies to all CAs (this is most useful when 53295367Sdesrevoking key IDs). 54295367Sdes 55248613SdesFollowed by one or more sections: 56248613Sdes 57248613Sdes byte cert_section_type 58248613Sdes string cert_section_data 59248613Sdes 60248613SdesThe certificate section types are: 61248613Sdes 62248613Sdes#define KRL_SECTION_CERT_SERIAL_LIST 0x20 63248613Sdes#define KRL_SECTION_CERT_SERIAL_RANGE 0x21 64248613Sdes#define KRL_SECTION_CERT_SERIAL_BITMAP 0x22 65248613Sdes#define KRL_SECTION_CERT_KEY_ID 0x23 66248613Sdes 67248613Sdes2.1 Certificate serial list section 68248613Sdes 69248613SdesThis section is identified as KRL_SECTION_CERT_SERIAL_LIST. It revokes 70248613Sdescertificates by listing their serial numbers. The cert_section_data in this 71248613Sdescase contains: 72248613Sdes 73248613Sdes uint64 revoked_cert_serial 74248613Sdes uint64 ... 75248613Sdes 76248613SdesThis section may appear multiple times. 77248613Sdes 78248613Sdes2.2. Certificate serial range section 79248613Sdes 80248613SdesThese sections use type KRL_SECTION_CERT_SERIAL_RANGE and hold 81248613Sdesa range of serial numbers of certificates: 82248613Sdes 83248613Sdes uint64 serial_min 84248613Sdes uint64 serial_max 85248613Sdes 86248613SdesAll certificates in the range serial_min <= serial <= serial_max are 87248613Sdesrevoked. 88248613Sdes 89248613SdesThis section may appear multiple times. 90248613Sdes 91248613Sdes2.3. Certificate serial bitmap section 92248613Sdes 93248613SdesBitmap sections use type KRL_SECTION_CERT_SERIAL_BITMAP and revoke keys 94248613Sdesby listing their serial number in a bitmap. 95248613Sdes 96248613Sdes uint64 serial_offset 97248613Sdes mpint revoked_keys_bitmap 98248613Sdes 99248613SdesA bit set at index N in the bitmap corresponds to revocation of a keys with 100248613Sdesserial number (serial_offset + N). 101248613Sdes 102248613SdesThis section may appear multiple times. 103248613Sdes 104248613Sdes2.4. Revoked key ID sections 105248613Sdes 106248613SdesKRL_SECTION_CERT_KEY_ID sections revoke particular certificate "key 107248613SdesID" strings. This may be useful in revoking all certificates 108248613Sdesassociated with a particular identity, e.g. a host or a user. 109248613Sdes 110248613Sdes string key_id[0] 111248613Sdes ... 112248613Sdes 113248613SdesThis section must contain at least one "key_id". This section may appear 114248613Sdesmultiple times. 115248613Sdes 116248613Sdes3. Explicit key sections 117248613Sdes 118248613SdesThese sections, identified as KRL_SECTION_EXPLICIT_KEY, revoke keys 119248613Sdes(not certificates). They are less space efficient than serial numbers, 120248613Sdesbut are able to revoke plain keys. 121248613Sdes 122248613Sdes string public_key_blob[0] 123248613Sdes .... 124248613Sdes 125248613SdesThis section must contain at least one "public_key_blob". The blob 126248613Sdesmust be a raw key (i.e. not a certificate). 127248613Sdes 128248613SdesThis section may appear multiple times. 129248613Sdes 130248613Sdes4. SHA1 fingerprint sections 131248613Sdes 132248613SdesThese sections, identified as KRL_SECTION_FINGERPRINT_SHA1, revoke 133248613Sdesplain keys (i.e. not certificates) by listing their SHA1 hashes: 134248613Sdes 135248613Sdes string public_key_hash[0] 136248613Sdes .... 137248613Sdes 138248613SdesThis section must contain at least one "public_key_hash". The hash blob 139248613Sdesis obtained by taking the SHA1 hash of the public key blob. Hashes in 140248613Sdesthis section must appear in numeric order, treating each hash as a big- 141248613Sdesendian integer. 142248613Sdes 143248613SdesThis section may appear multiple times. 144248613Sdes 145248613Sdes5. KRL signature sections 146248613Sdes 147248613SdesThe KRL_SECTION_SIGNATURE section serves a different purpose to the 148248613Sdespreceeding ones: to provide cryptographic authentication of a KRL that 149248613Sdesis retrieved over a channel that does not provide integrity protection. 150248613SdesIts format is slightly different to the previously-described sections: 151248613Sdesin order to simplify the signature generation, it includes as a "body" 152248613Sdestwo string components instead of one. 153248613Sdes 154248613Sdes byte KRL_SECTION_SIGNATURE 155248613Sdes string signature_key 156248613Sdes string signature 157248613Sdes 158248613SdesThe signature is calculated over the entire KRL from the KRL_MAGIC 159248613Sdesto this subsection's "signature_key", including both and using the 160248613Sdessignature generation rules appropriate for the type of "signature_key". 161248613Sdes 162248613SdesThis section must appear last in the KRL. If multiple signature sections 163248613Sdesappear, they must appear consecutively at the end of the KRL file. 164248613Sdes 165248613SdesImplementations that retrieve KRLs over untrusted channels must verify 166248613Sdessignatures. Signature sections are optional for KRLs distributed by 167248613Sdestrusted means. 168248613Sdes 169295367Sdes$OpenBSD: PROTOCOL.krl,v 1.3 2015/01/30 01:10:33 djm Exp $ 170