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
403. Certificate serial section
41
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
50Followed by one or more sections:
51
52	byte	cert_section_type
53	string	cert_section_data
54
55The certificate section types are:
56
57#define KRL_SECTION_CERT_SERIAL_LIST	0x20
58#define KRL_SECTION_CERT_SERIAL_RANGE	0x21
59#define KRL_SECTION_CERT_SERIAL_BITMAP	0x22
60#define KRL_SECTION_CERT_KEY_ID		0x23
61
622.1 Certificate serial list section
63
64This section is identified as KRL_SECTION_CERT_SERIAL_LIST. It revokes
65certificates by listing their serial numbers. The cert_section_data in this
66case contains:
67
68	uint64	revoked_cert_serial
69	uint64	...
70
71This section may appear multiple times.
72
732.2. Certificate serial range section
74
75These sections use type KRL_SECTION_CERT_SERIAL_RANGE and hold
76a range of serial numbers of certificates:
77
78	uint64	serial_min
79	uint64	serial_max
80
81All certificates in the range serial_min <= serial <= serial_max are
82revoked.
83
84This section may appear multiple times.
85
862.3. Certificate serial bitmap section
87
88Bitmap sections use type KRL_SECTION_CERT_SERIAL_BITMAP and revoke keys
89by listing their serial number in a bitmap.
90
91	uint64	serial_offset
92	mpint	revoked_keys_bitmap
93
94A bit set at index N in the bitmap corresponds to revocation of a keys with
95serial number (serial_offset + N).
96
97This section may appear multiple times.
98
992.4. Revoked key ID sections
100
101KRL_SECTION_CERT_KEY_ID sections revoke particular certificate "key
102ID" strings. This may be useful in revoking all certificates
103associated with a particular identity, e.g. a host or a user.
104
105	string	key_id[0]
106	...
107
108This section must contain at least one "key_id". This section may appear
109multiple times.
110
1113. Explicit key sections
112
113These sections, identified as KRL_SECTION_EXPLICIT_KEY, revoke keys
114(not certificates). They are less space efficient than serial numbers,
115but are able to revoke plain keys.
116
117	string	public_key_blob[0]
118	....
119
120This section must contain at least one "public_key_blob". The blob
121must be a raw key (i.e. not a certificate).
122
123This section may appear multiple times.
124
1254. SHA1 fingerprint sections
126
127These sections, identified as KRL_SECTION_FINGERPRINT_SHA1, revoke
128plain keys (i.e. not certificates) by listing their SHA1 hashes:
129
130	string	public_key_hash[0]
131	....
132
133This section must contain at least one "public_key_hash". The hash blob
134is obtained by taking the SHA1 hash of the public key blob. Hashes in
135this section must appear in numeric order, treating each hash as a big-
136endian integer.
137
138This section may appear multiple times.
139
1405. KRL signature sections
141
142The KRL_SECTION_SIGNATURE section serves a different purpose to the
143preceeding ones: to provide cryptographic authentication of a KRL that
144is retrieved over a channel that does not provide integrity protection.
145Its format is slightly different to the previously-described sections:
146in order to simplify the signature generation, it includes as a "body"
147two string components instead of one.
148
149	byte	KRL_SECTION_SIGNATURE
150	string	signature_key
151	string	signature
152
153The signature is calculated over the entire KRL from the KRL_MAGIC
154to this subsection's "signature_key", including both and using the
155signature generation rules appropriate for the type of "signature_key".
156
157This section must appear last in the KRL. If multiple signature sections
158appear, they must appear consecutively at the end of the KRL file.
159
160Implementations that retrieve KRLs over untrusted channels must verify
161signatures. Signature sections are optional for KRLs distributed by
162trusted means.
163
164$OpenBSD: PROTOCOL.krl,v 1.2 2013/01/18 00:24:58 djm Exp $
165