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 . |
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 |
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 |
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 . |
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 |
220 | Mark Wooding, <mdw@nsict.org> |