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