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