git.distorted.org.uk Git - u/mdw/catacomb/blob - keyring.5

   1 .\" -*-nroff-*-
   2 .ie t \{\
   3 .  if \n(.g \{\
   4 .    fam P
   5 .  \}
   6 .  ds ss \s8\u
   7 .  ds se \d\s0
   8 .  ds us \s8\d
   9 .  ds ue \u\s0
  10 .  ds *t \(*t
  11 .\}
  12 .el \{\
  13 .  ds ss ^
  14 .  ds se
  15 .  ds us _
  16 .  ds ue
  17 .  ds *t \fIt\fP
  18 .\}
  19 .TH keyring 5 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
  20 .SH NAME
  21 keyring \- description of Catacomb keyring files
  22 .SH DESCRIPTION
  23 Keyring files are line-oriented text files.  It is recommended that
  24 programs use only the provided interface for reading and modifying
  25 keyring files for consistency of locking and representation: this
  26 description is provided for the benefit of administrators attempting to
  27 understand or repair keyring files.
  28 .SS "File format"
  29 Lines containing only whitespace and lines whose first non-whitespace
  30 character is
  31 .RB ` # '
  32 are ignored, but are not written back to the file.  Thus, the comment
  33 facility is not particularly useful.
  34 .PP
  35 Each remaining line describes a key.
  36 .SS "Key records"
  37 Key descriptions consist of
  38 between 4 and six whitespace-separated fields.  The final comment field
  39 may contain whitespace characters.  The fields are, in order:
  40 .TP
  41 .B type
  42 The key's type string, set when the key was created.
  43 .TP
  44 .B "key data"
  45 The actual key.  See below.
  46 .TP
  47 .B "expiry time"
  48 The time at which this key expires, represented as an integer, in the
  49 format returned by the
  50 .BR time (2)
  51 system call.
  52 .TP
  53 .B "deletion time"
  54 The time at which this key should be deleted, using the same
  55 representation as the expiry time.  The special value 0 signifies that
  56 the key should be deleted on expiry.
  57 .TP
  58 .B attributes
  59 The key's attributes, encoded using the `form-urlencoded' encoding
  60 defined in RFC1866.  This field is optional: if it is omitted, the key
  61 has no attributes.  Alternatively, if there are no attributes, this
  62 field may be given as a single dash
  63 .RB ` \- '.
  64 .TP
  65 .B comment
  66 The comment field.  This field is optional.  It may contain whitespace.
  67 It is deliberately not included as an attribute, since the urlencoded
  68 nature of attributes makes them hard to read when perusing a keyring
  69 file.
  70 .SS "Key data"
  71 There are two basic formats for keys: the
  72 .I text
  73 encoding and the
  74 .I binary
  75 encoding.  The usual form for keys in a keyring is the text encoding;
  76 however, keys are represented as binary prior to being encrypted.
  77 .PP
  78 The textual form of a key is a comma-separated sequence of
  79 .IR attributes ,
  80 followed by a
  81 .RB ` : '
  82 and the actual key data.  The attributes are as follows.
  83 .TP
  84 .BR "binary" ", " "integer" ", " "struct" ", " "encrypt" ", " "string" ", " "ec"
  85 The key encoding type.  This describes the format of the actual key
  86 data.
  87 .TP
  88 .BR "symmetric" ", " "private" ", " "public" ", " "shared"
  89 The kind of key this is.  This field can be used to filter public keys
  90 from private ones.
  91 .TP
  92 .B "burn"
  93 The key is sensitive; it should be stored in secure memory, and properly
  94 deleted after use.
  95 .PP
  96 As mentioned, the format of the key data itself following the colon
  97 depends on the encoding type.  This works as follows.
  98 .TP
  99 .B "binary"
 100 The binary data is base64 encoded (RFC2045).
 101 .TP
 102 .B "integer"
 103 The integer is a string of decimal digits.
 104 .TP
 105 .B "struct"
 106 The representation is a
 107 .RB ` [ '
 108 followed by a sequence of
 109 .IB name = value
 110 pairs separated by
 111 .RB ` , ',
 112 and a final
 113 .RB ` ] '.
 114 The names are the subkey labels; the values are the encodings of the
 115 individual subkeys.
 116 .TP
 117 .B "string"
 118 The string is form-urlencoded (RFC1866).
 119 .TP
 120 .B "ec"
 121 The point at infinity is denoted
 122 .BR inf ;
 123 otherwise the point is written as a pair of hexadecimal integers, each
 124 preceded by
 125 .B 0x
 126 and separated by
 127 .RB ` , '.
 128 .TP
 129 .B "encrypt"
 130 The actual key data is encoded as binary and encrypted; the ciphertext
 131 is base64 encoded (RFC2045).  Encryption works as follows.  Let the
 132 passphrase be
 133 .I P
 134 and the plaintext be
 135 .IR m .
 136 A 160-bit nonce
 137 .I N
 138 is chosen at random.  Let
 139 .IR K \ =\  N \ ||\  K .
 140 Generate 320 bits of output from RIPEMD-160 in
 141 MGF1 mode with seed
 142 .IR K ;
 143 let
 144 .I K\*(usE\*(ue
 145 be the first half and
 146 .I K\*(usT\*(ue
 147 be the second.
 148 Encrypt the message
 149 .I m
 150 using Blowfish in CBC mode, with ciphertext stealing if necessary, using
 151 a zero IV and the key
 152 .IR K\*(usE\*(ue ,
 153 giving the ciphertext
 154 .IR y\*(us0\*(ue .
 155 Let \*(*t be the 160-bit tag obtained from RIPEMD-160 in HMAC mode on
 156 the message
 157 .I y\*(us0\*(ue
 158 and with key
 159 .IR K\*(usT\*(ue .
 160 The ciphertext is then
 161 .IR y \ =\  N \ ||\ \*(*t\ ||\  y\*(us0\*(ue .
 162 This encryption scheme can be shown to provide integrity of ciphertexts
 163 and indistinguishability against chosen-ciphertext attack against an
 164 adversary who doesn't know
 165 .IR P .
 166 .PP
 167 The binary format is also quite simple.  All integers are stored
 168 base-256, one digit per octet, in big-endian order.  A key begins with a
 169 header consisting of a two-octet flags field and a two-octet length.
 170 The flags encode the attributes described above; see the header file
 171 .B key\-data.h
 172 for the values of the flags.  The length gives the number of octets in
 173 the following key data, not including the header.  Finally, the key data
 174 is padded with zero octets to make it a multiple of 4 octets long.  The
 175 length does not include this padding.  The various key encodings are as
 176 follows.
 177 .TP
 178 .B "binary"
 179 The key data is stored as-is.
 180 .TP
 181 .B "integer"
 182 The integer is stored, base-256, one digit per octet, in big-endian
 183 order, using as few octets as possible.  The value 0 has length zero.
 184 .TP
 185 .B "struct"
 186 A sequence of subkeys is stored; the sequence is sorted by
 187 lexicographical order of the subkeys' labels.  Each subkey consists of a
 188 single octet giving the length of the subkey's label; the label itself
 189 in ASCII, zero-octet padding to make the subkey start at a multiple of
 190 four octets, and then the encoding of the subkey.  There is no
 191 terminator: the outer length field indicates when to stop reading
 192 subkeys.
 193 .TP
 194 .B "string"
 195 The string is stored as-is, with no terminator.
 196 .TP
 197 .B "ec"
 198 The point at infinity has length zero.  Otherwise, the key consists of
 199 the
 200 .IR x -
 201 and
 202 .IR y -coordinates
 203 expressed as integers in the obvious way and encoded as for
 204 .B integer
 205 keys, each preceded by a two-octet length.  There is no padding between
 206 the two coordinates.
 207 .TP
 208 .B "encrypt"
 209 The key data is encoded as binary and encrypted as described above.  The
 210 resulting ciphertext is stored as is.
 211 .SS "Fingerprints"
 212 The fingerprint is computed by hashing the binary representation of (the
 213 selected parts of) a key's data followed by the key type preceded by a
 214 single length octet, and the key's attributes, in lexicographic order of
 215 the attribute name.  Each attribute consists of the attribute's name
 216 preceded by a single length octet, followed by the value preceded by a
 217 two-octet length.  The lengths do not include themselves; neither string
 218 has a terminator character; there is no padding.
 219 .SH AUTHOR
 220 Mark Wooding, <mdw@nsict.org>