19 .TH keyring 5 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
21 keyring \- description of Catacomb keyring files
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.
29 Lines containing only whitespace and lines whose first non-whitespace
32 are ignored, but are not written back to the file. Thus, the comment
33 facility is not particularly useful.
35 Each remaining line describes a key.
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:
42 The key's type string, set when the key was created.
45 The actual key. See below.
48 The time at which this key expires, represented as an integer, in the
49 format returned by the
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.
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
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
71 There are two basic formats for keys: the
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.
78 The textual form of a key is a comma-separated sequence of
82 and the actual key data. The attributes are as follows.
84 .BR "binary" ", " "integer" ", " "struct" ", " "encrypt" ", " "string" ", " "ec"
85 The key encoding type. This describes the format of the actual key
88 .BR "symmetric" ", " "private" ", " "public" ", " "shared"
89 The kind of key this is. This field can be used to filter public keys
93 The key is sensitive; it should be stored in secure memory, and properly
96 As mentioned, the format of the key data itself following the colon
97 depends on the encoding type. This works as follows.
100 The binary data is base64 encoded (RFC2045).
103 The integer is a string of decimal digits.
106 The representation is a
108 followed by a sequence of
114 The names are the subkey labels; the values are the encodings of the
118 The string is form-urlencoded (RFC1866).
121 The point at infinity is denoted
123 otherwise the point is written as a pair of hexadecimal integers, each
130 The actual key data is encoded as binary and encrypted; the ciphertext
131 is base64 encoded (RFC2045). Encryption works as follows. Let the
138 is chosen at random. Let
139 .IR K \ =\ N \ ||\ K .
140 Generate 320 bits of output from RIPEMD-160 in
145 be the first half and
150 using Blowfish in CBC mode, with ciphertext stealing if necessary, using
151 a zero IV and the key
153 giving the ciphertext
155 Let \*(*t be the 160-bit tag obtained from RIPEMD-160 in HMAC mode on
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
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
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
179 The key data is stored as-is.
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.
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
195 The string is stored as-is, with no terminator.
198 The point at infinity has length zero. Otherwise, the key consists of
203 expressed as integers in the obvious way and encoded as for
205 keys, each preceded by a two-octet length. There is no padding between
209 The key data is encoded as binary and encrypted as described above. The
210 resulting ciphertext is stored as is.
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.
220 Mark Wooding, <mdw@distorted.org.uk>