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