Update manuals.

diff --git a/key.1 b/key.1
index e09ef51..cab0d41 100644 (file)
--- a/key.1
+++ b/key.1
@@ -1,15 +1,20 @@
 .\" -*-nroff-*-
 .ie t \{\
 .\" -*-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 ss \s8\u
 .  ds se \d\s0
 .  ds us \s8\d
 .  ds ue \u\s0

+.  ds *b \(*b

 .\}
 .el \{\
 .  ds ss ^
 .  ds se
 .  ds us _
 .\}
 .el \{\
 .  ds ss ^
 .  ds se
 .  ds us _

-.  ds se
+.  ds ue
+.  ds *b \fIbeta\fP

 .\}
 .TH key 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
 .SH NAME
 .\}
 .TH key 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
 .SH NAME


@@ -170,24 +175,32 @@ algorithms use
 keys.  Keys used with number-theoretic systems (like most common
 public-key systems) use
 .I "multiprecision integer"
 keys.  Keys used with number-theoretic systems (like most common
 public-key systems) use
 .I "multiprecision integer"

-keys.  Algorithms which require several key constituents (again, like
-most public-key systems) use
+keys.  Elliptic curve systems use
+.I "curve point"
+keys, which are either a pair of integers representing field elements,
+or a `point at infinity'.  Algorithms which require several key
+constituents (again, like most public-key systems) use

 .I structured
 .I structured

-keys, which consist of a collection of named parts.  Finally, keys
-(including structured keys) can be encrypted.
+keys, which consist of a collection of named parts.  It's possible to
+store an
+.I "ASCII string"
+as a key, though this is usually done as a component of a structured
+key.  Finally, keys (including structured keys) can be encrypted.

 .TP
 .B "filter"
 Keys and key components may be selected by a filter expression, a
 sequence of flag names separated by commas.  Flags are:
 .BR binary ,
 .BR integer ,
 .TP
 .B "filter"
 Keys and key components may be selected by a filter expression, a
 sequence of flag names separated by commas.  Flags are:
 .BR binary ,
 .BR integer ,

-.B struct
+.BR struct ,
+.BR ec ,
+.BR string ,

 or
 .B encrypt
 (describing the key encoding);
 .BR symmetric ,
 .BR private ,
 or
 .B encrypt
 (describing the key encoding);
 .BR symmetric ,
 .BR private ,

-.B public
+.BR public ,

 or
 .B shared
 (describing the category of key);
 or
 .B shared
 (describing the category of key);


@@ -427,7 +440,8 @@ is chosen to be a `safe' prime (i.e.,
 .IR p \ =\ 2 q \ +\ 1,
 with
 .I q
 .IR p \ =\ 2 q \ +\ 1,
 with
 .I q

-prime).  In this case, the value of
+prime).  Finding safe primes takes a very long time.  In this case, the
+value of

 .I g
 is fixed as 4.
 .IP
 .I g
 is fixed as 4.
 .IP


@@ -463,6 +477,17 @@ otherwise,
 .I g
 will generate the group of order
 .RI ( p \ \-\ 1)/2\ =\  q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...
 .I g
 will generate the group of order
 .RI ( p \ \-\ 1)/2\ =\  q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...

+.IP
+Finally, the
+.B \-C
+option can be given, in which case the parameters are taken directly
+from the provided group specification, which may either be the the name
+of one of the built-in groups (say
+.B "key add \-a dh\-param \-C list 42"
+for a list) or a triple
+.RI ( p ,\  q ,\  g ).
+separated by commas.  No random generation is done in this case: the
+given parameters are simply stored.

 .TP
 .B "dh"
 Generates a public/private key pair for use with offline Diffie-Hellman,
 .TP
 .B "dh"
 Generates a public/private key pair for use with offline Diffie-Hellman,


@@ -560,7 +585,7 @@ A
 can be given explicitly (in which case
 .RB ` \-b '
 is ignored).  It can either be the name of a built-in curve (say
 can be given explicitly (in which case
 .RB ` \-b '
 is ignored).  It can either be the name of a built-in curve (say

-.B "key add \-C list"
+.B "key add \-a ec\-param \-C list 42"

 for a list of curve names) or a full specification.  The curve is
 checked for correctness and security according to the SEC1
 specification: failed checks cause a warning to be issued to standard
 for a list of curve names) or a full specification.  The curve is
 checked for correctness and security according to the SEC1
 specification: failed checks cause a warning to be issued to standard


@@ -575,13 +600,18 @@ separated by whitespace: a
 which is one of
 .BR "prime" ,
 .BR "niceprime" ,
 which is one of
 .BR "prime" ,
 .BR "niceprime" ,

-or
-.BR "binpoly" ;
+.BR "binpoly" ,
+.or
+.BR "binnorm" ;

 an optional
 .RB ` : ';
 the field modulus
 .IR p ;
 an optional
 .RB ` : ';
 the field modulus
 .IR p ;

-an optional
+if the field type is
+.B binnorm
+then an optional
+.RB ` , '
+and the representation of the normal element \*(*b; an optional

 .RB ` / ';
 a
 .IR "curve type" ,
 .RB ` / ';
 a
 .IR "curve type" ,

diff --git a/keyring.5 b/keyring.5
index 1e99c2e..10b2f5b 100644 (file)
--- a/keyring.5
+++ b/keyring.5
@@ -1,4 +1,21 @@
 .\" -*-nroff-*-
 .\" -*-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
 .TH keyring 5 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
 .SH NAME
 keyring \- description of Catacomb keyring files


@@ -8,14 +25,16 @@ 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.
 keyring files for consistency of locking and representation: this
 description is provided for the benefit of administrators attempting to
 understand or repair keyring files.

-.PP
+.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
 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.  Key descriptions consist of
+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
 between 4 and six whitespace-separated fields.  The final comment field
 may contain whitespace characters.  The fields are, in order:
 .TP


@@ -23,7 +42,7 @@ may contain whitespace characters.  The fields are, in order:
 The key's type string, set when the key was created.
 .TP
 .B "key data"
 The key's type string, set when the key was created.
 .TP
 .B "key data"

-The actual key, Base64 encoded, as described in RFC2045.
+The actual key.  See below.

 .TP
 .B "expiry time"
 The time at which this key expires, represented as an integer, in the
 .TP
 .B "expiry time"
 The time at which this key expires, represented as an integer, in the


@@ -48,8 +67,144 @@ 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.
 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" ", " "mp" ", " "struct" ", " "encrypt" ", " "string" ", " "ec"
+The key encoding type.  This describes the format of the actual key
+data.
+.TP
+.B "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 "mp"
+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 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
 .PP

-It is not envisaged that the file format will change in the future.  Any
-extensions will be made by defining new attributes.
+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 "mp"
+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.  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 mp
+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.

 .SH AUTHOR
 Mark Wooding, <mdw@nsict.org>
 .SH AUTHOR
 Mark Wooding, <mdw@nsict.org>