blob: e8caa4527ab362ecde686e560737248eddf31cda [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
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 $