X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/c65df27983057ec76ed0e72bb370f9a5ae7dad28..80be023065ced106a4078a36371c135a60d2bd6c:/catcrypt.1 diff --git a/catcrypt.1 b/catcrypt.1 index 603d1d1..d4ef3e1 100644 --- a/catcrypt.1 +++ b/catcrypt.1 @@ -44,7 +44,7 @@ is one of: .RI [ item ...] .br .B encrypt -.RB [ \-a ] +.RB [ \-aC ] .RB [ \-k .IR tag ] .RB [ \-f @@ -54,7 +54,7 @@ is one of: .RI [ file ] .br .B decrypt -.RB [ \-aqv ] +.RB [ \-aqvC ] .RB [ \-f .IR format ] .RB [ \-o @@ -70,7 +70,7 @@ is one of: .IR output ] .RI [ file ] .br -.B encode +.B decode .RB [ \-f .IR format ] .RB [ \-b @@ -118,7 +118,10 @@ for more details about keyring files. Algorithms to be used with a particular key are described by attributes on the key, or its type. The .B catcrypt -command deals with both signing and key-encapsulation keys. +command deals with both signing and key-encapsulation keys. (Note that +.B catcrypt +uses signing keys in the same way as +.BR catsign (1).) .SS "Key-encapsulation keys" (Key encapsulation is a means of transmitting a short, known, random secret to a recipient. It differs from encryption in technical ways @@ -175,7 +178,8 @@ options, to generate the key. .TP .B ec This is the elliptic-curve analogue of -.BR dh . Use the +.BR dh . +Use the .B ec algorithm of the .BR key (1)) @@ -206,7 +210,8 @@ constructed by the raw KEM. If there is no attribute then the .I hash in the -.I kemalgspec is used; if that is absent then the default of +.I kemalgspec +is used; if that is absent then the default of .B rmd160 is used. Run .B catcrypt show hash @@ -465,6 +470,10 @@ in the current keyring; the default is not to sign the ciphertext. Write output to .I file rather than to standard output. +.TP +.B "\-C, \-\-nocheck" +Don't check the public key for validity. This makes encryption go much +faster, but at the risk of using a duff key. .SS decrypt The .B decrypt @@ -475,12 +484,16 @@ filename argument is given, this file is read instead. The following options are recognized. .TP .B "\-a, \-\-armour" -Read ASCII-armoured output. This is equivalent to specifying +Read ASCII-armoured input. This is equivalent to specifying .BR "\-f pem" . The variant spelling .B "\-\-armor" is also accepted. .TP +.B "\-b, \-\-buffer" +Buffer plaintext data until we're sure we've got it all. This is forced +on if output is to stdout, but is always available as an option. +.TP .BI "\-f, \-\-format " format Read input encoded according to .IR format . @@ -499,12 +512,17 @@ Write output to instead of to standard output. The file is written in binary mode. Fixing line-end conventions is your problem; there are lots of good tools for dealing with it. +.TP +.B "\-C, \-\-nocheck" +Don't check the private key for validity. This makes decryption go much +faster, but at the risk of using a duff key, and possibly leaking +information about the private key. .PP Output is written to standard output in a machine-readable format. Major problems cause the program to write a diagnostic to standard error and exit nonzero as usual. The quantity of output varies depending on the verbosity level and whether the plaintext is also being written to -standard output. Output lines begin with a keyword.: +standard output. Output lines begin with a keyword: .TP .BI "FAIL " reason An error prevented decryption. The program will exit nonzero. @@ -519,11 +537,8 @@ being sent somewhere other than standard output. .TP .B "DATA" The plaintext follows, starting just after the next newline character or -sequence. This is only produced if main output is being sent to -standard output. If anything goes wrong, a -.B FAIL -message is printed, preceded and followed by a newline, and the program -exits nonzero. +sequence. This is only produced if main output is also being sent to +standard output. .TP .BI "INFO " note Any other information. @@ -535,14 +550,13 @@ No output. Watch the exit status. All messages. .PP .B Warning! -All output written has been checked for authenticity. However, since -the input is chunked, a chunk will be checked and written before the -authenticity of following chunks is established. Don't rely on the -output being complete until -.B catcrypt decrypt -prints +All output written has been checked for authenticity. However, output +can fail madway through for many reasons, and the resulting message may +therefore be truncated. Don't rely on the output being complete until .B OK -and/or exits successfully. +is printed or +.B catcrypt decrypt +exits successfully. .SS "encode" The .B encode @@ -642,6 +656,18 @@ that, then \(en leaking intermediate values often voids security warranties. But it does avoid the usual problem with separate signing and encryption that a careful leak by the recipient can produce evidence that you signed some incriminating message. +.PP +Note that +.BR catcrypt 's +signatures do +.I not +provide `non-repudiation' in any useful way. This is deliberate: the +purpose of signing is to convince the recipient of the sender's +identity, rather than to allow the recipient to persuade anyone else. +Indeed, given an encrypted and signed message, the recipient can +straightforwardly construct a new message, apparently from the same +sender, and whose signature still verifies, but with arbitrarily chosen +content. .SH "CRYPTOGRAPHIC THEORY" Encryption of a message proceeds as follows. .hP 0. @@ -659,18 +685,25 @@ Use the first bits of the keystream to key a symmetric encryption scheme; use the next bits to key a message authentication code. .hP 4. If we're signing the message then extract 1024 bytes from the keystream, -sign them, and emit a packet containing the signature. The signature -packet doesn't contain the signed message, just the signature. +sign the header and public value, and the keystream bytes; emit a packet +containing the signature. The signature packet doesn't contain the +signed message, just the signature. .hP 5. Split the message into blocks. For each block, pick a random IV from the keystream, encrypt the block and emit a packet containing the -IV, ciphertext and a MAC tag. +IV, ciphertext, and a MAC tag over the ciphertext and a sequence number. +.hP 6. +The last chunk is the encryption of an empty plaintext block. No +previous plaintext block is empty. This lets us determine the +difference between a complete file and one that's been maliciously +truncated. .PP That's it. Nothing terribly controversial, really. .SH "SEE ALSO" .BR key (1), +.BR catsign (1), .BR dsig (1), .BR hashsum (1), .BR keyring (5). .SH AUTHOR -Mark Wooding, +Mark Wooding,