--- /dev/null
+.\" -*-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, <mdw@distorted.org.uk>
projects / u / mdw / catacomb / blobdiff