Annotation of src/usr.bin/ssh/PROTOCOL.krl, Revision 1.4
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
39:
1.3 djm 40: 2. Certificate section
1.1 djm 41:
42: These sections use type KRL_SECTION_CERTIFICATES to revoke certificates by
43: serial number or key ID. The consist of the CA key that issued the
44: certificates to be revoked and a reserved field whose contents is currently
45: ignored.
46:
47: string ca_key
48: string reserved
49:
1.3 djm 50: Where "ca_key" is the standard SSH wire serialisation of the CA's
51: public key. Alternately, "ca_key" may be an empty string to indicate
52: the certificate section applies to all CAs (this is most useful when
53: revoking key IDs).
54:
1.1 djm 55: Followed by one or more sections:
56:
57: byte cert_section_type
58: string cert_section_data
59:
60: The certificate section types are:
61:
62: #define KRL_SECTION_CERT_SERIAL_LIST 0x20
63: #define KRL_SECTION_CERT_SERIAL_RANGE 0x21
64: #define KRL_SECTION_CERT_SERIAL_BITMAP 0x22
65: #define KRL_SECTION_CERT_KEY_ID 0x23
66:
67: 2.1 Certificate serial list section
68:
69: This section is identified as KRL_SECTION_CERT_SERIAL_LIST. It revokes
70: certificates by listing their serial numbers. The cert_section_data in this
71: case contains:
72:
73: uint64 revoked_cert_serial
74: uint64 ...
75:
76: This section may appear multiple times.
77:
78: 2.2. Certificate serial range section
79:
80: These sections use type KRL_SECTION_CERT_SERIAL_RANGE and hold
81: a range of serial numbers of certificates:
82:
83: uint64 serial_min
84: uint64 serial_max
85:
86: All certificates in the range serial_min <= serial <= serial_max are
87: revoked.
88:
89: This section may appear multiple times.
90:
91: 2.3. Certificate serial bitmap section
92:
93: Bitmap sections use type KRL_SECTION_CERT_SERIAL_BITMAP and revoke keys
94: by listing their serial number in a bitmap.
95:
96: uint64 serial_offset
97: mpint revoked_keys_bitmap
98:
99: A bit set at index N in the bitmap corresponds to revocation of a keys with
100: serial number (serial_offset + N).
101:
102: This section may appear multiple times.
103:
104: 2.4. Revoked key ID sections
105:
106: KRL_SECTION_CERT_KEY_ID sections revoke particular certificate "key
107: ID" strings. This may be useful in revoking all certificates
108: associated with a particular identity, e.g. a host or a user.
109:
110: string key_id[0]
111: ...
112:
113: This section must contain at least one "key_id". This section may appear
114: multiple times.
115:
116: 3. Explicit key sections
117:
118: These sections, identified as KRL_SECTION_EXPLICIT_KEY, revoke keys
119: (not certificates). They are less space efficient than serial numbers,
120: but are able to revoke plain keys.
121:
122: string public_key_blob[0]
123: ....
124:
125: This section must contain at least one "public_key_blob". The blob
126: must be a raw key (i.e. not a certificate).
127:
128: This section may appear multiple times.
129:
130: 4. SHA1 fingerprint sections
131:
132: These sections, identified as KRL_SECTION_FINGERPRINT_SHA1, revoke
133: plain keys (i.e. not certificates) by listing their SHA1 hashes:
134:
135: string public_key_hash[0]
136: ....
137:
138: This section must contain at least one "public_key_hash". The hash blob
139: is obtained by taking the SHA1 hash of the public key blob. Hashes in
140: this section must appear in numeric order, treating each hash as a big-
141: endian integer.
142:
143: This section may appear multiple times.
144:
145: 5. KRL signature sections
146:
147: The KRL_SECTION_SIGNATURE section serves a different purpose to the
1.4 ! djm 148: preceding ones: to provide cryptographic authentication of a KRL that
1.1 djm 149: is retrieved over a channel that does not provide integrity protection.
150: Its format is slightly different to the previously-described sections:
151: in order to simplify the signature generation, it includes as a "body"
152: two string components instead of one.
153:
154: byte KRL_SECTION_SIGNATURE
155: string signature_key
156: string signature
157:
158: The signature is calculated over the entire KRL from the KRL_MAGIC
159: to this subsection's "signature_key", including both and using the
160: signature generation rules appropriate for the type of "signature_key".
161:
162: This section must appear last in the KRL. If multiple signature sections
163: appear, they must appear consecutively at the end of the KRL file.
164:
165: Implementations that retrieve KRLs over untrusted channels must verify
166: signatures. Signature sections are optional for KRLs distributed by
167: trusted means.
1.2 djm 168:
1.4 ! djm 169: $OpenBSD: PROTOCOL.krl,v 1.3 2015/01/30 01:10:33 djm Exp $
![[BACK]](/icons/back.gif){kind=icon}
Return to PROTOCOL.krl CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / ssh