| 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> |