forked from openssh/openssh-portable
-
Notifications
You must be signed in to change notification settings - Fork 0
/
PROTOCOL.krl
222 lines (154 loc) · 6.87 KB
/
PROTOCOL.krl
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
This describes the key/certificate revocation list format for OpenSSH.
1. Overall format
The KRL consists of a header and zero or more sections. The header is:
#define KRL_MAGIC 0x5353484b524c0a00ULL /* "SSHKRL\n\0" */
#define KRL_FORMAT_VERSION 1
uint64 KRL_MAGIC
uint32 KRL_FORMAT_VERSION
uint64 krl_version
uint64 generated_date
uint64 flags
string reserved
string comment
Where "krl_version" is a version number that increases each time the KRL
is modified, "generated_date" is the time in seconds since 1970-01-01
00:00:00 UTC that the KRL was generated, "comment" is an optional comment
and "reserved" an extension field whose contents are currently ignored.
No "flags" are currently defined.
Following the header are zero or more sections, each consisting of:
byte section_type
string section_data
Where "section_type" indicates the type of the "section_data". An exception
to this is the KRL_SECTION_SIGNATURE section, that has a slightly different
format (see below).
The available section types are:
#define KRL_SECTION_CERTIFICATES 1
#define KRL_SECTION_EXPLICIT_KEY 2
#define KRL_SECTION_FINGERPRINT_SHA1 3
#define KRL_SECTION_SIGNATURE 4
#define KRL_SECTION_FINGERPRINT_SHA256 5
#define KRL_SECTION_EXTENSION 255
2. Certificate section
These sections use type KRL_SECTION_CERTIFICATES to revoke certificates by
serial number or key ID. The consist of the CA key that issued the
certificates to be revoked and a reserved field whose contents is currently
ignored.
string ca_key
string reserved
Where "ca_key" is the standard SSH wire serialisation of the CA's
public key. Alternately, "ca_key" may be an empty string to indicate
the certificate section applies to all CAs (this is most useful when
revoking key IDs).
Followed by one or more sections:
byte cert_section_type
string cert_section_data
The certificate section types are:
#define KRL_SECTION_CERT_SERIAL_LIST 0x20
#define KRL_SECTION_CERT_SERIAL_RANGE 0x21
#define KRL_SECTION_CERT_SERIAL_BITMAP 0x22
#define KRL_SECTION_CERT_KEY_ID 0x23
#define KRL_SECTION_CERT_EXTENSION 0x39
2.1 Certificate serial list section
This section is identified as KRL_SECTION_CERT_SERIAL_LIST. It revokes
certificates by listing their serial numbers. The cert_section_data in this
case contains:
uint64 revoked_cert_serial
uint64 ...
This section may appear multiple times.
2.2. Certificate serial range section
These sections use type KRL_SECTION_CERT_SERIAL_RANGE and hold
a range of serial numbers of certificates:
uint64 serial_min
uint64 serial_max
All certificates in the range serial_min <= serial <= serial_max are
revoked.
This section may appear multiple times.
2.3. Certificate serial bitmap section
Bitmap sections use type KRL_SECTION_CERT_SERIAL_BITMAP and revoke keys
by listing their serial number in a bitmap.
uint64 serial_offset
mpint revoked_keys_bitmap
A bit set at index N in the bitmap corresponds to revocation of a keys with
serial number (serial_offset + N).
This section may appear multiple times.
2.4. Revoked key ID sections
KRL_SECTION_CERT_KEY_ID sections revoke particular certificate "key
ID" strings. This may be useful in revoking all certificates
associated with a particular identity, e.g. a host or a user.
string key_id[0]
...
This section must contain at least one "key_id". This section may appear
multiple times.
2.5. Certificate Extension subsections
This subsection type provides a generic extension mechanism to the
certificates KRL section that may be used to provide optional or critical
data.
Extensions are stored in subsections of type
KRL_SECTION_CERT_EXTENSION with the following contents:
string extension_name
boolean is_critical
string extension_contents.
Where "extension_name" describes the type of extension. It is
recommended that user extensions follow "cert-name@domain.org" naming.
The "is_critical" indicates whether this extension is mandatory or
optional. If true, then any unsupported extension encountered should
result in KRL parsing failure. If false, then it may be safely be
ignored.
The "extension_contents" contains the body of the extension.
3. Explicit key sections
These sections, identified as KRL_SECTION_EXPLICIT_KEY, revoke keys
(not certificates). They are less space efficient than serial numbers,
but are able to revoke plain keys.
string public_key_blob[0]
....
This section must contain at least one "public_key_blob". The blob
must be a raw key (i.e. not a certificate).
This section may appear multiple times.
4. SHA1/SHA256 fingerprint sections
These sections, identified as KRL_SECTION_FINGERPRINT_SHA1 and
KRL_SECTION_FINGERPRINT_SHA256, revoke plain keys (i.e. not
certificates) by listing their hashes:
string public_key_hash[0]
....
This section must contain at least one "public_key_hash". The hash blob
is obtained by taking the SHA1 or SHA256 hash of the public key blob.
Hashes in this section must appear in numeric order, treating each hash
as a big-endian integer.
This section may appear multiple times.
5. Extension sections
This section type provides a generic extension mechanism to the KRL
format that may be used to provide optional or critical data.
Extensions are recorded in sections of type KRL_SECTION_EXTENSION
with the following contents:
string extension_name
boolean is_critical
string extension_contents.
Where "extension_name" describes the type of extension. It is
recommended that user extensions follow "name@domain.org" naming.
The "is_critical" indicates whether this extension is mandatory or
optional. If true, then any unsupported extension encountered should
result in KRL parsing failure. If false, then it may be safely be
ignored.
The "extension_contents" contains the body of the extension.
6. KRL signature sections
Note: KRL signatures are not supported by OpenSSH. OpenSSH >= 9.4 will
refuse to load KRLs that contain signatures. We recommend the use
of SSHSIG (`ssh-keygen -Y sign ...`) style signatures for KRLs instead.
The KRL_SECTION_SIGNATURE section serves a different purpose to the
preceding ones: to provide cryptographic authentication of a KRL that
is retrieved over a channel that does not provide integrity protection.
Its format is slightly different to the previously-described sections:
in order to simplify the signature generation, it includes as a "body"
two string components instead of one.
byte KRL_SECTION_SIGNATURE
string signature_key
string signature
The signature is calculated over the entire KRL from the KRL_MAGIC
to this subsection's "signature_key", including both and using the
signature generation rules appropriate for the type of "signature_key".
This section must appear last in the KRL. If multiple signature sections
appear, they must appear consecutively at the end of the KRL file.
Implementations that retrieve KRLs over untrusted channels must verify
signatures. Signature sections are optional for KRLs distributed by
trusted means.
$OpenBSD: PROTOCOL.krl,v 1.7 2023/07/17 04:01:10 djm Exp $