jcs.org
jcs's openbsd hax
openbsd
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 $