crypto/openssh/PROTOCOL.krl

   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.
 163
 164 $OpenBSD: PROTOCOL.krl,v 1.2 2013/01/18 00:24:58 djm Exp $