X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/ba6e6b64033b1f9de49feccb5c9cd438354481f7..0f00dc4c8eb47e67bc0f148c2dd109f73a451e0a:/keyring.5?ds=sidebyside diff --git a/keyring.5 b/keyring.5 deleted file mode 100644 index b3e4af3..0000000 --- a/keyring.5 +++ /dev/null @@ -1,220 +0,0 @@ -.\" -*-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,