From d1d169b1fca5876dc13706ccc8a00ac90459679c Mon Sep 17 00:00:00 2001 From: "git@daemon.de" Date: Thu, 6 Feb 2014 11:26:45 +0100 Subject: [PATCH] updated format descriptions to be more formal and reproducible --- man/details.pod | 79 +++++++++++++++-- man/z85.1 | 231 ------------------------------------------------ man/z85.pod | 99 --------------------- 3 files changed, 74 insertions(+), 335 deletions(-) delete mode 100644 man/z85.1 delete mode 100644 man/z85.pod diff --git a/man/details.pod b/man/details.pod index 3e5728c..bfc9cfb 100644 --- a/man/details.pod +++ b/man/details.pod @@ -123,9 +123,9 @@ Verification by recipient: =head1 SIGNED ENCRYPTION Beside pure encryption and signatures pcp1 also supports signed -encryption. In this mode an input file will be encrypted and -a signature using your primary secret key from a BLAKE2 hash of -the file contents will be appended to it. +encryption. In this mode an input file will be signed your primary +secret key from a BLAKE2 hash of the file contents and the recipients +and then encrypted. The signature is encrypted as well. Example: @@ -363,6 +363,20 @@ Recipient field format: R is calculated using public key encryption using the senders secret key, the recipients public key and a random nonce. +Pseudocode: + + R = foreach P: N | crypto_box(S, N, P, SK) + L = len(R) + T = 5 + write (T | L | R) + foreach I: write (N | crypto_secret_box(I, N, S)) + +where P is the public key of a recipient, SK is the senders +secret key, R is the recipient list, L is the number of recipients, +T is the filetype header, I is a block of input with a size +of 32k, N is a nonce (new per block) and S the symmetric key. + + =head2 SIGNATURE FORMAT There are different signature formats. Standard binary NACL @@ -383,6 +397,15 @@ signatures have the following format: The actual signature is not a signature over the whole content of an input file but of a BLAKE2 hash of the content. +Pseudo code: + + H = crypto_generichash(C) + C | O | H | crypto_sign(H, S) + +where C is the message (content), H is the blake2 hash, +O is the offset separator and S is the secret signing key +of the sender. + Armored signatures have the following format: ----- BEGIN ED25519 SIGNED MESSAGE ----- @@ -405,8 +428,54 @@ contents as the binary signature outlined above (hash+sig). Signed encrypted files are in binary form only. The first part is the standard encrypted file as described in B -followed by the binary signature described in B without -the offset separator. +followed by the binary encrypted signature described in B +without the offset separator. + +However, not only the hash of the file content will be signed but the +recipient list described in B as well. A +valid recipient is therefore not able to re-encrypt the decrypted +message, append the original signature and send it to other recipients. +The signature would not match since the recipient list differs and +so recipients know that the signature is forged. + +Formal file description of sign+encrypt format: + + +---------------------------------------------------------+ + | Field Size Description | + +-------------+--------+----------------------------------+ + | Type | 1 | Filetype, 5=ASYM, 23=SYM | + +-------------|--------|----------------------------------+ + | Len R | 4 | Number of recipients (*) | + +-------------|--------|----------------------------------+ + | Recipients | R*72 | C(recipient)|C(recipient)... (*) | + +-------------|--------|----------------------------------+ + | Encrypted | ~ | The actual encrypted data | + +-------------|--------|----------------------------------+ + | Signature | ~ | Encrypted signature(*) | + +-------------|--------|----------------------------------+ + +As usual the encrypted signature consists of a nonce and the +actual cipher, which is computed symmetrically (see above) +from the following clear signature. + +Before encryption the signature format is: + + +---------------------------------------------------------+ + | Field Size Description | + +-------------+--------+----------------------------------+ + | Hash | 64 | BLAKE2 hash of content+R (*) | + +-------------|--------|----------------------------------+ + | Signature | 64 | ED25519 signature of BLAKE2 Hash | + +-------------|--------|----------------------------------+ + +where R is: C(recipient)|C(recipient)... (see B). + +Pseudocode: + + N | crypto_secret_box( crypto_sign( crypto_generichash( M + R, SK ) ), N, S) + +where N is the nonce, M the message, R the recipient list, SK is the senders +secret signing key and S the symmetric key. =head2 Z85 ENCODING diff --git a/man/z85.1 b/man/z85.1 deleted file mode 100644 index 49f8aa4..0000000 --- a/man/z85.1 +++ /dev/null @@ -1,231 +0,0 @@ -.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. \*(C+ will -.\" give a nicer C++. Capital omega is used to do unbreakable dashes and -.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, -.\" nothing in troff, for use with C<>. -.tr \(*W- -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" Escape single quotes in literal strings from groff's Unicode transform. -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.ie \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.el \{\ -. de IX -.. -.\} -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "Z85 1" -.TH Z85 1 "2013-10-25" "Z85 0.0.1" "USER CONTRIBUTED DOCUMENTATION" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.if n .ad l -.nh -.SH "NAME" -z85 \- encode and decode strings to Z85 encoding. -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 1 -\& Usage: z85 [options] [] -\& -\& Options: -\& \-e encode input to Z85 -\& \-d decode input from Z85 -\& \-h print this help message -\& \-v print program version -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\fBz85\fR can be used to encode and decode strings to Z85 encoding. -.PP -The option \fB\-e\fR encodes \fBto\fR Z85, which is the default if -no option have been specified. The option \fB\-d\fR does the opposite -and decodes b Z85. -.PP -If no input file have been specified, \fBz85\fR expects the -input to come from \fB\s-1STDIN\s0\fR, otherwise it reads the contents -of \fBfile\fR. -.PP -Encoded or decoded output will always be written to \fB\s-1STDOUT\s0\fR. -.SH "EXAMPLES" -.IX Header "EXAMPLES" -To encode a given file to Z85 and write the output to another: -.PP -.Vb 1 -\& z85 \-e myfile.bin > myfile.z85 -.Ve -.PP -To decode the file created above and restore the original: -.PP -.Vb 1 -\& z85 \-d myfile.z85 > myfile.bin -.Ve -.PP -To encode something from stdin to Z85: -.PP -.Vb 1 -\& ps axuw | z85 > pslist.z85 -.Ve -.PP -To decode the above and print to stdout: -.PP -.Vb 1 -\& z85 \-d pslist.z85 -.Ve -.SH "BACKGROUND" -.IX Header "BACKGROUND" -The Z85 encoding format is described here: . -It's part of ZeroMQ (). Z85 is based on \s-1ASCII85\s0 with -a couple of modifications (portability, readability etc). -.PP -To fulfil the requirements of the ZeroMQ Z85 functions, the \fBz85\fR utility -does some additional preparations of raw input before actually doing the -encoding, since the input for \fIzmq_z85_encode()\fR must be divisible by 4: -.PP -Expand the input so that the resulting size is divisible by 4. -.PP -Fill the added bytes with zeroes. -.PP -Prepend the input with a one byte value which holds the number of zeroes -added in the previous step. -.PP -Example: -.PP -Raw input: -.PP -.Vb 1 -\& hello\e0 -.Ve -.PP -Here, the input size is 6, which is insufficient, therefore it has to be expanded -to be 8. After the process the input looks like this: -.PP -.Vb 1 -\& 1hello\e0\e0 -.Ve -.PP -So, we padded the input with 1 zero (makes 7 bytes) and preprended it with the -value 1 (the number of zeros added): makes 8 bytes total. -.PP -After decoding Z85 input the process will be reversed. -.PP -\&\fBTrying to use another tool to decode an Z85 encoded string produced -by z85, might not work therefore, unless the tool takes the padding scheme -outlined above into account\fR. -.SH "COPYRIGHT" -.IX Header "COPYRIGHT" -Copyright (c) 2013 by T.Linden -.SH "AUTHORS" -.IX Header "AUTHORS" -\&\fIT.Linden -.SH "LICENSE" -.IX Header "LICENSE" -Licensed under the \s-1GNU\s0 \s-1GENERAL\s0 \s-1PUBLIC\s0 \s-1LICENSE\s0 version 3. diff --git a/man/z85.pod b/man/z85.pod deleted file mode 100644 index 4ddfb84..0000000 --- a/man/z85.pod +++ /dev/null @@ -1,99 +0,0 @@ -# -*-cperl-*- - -=head1 NAME - -z85 - encode and decode strings to Z85 encoding. - -=head1 SYNOPSIS - - Usage: z85 [options] [] - - Options: - -e encode input to Z85 - -d decode input from Z85 - -h print this help message - -v print program version - -=head1 DESCRIPTION - -B can be used to encode and decode strings to Z85 encoding. - -The option B<-e> encodes B Z85, which is the default if -no option have been specified. The option B<-d> does the opposite -and decodes b Z85. - -If no input file have been specified, B expects the -input to come from B, otherwise it reads the contents -of B. - -Encoded or decoded output will always be written to B. - -=head1 EXAMPLES - -To encode a given file to Z85 and write the output to another: - - z85 -e myfile.bin > myfile.z85 - -To decode the file created above and restore the original: - - z85 -d myfile.z85 > myfile.bin - -To encode something from stdin to Z85: - - ps axuw | z85 > pslist.z85 - -To decode the above and print to stdout: - - z85 -d pslist.z85 - -=head1 BACKGROUND - -The Z85 encoding format is described here: L. -It's part of ZeroMQ (L). Z85 is based on ASCII85 with -a couple of modifications (portability, readability etc). - -To fulfil the requirements of the ZeroMQ Z85 functions, the B utility -does some additional preparations of raw input before actually doing the -encoding, since the input for zmq_z85_encode() must be divisible by 4: - -Expand the input so that the resulting size is divisible by 4. - -Fill the added bytes with zeroes. - -Prepend the input with a one byte value which holds the number of zeroes -added in the previous step. - -Example: - -Raw input: - - hello\0 - -Here, the input size is 6, which is insufficient, therefore it has to be expanded -to be 8. After the process the input looks like this: - - 1hello\0\0 - -So, we padded the input with 1 zero (makes 7 bytes) and preprended it with the -value 1 (the number of zeros added): makes 8 bytes total. - -After decoding Z85 input the process will be reversed. - -B. - -=head1 COPYRIGHT - -Copyright (c) 2013 by T.Linden - -=head1 AUTHORS - -I> - -=head1 LICENSE - -Licensed under the GNU GENERAL PUBLIC LICENSE version 3. - -=cut -