blob: f319bad21d33f479bb3b79077425c38369c5cea9 [file] [log] [blame]
Damien Millerf3747bf2013-01-18 11:44:04 +11001This 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
djm@openbsd.org669aee92015-01-30 01:10:33 +0000402. Certificate section
Damien Millerf3747bf2013-01-18 11:44:04 +110041
42These sections use type KRL_SECTION_CERTIFICATES to revoke certificates by
43serial number or key ID. The consist of the CA key that issued the
44certificates to be revoked and a reserved field whose contents is currently
45ignored.
46
47 string ca_key
48 string reserved
49
djm@openbsd.org669aee92015-01-30 01:10:33 +000050Where "ca_key" is the standard SSH wire serialisation of the CA's
51public key. Alternately, "ca_key" may be an empty string to indicate
52the certificate section applies to all CAs (this is most useful when
53revoking key IDs).
54
Damien Millerf3747bf2013-01-18 11:44:04 +110055Followed by one or more sections:
56
57 byte cert_section_type
58 string cert_section_data
59
60The 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
672.1 Certificate serial list section
68
69This section is identified as KRL_SECTION_CERT_SERIAL_LIST. It revokes
70certificates by listing their serial numbers. The cert_section_data in this
71case contains:
72
73 uint64 revoked_cert_serial
74 uint64 ...
75
76This section may appear multiple times.
77
782.2. Certificate serial range section
79
80These sections use type KRL_SECTION_CERT_SERIAL_RANGE and hold
81a range of serial numbers of certificates:
82
83 uint64 serial_min
84 uint64 serial_max
85
86All certificates in the range serial_min <= serial <= serial_max are
87revoked.
88
89This section may appear multiple times.
90
912.3. Certificate serial bitmap section
92
93Bitmap sections use type KRL_SECTION_CERT_SERIAL_BITMAP and revoke keys
94by listing their serial number in a bitmap.
95
96 uint64 serial_offset
97 mpint revoked_keys_bitmap
98
99A bit set at index N in the bitmap corresponds to revocation of a keys with
100serial number (serial_offset + N).
101
102This section may appear multiple times.
103
1042.4. Revoked key ID sections
105
106KRL_SECTION_CERT_KEY_ID sections revoke particular certificate "key
107ID" strings. This may be useful in revoking all certificates
108associated with a particular identity, e.g. a host or a user.
109
110 string key_id[0]
111 ...
112
113This section must contain at least one "key_id". This section may appear
114multiple times.
115
1163. Explicit key sections
117
118These sections, identified as KRL_SECTION_EXPLICIT_KEY, revoke keys
119(not certificates). They are less space efficient than serial numbers,
120but are able to revoke plain keys.
121
122 string public_key_blob[0]
123 ....
124
125This section must contain at least one "public_key_blob". The blob
126must be a raw key (i.e. not a certificate).
127
128This section may appear multiple times.
129
1304. SHA1 fingerprint sections
131
132These sections, identified as KRL_SECTION_FINGERPRINT_SHA1, revoke
133plain keys (i.e. not certificates) by listing their SHA1 hashes:
134
135 string public_key_hash[0]
136 ....
137
138This section must contain at least one "public_key_hash". The hash blob
139is obtained by taking the SHA1 hash of the public key blob. Hashes in
140this section must appear in numeric order, treating each hash as a big-
141endian integer.
142
143This section may appear multiple times.
144
1455. KRL signature sections
146
147The KRL_SECTION_SIGNATURE section serves a different purpose to the
djm@openbsd.org001aa552018-04-10 00:10:49 +0000148preceding ones: to provide cryptographic authentication of a KRL that
Damien Millerf3747bf2013-01-18 11:44:04 +1100149is retrieved over a channel that does not provide integrity protection.
150Its format is slightly different to the previously-described sections:
151in order to simplify the signature generation, it includes as a "body"
152two string components instead of one.
153
154 byte KRL_SECTION_SIGNATURE
155 string signature_key
156 string signature
157
158The signature is calculated over the entire KRL from the KRL_MAGIC
159to this subsection's "signature_key", including both and using the
160signature generation rules appropriate for the type of "signature_key".
161
162This section must appear last in the KRL. If multiple signature sections
163appear, they must appear consecutively at the end of the KRL file.
164
165Implementations that retrieve KRLs over untrusted channels must verify
166signatures. Signature sections are optional for KRLs distributed by
167trusted means.
168
djm@openbsd.org001aa552018-04-10 00:10:49 +0000169$OpenBSD: PROTOCOL.krl,v 1.4 2018/04/10 00:10:49 djm Exp $