xref: /openssh-portable/PROTOCOL.krl (revision 9405c621)
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
412. Certificate section
42
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
51Where "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
56Followed 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
1314. SHA1/SHA256 fingerprint sections
132
133These sections, identified as KRL_SECTION_FINGERPRINT_SHA1 and
134KRL_SECTION_FINGERPRINT_SHA256, revoke plain keys (i.e. not
135certificates) by listing their hashes:
136
137	string	public_key_hash[0]
138	....
139
140This section must contain at least one "public_key_hash". The hash blob
141is 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.
144
145This section may appear multiple times.
146
1475. KRL signature sections
148
149The KRL_SECTION_SIGNATURE section serves a different purpose to the
150preceding ones: to provide cryptographic authentication of a KRL that
151is 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
171$OpenBSD: PROTOCOL.krl,v 1.5 2018/09/12 01:21:34 djm Exp $
172