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