X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/c65df27983057ec76ed0e72bb370f9a5ae7dad28..f387fcb17a980fe165218d217b0187a8c279508a:/catcrypt.1 diff --git a/catcrypt.1 b/catcrypt.1 index 603d1d1..56fe297 100644 --- a/catcrypt.1 +++ b/catcrypt.1 @@ -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 @@ -475,12 +480,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 . @@ -504,7 +513,7 @@ 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 +528,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 +541,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 +647,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. @@ -664,13 +681,19 @@ 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,