scip/pcp
1
0
Fork 0
mirror of https://codeberg.org/scip/pcp.git synced 2025-12-17 03:50:57 +01:00
Code Issues Packages Projects Releases Wiki Activity

updated format descriptions to be more formal and reproducible

Browse Source
This commit is contained in:
git@daemon.de
2014-02-06 11:26:45 +01:00
parent 4a12cb0c2c
commit d1d169b1fc
3 changed files with 74 additions and 335 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
man/details.pod
View File

@@ -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<ENCRYPTED OUTPUT FORMAT>
followed by the binary signature described in B<SIGNATURE FORMAT> without
the offset separator.
followed by the binary encrypted signature described in B<SIGNATURE FORMAT>
without the offset separator.
However, not only the hash of the file content will be signed but the
recipient list described in B<ENCRYPTED OUTPUT FORMAT> 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<ENCRYPTED OUTPUT FORMAT>).
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

231
man/z85.1
View File

@@ -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] [<file>]
\&
\& 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<from> 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: <http://rfc.zeromq.org/spec:32>.
It's part of ZeroMQ (<http://zeromq.org>). 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 <tom \s-1AT\s0 cpan \s-1DOT\s0 org>
.SH "AUTHORS"
.IX Header "AUTHORS"
\&\fIT.Linden <tom \s-1AT\s0 cpan \s-1DOT\s0 org\fR>
.SH "LICENSE"
.IX Header "LICENSE"
Licensed under the \s-1GNU\s0 \s-1GENERAL\s0 \s-1PUBLIC\s0 \s-1LICENSE\s0 version 3.

99
man/z85.pod
View File

@@ -1,99 +0,0 @@
# -*-cperl-*-
=head1 NAME
z85 - encode and decode strings to Z85 encoding.
=head1 SYNOPSIS
Usage: z85 [options] [<file>]
Options:
-e encode input to Z85
-d decode input from Z85
-h print this help message
-v print program version
=head1 DESCRIPTION
B<z85> can be used to encode and decode strings to Z85 encoding.
The option B<-e> encodes B<to> Z85, which is the default if
no option have been specified. The option B<-d> does the opposite
and decodes b<from> Z85.
If no input file have been specified, B<z85> expects the
input to come from B<STDIN>, otherwise it reads the contents
of B<file>.
Encoded or decoded output will always be written to B<STDOUT>.
=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<http://rfc.zeromq.org/spec:32>.
It's part of ZeroMQ (L<http://zeromq.org>). Z85 is based on ASCII85 with
a couple of modifications (portability, readability etc).
To fulfil the requirements of the ZeroMQ Z85 functions, the B<z85> 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<Trying 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>.
=head1 COPYRIGHT
Copyright (c) 2013 by T.Linden <tom AT cpan DOT org>
=head1 AUTHORS
I<T.Linden <tom AT cpan DOT org>>
=head1 LICENSE
Licensed under the GNU GENERAL PUBLIC LICENSE version 3.
=cut