General utilities cleanup. Add signature support to catcrypt. Throw in
[u/mdw/catacomb] / 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" ", " "mp" ", " "struct" ", " "encrypt" ", " "string" ", " "ec"
85 The key encoding type. This describes the format of the actual key
86 data.
87 .TP
88 .B "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 "mp"
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 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 "mp"
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 mp
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>