blob: 115f80e5d541f8e698f831d7033592d9a4b8dc75 [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
djm@openbsd.org9405c622018-09-12 01:21:34 +000039#define KRL_SECTION_FINGERPRINT_SHA256 5
Damien Millerf3747bf2013-01-18 11:44:04 +110040
djm@openbsd.org669aee92015-01-30 01:10:33 +0000412. Certificate section
Damien Millerf3747bf2013-01-18 11:44:04 +110042
43These sections use type KRL_SECTION_CERTIFICATES to revoke certificates by
44serial number or key ID. The consist of the CA key that issued the
45certificates to be revoked and a reserved field whose contents is currently
46ignored.
47
48 string ca_key
49 string reserved
50
djm@openbsd.org669aee92015-01-30 01:10:33 +000051Where "ca_key" is the standard SSH wire serialisation of the CA's
52public key. Alternately, "ca_key" may be an empty string to indicate
53the certificate section applies to all CAs (this is most useful when
54revoking key IDs).
55
Damien Millerf3747bf2013-01-18 11:44:04 +110056Followed by one or more sections:
57
58 byte cert_section_type
59 string cert_section_data
60
61The certificate section types are:
62
63#define KRL_SECTION_CERT_SERIAL_LIST 0x20
64#define KRL_SECTION_CERT_SERIAL_RANGE 0x21
65#define KRL_SECTION_CERT_SERIAL_BITMAP 0x22
66#define KRL_SECTION_CERT_KEY_ID 0x23
67
682.1 Certificate serial list section
69
70This section is identified as KRL_SECTION_CERT_SERIAL_LIST. It revokes
71certificates by listing their serial numbers. The cert_section_data in this
72case contains:
73
74 uint64 revoked_cert_serial
75 uint64 ...
76
77This section may appear multiple times.
78
792.2. Certificate serial range section
80
81These sections use type KRL_SECTION_CERT_SERIAL_RANGE and hold
82a range of serial numbers of certificates:
83
84 uint64 serial_min
85 uint64 serial_max
86
87All certificates in the range serial_min <= serial <= serial_max are
88revoked.
89
90This section may appear multiple times.
91
922.3. Certificate serial bitmap section
93
94Bitmap sections use type KRL_SECTION_CERT_SERIAL_BITMAP and revoke keys
95by listing their serial number in a bitmap.
96
97 uint64 serial_offset
98 mpint revoked_keys_bitmap
99
100A bit set at index N in the bitmap corresponds to revocation of a keys with
101serial number (serial_offset + N).
102
103This section may appear multiple times.
104
1052.4. Revoked key ID sections
106
107KRL_SECTION_CERT_KEY_ID sections revoke particular certificate "key
108ID" strings. This may be useful in revoking all certificates
109associated with a particular identity, e.g. a host or a user.
110
111 string key_id[0]
112 ...
113
114This section must contain at least one "key_id". This section may appear
115multiple times.
116
1173. Explicit key sections
118
119These sections, identified as KRL_SECTION_EXPLICIT_KEY, revoke keys
120(not certificates). They are less space efficient than serial numbers,
121but are able to revoke plain keys.
122
123 string public_key_blob[0]
124 ....
125
126This section must contain at least one "public_key_blob". The blob
127must be a raw key (i.e. not a certificate).
128
129This section may appear multiple times.
130
djm@openbsd.org9405c622018-09-12 01:21:34 +00001314. SHA1/SHA256 fingerprint sections
Damien Millerf3747bf2013-01-18 11:44:04 +1100132
djm@openbsd.org9405c622018-09-12 01:21:34 +0000133These sections, identified as KRL_SECTION_FINGERPRINT_SHA1 and
134KRL_SECTION_FINGERPRINT_SHA256, revoke plain keys (i.e. not
135certificates) by listing their hashes:
Damien Millerf3747bf2013-01-18 11:44:04 +1100136
137 string public_key_hash[0]
138 ....
139
140This section must contain at least one "public_key_hash". The hash blob
djm@openbsd.org9405c622018-09-12 01:21:34 +0000141is obtained by taking the SHA1 or SHA256 hash of the public key blob.
142Hashes in this section must appear in numeric order, treating each hash
143as a big-endian integer.
Damien Millerf3747bf2013-01-18 11:44:04 +1100144
145This section may appear multiple times.
146
1475. KRL signature sections
148
149The KRL_SECTION_SIGNATURE section serves a different purpose to the
djm@openbsd.org001aa552018-04-10 00:10:49 +0000150preceding ones: to provide cryptographic authentication of a KRL that
Damien Millerf3747bf2013-01-18 11:44:04 +1100151is retrieved over a channel that does not provide integrity protection.
152Its format is slightly different to the previously-described sections:
153in order to simplify the signature generation, it includes as a "body"
154two string components instead of one.
155
156 byte KRL_SECTION_SIGNATURE
157 string signature_key
158 string signature
159
160The signature is calculated over the entire KRL from the KRL_MAGIC
161to this subsection's "signature_key", including both and using the
162signature generation rules appropriate for the type of "signature_key".
163
164This section must appear last in the KRL. If multiple signature sections
165appear, they must appear consecutively at the end of the KRL file.
166
167Implementations that retrieve KRLs over untrusted channels must verify
168signatures. Signature sections are optional for KRLs distributed by
169trusted means.
170
djm@openbsd.org9405c622018-09-12 01:21:34 +0000171$OpenBSD: PROTOCOL.krl,v 1.5 2018/09/12 01:21:34 djm Exp $