New function and example program computes Fibonacci numbers fairly fast.

[u/mdw/catacomb] / keyring.5

.\" -*-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>