X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/ba6e6b64033b1f9de49feccb5c9cd438354481f7..0f00dc4c8eb47e67bc0f148c2dd109f73a451e0a:/progs/keyring.5 diff --git a/progs/keyring.5 b/progs/keyring.5 new file mode 100644 index 0000000..b3e4af3 --- /dev/null +++ b/progs/keyring.5 @@ -0,0 +1,220 @@ +.\" -*-nroff-*- +.ie t \{\ +. if \n(.g \{\ +. fam P +. \} +. ds ss \s8\u +. ds se \d\s0 +. ds us \s8\d +. ds ue \u\s0 +. ds *t \(*t +.\} +.el \{\ +. ds ss ^ +. ds se +. ds us _ +. ds ue +. ds *t \fIt\fP +.\} +.TH keyring 5 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library" +.SH NAME +keyring \- description of Catacomb keyring files +.SH DESCRIPTION +Keyring files are line-oriented text files. It is recommended that +programs use only the provided interface for reading and modifying +keyring files for consistency of locking and representation: this +description is provided for the benefit of administrators attempting to +understand or repair keyring files. +.SS "File format" +Lines containing only whitespace and lines whose first non-whitespace +character is +.RB ` # ' +are ignored, but are not written back to the file. Thus, the comment +facility is not particularly useful. +.PP +Each remaining line describes a key. +.SS "Key records" +Key descriptions consist of +between 4 and six whitespace-separated fields. The final comment field +may contain whitespace characters. The fields are, in order: +.TP +.B type +The key's type string, set when the key was created. +.TP +.B "key data" +The actual key. See below. +.TP +.B "expiry time" +The time at which this key expires, represented as an integer, in the +format returned by the +.BR time (2) +system call. +.TP +.B "deletion time" +The time at which this key should be deleted, using the same +representation as the expiry time. The special value 0 signifies that +the key should be deleted on expiry. +.TP +.B attributes +The key's attributes, encoded using the `form-urlencoded' encoding +defined in RFC1866. This field is optional: if it is omitted, the key +has no attributes. Alternatively, if there are no attributes, this +field may be given as a single dash +.RB ` \- '. +.TP +.B comment +The comment field. This field is optional. It may contain whitespace. +It is deliberately not included as an attribute, since the urlencoded +nature of attributes makes them hard to read when perusing a keyring +file. +.SS "Key data" +There are two basic formats for keys: the +.I text +encoding and the +.I binary +encoding. The usual form for keys in a keyring is the text encoding; +however, keys are represented as binary prior to being encrypted. +.PP +The textual form of a key is a comma-separated sequence of +.IR attributes , +followed by a +.RB ` : ' +and the actual key data. The attributes are as follows. +.TP +.BR "binary" ", " "integer" ", " "struct" ", " "encrypt" ", " "string" ", " "ec" +The key encoding type. This describes the format of the actual key +data. +.TP +.BR "symmetric" ", " "private" ", " "public" ", " "shared" +The kind of key this is. This field can be used to filter public keys +from private ones. +.TP +.B "burn" +The key is sensitive; it should be stored in secure memory, and properly +deleted after use. +.PP +As mentioned, the format of the key data itself following the colon +depends on the encoding type. This works as follows. +.TP +.B "binary" +The binary data is base64 encoded (RFC2045). +.TP +.B "integer" +The integer is a string of decimal digits. +.TP +.B "struct" +The representation is a +.RB ` [ ' +followed by a sequence of +.IB name = value +pairs separated by +.RB ` , ', +and a final +.RB ` ] '. +The names are the subkey labels; the values are the encodings of the +individual subkeys. +.TP +.B "string" +The string is form-urlencoded (RFC1866). +.TP +.B "ec" +The point at infinity is denoted +.BR inf ; +otherwise the point is written as a pair of hexadecimal integers, each +preceded by +.B 0x +and separated by +.RB ` , '. +.TP +.B "encrypt" +The actual key data is encoded as binary and encrypted; the ciphertext +is base64 encoded (RFC2045). Encryption works as follows. Let the +passphrase be +.I P +and the plaintext be +.IR m . +A 160-bit nonce +.I N +is chosen at random. Let +.IR K \ =\ N \ ||\ K . +Generate 320 bits of output from RIPEMD-160 in +MGF1 mode with seed +.IR K ; +let +.I K\*(usE\*(ue +be the first half and +.I K\*(usT\*(ue +be the second. +Encrypt the message +.I m +using Blowfish in CBC mode, with ciphertext stealing if necessary, using +a zero IV and the key +.IR K\*(usE\*(ue , +giving the ciphertext +.IR y\*(us0\*(ue . +Let \*(*t be the 160-bit tag obtained from RIPEMD-160 in HMAC mode on +the message +.I y\*(us0\*(ue +and with key +.IR K\*(usT\*(ue . +The ciphertext is then +.IR y \ =\ N \ ||\ \*(*t\ ||\ y\*(us0\*(ue . +This encryption scheme can be shown to provide integrity of ciphertexts +and indistinguishability against chosen-ciphertext attack against an +adversary who doesn't know +.IR P . +.PP +The binary format is also quite simple. All integers are stored +base-256, one digit per octet, in big-endian order. A key begins with a +header consisting of a two-octet flags field and a two-octet length. +The flags encode the attributes described above; see the header file +.B key\-data.h +for the values of the flags. The length gives the number of octets in +the following key data, not including the header. Finally, the key data +is padded with zero octets to make it a multiple of 4 octets long. The +length does not include this padding. The various key encodings are as +follows. +.TP +.B "binary" +The key data is stored as-is. +.TP +.B "integer" +The integer is stored, base-256, one digit per octet, in big-endian +order, using as few octets as possible. The value 0 has length zero. +.TP +.B "struct" +A sequence of subkeys is stored; the sequence is sorted by +lexicographical order of the subkeys' labels. Each subkey consists of a +single octet giving the length of the subkey's label; the label itself +in ASCII, zero-octet padding to make the subkey start at a multiple of +four octets, and then the encoding of the subkey. There is no +terminator: the outer length field indicates when to stop reading +subkeys. +.TP +.B "string" +The string is stored as-is, with no terminator. +.TP +.B "ec" +The point at infinity has length zero. Otherwise, the key consists of +the +.IR x - +and +.IR y -coordinates +expressed as integers in the obvious way and encoded as for +.B integer +keys, each preceded by a two-octet length. There is no padding between +the two coordinates. +.TP +.B "encrypt" +The key data is encoded as binary and encrypted as described above. The +resulting ciphertext is stored as is. +.SS "Fingerprints" +The fingerprint is computed by hashing the binary representation of (the +selected parts of) a key's data followed by the key type preceded by a +single length octet, and the key's attributes, in lexicographic order of +the attribute name. Each attribute consists of the attribute's name +preceded by a single length octet, followed by the value preceded by a +two-octet length. The lengths do not include themselves; neither string +has a terminator character; there is no padding. +.SH AUTHOR +Mark Wooding,