Commit | Line | Data |
---|---|---|
d03ab969 | 1 | .\" -*-nroff-*- |
8404fd75 | 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 | .\} | |
d07dfe80 | 19 | .TH keyring 5 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library" |
d03ab969 | 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 | |
2d3bea94 | 25 | keyring files for consistency of locking and representation: this |
d03ab969 | 26 | description is provided for the benefit of administrators attempting to |
27 | understand or repair keyring files. | |
8404fd75 | 28 | .SS "File format" |
d03ab969 | 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 | |
8404fd75 | 35 | Each remaining line describes a key. |
36 | .SS "Key records" | |
37 | Key descriptions consist of | |
2d3bea94 | 38 | between 4 and six whitespace-separated fields. The final comment field |
39 | may contain whitespace characters. The fields are, in order: | |
d03ab969 | 40 | .TP |
41 | .B type | |
42 | The key's type string, set when the key was created. | |
43 | .TP | |
44 | .B "key data" | |
8404fd75 | 45 | The actual key. See below. |
d03ab969 | 46 | .TP |
47 | .B "expiry time" | |
c9e31e42 | 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. | |
d03ab969 | 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. | |
8404fd75 | 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 | |
513d9770 | 84 | .BR "binary" ", " "integer" ", " "struct" ", " "encrypt" ", " "string" ", " "ec" |
8404fd75 | 85 | The key encoding type. This describes the format of the actual key |
86 | data. | |
87 | .TP | |
513d9770 | 88 | .BR "symmetric" ", " "private" ", " "public" ", " "shared" |
8404fd75 | 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 | |
513d9770 | 102 | .B "integer" |
8404fd75 | 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 . | |
45c0fd36 | 136 | A 160-bit nonce |
8404fd75 | 137 | .I N |
138 | is chosen at random. Let | |
45c0fd36 | 139 | .IR K \ =\ N \ ||\ K . |
8404fd75 | 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 | |
513d9770 | 145 | be the first half and |
8404fd75 | 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 | |
45c0fd36 MW |
156 | the message |
157 | .I y\*(us0\*(ue | |
8404fd75 | 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 . | |
d03ab969 | 166 | .PP |
8404fd75 | 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 | |
513d9770 | 181 | .B "integer" |
8404fd75 | 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" | |
b817bfc6 | 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. | |
8404fd75 | 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 | |
513d9770 | 204 | .B integer |
8404fd75 | 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. | |
b817bfc6 | 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. | |
d03ab969 | 219 | .SH AUTHOR |
f387fcb1 | 220 | Mark Wooding, <mdw@distorted.org.uk> |