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 POD to reflect recent changes

Browse Source
This commit is contained in:
git@daemon.de
2014-01-27 16:13:35 +01:00
parent 770d8cb234
commit 3c9785e38e
7 changed files with 449 additions and 205 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
ChangeLog
View File

@@ -29,6 +29,16 @@
32k blockwise as well. Detached signatures are now
z85 encoded always.
Now you can also crypt+sign files with pcp1. Signatures
of encrypted files are always binary appended as is,
no offset designator. This leads to a couple of
problems which need to be solved somehow in the
future: recipient doesn't know whether to decrypt
the file or to decrypt and verify it. Also it's unclear
how to behave if decryption works but the signature
doesn't verify. Currently pcp1 failes in this case,
but leaves the decrypted result on disk. Hm...
0.1.5 Fixed a segmentation fault when using pcp1 -t on a
public key. I added a double free() there by purpose
to test segfault catching I added in unittest.pl

19
README.pod
View File

@@ -1,16 +1,3 @@
=head1 CAUTION
B<I'm currently in the process to rewrite major parts of PCP,
especially the asymetric crypto parts. Current master is incompatible
to earlier versions and might or might not work. Head back until
this message disappears. Thanks.>
B<Update 22/01/2014: Changes are complete, all unittests pass. So, pcp is
usable again on its own. However, I'm not sure if it's already fully compatible
with pbp, since I cant get pbp running here. Also, there#s still no key format
agreement between stef and me and not import function for our respective
pubkey formats.>
=head1 DESCRIPTION
B<Pretty Curved Privacy> (pcp1) is a commandline utility which can
@@ -64,10 +51,10 @@ sends it to Bobby, who in turn decrypts it:
Alicia Bobby
echo "Love you, honey" > letter
pcp1 -e -i 0x29A323A2C295D391 -I letter -O letter.z85
cat letter.z85 | mail bobby@foo.bar
pcp1 -e -r Bobby -I letter -O letter.asc
cat letter.asc | mail bobby@foo.bar
pcp1 -d -I letter.z85 | less
pcp1 -d -I letter.asc | less
And that's it.

6
README.txt
View File

@@ -48,10 +48,10 @@ QUICKSTART
Alicia Bobby
echo "Love you, honey" > letter
pcp1 -e -i 0x29A323A2C295D391 -I letter -O letter.z85
cat letter.z85 | mail bobby@foo.bar
pcp1 -e -r Bobby -I letter -O letter.asc
cat letter.asc | mail bobby@foo.bar
pcp1 -d -I letter.z85 | less
pcp1 -d -I letter.asc | less
And that's it.

6
man/pcp.pod
View File

@@ -51,10 +51,10 @@ sends it to Bobby, who in turn decrypts it:
Alicia Bobby
echo "Love you, honey" > letter
pcp1 -e -i 0x29A323A2C295D391 -I letter -O letter.z85
cat letter.z85 | mail bobby@foo.bar
pcp1 -e -r Bobby -I letter -O letter.asc
cat letter.asc | mail bobby@foo.bar
pcp1 -d -I letter.z85 | less
pcp1 -d -I letter.asc | less
And that's it.

320
man/pcp1.1
View File

@@ -1,4 +1,4 @@
.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
@@ -124,7 +124,7 @@
.\" ========================================================================
.\"
.IX Title "PCP1 1"
.TH PCP1 1 "2014-01-19" "PCP 0.1.5" "USER CONTRIBUTED DOCUMENTATION"
.TH PCP1 1 "2014-01-27" "PCP 0.2.0" "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
@@ -193,14 +193,22 @@ Pretty Curved Privacy \- File encryption using eliptic curve cryptography.
\& as YAML formatted text. Use \-O to put
\& the export into a file.
\& Encryption Options:
\& \-e \-\-encrypt Encrypt a message. Read from stdin or
\& specified via \-I. If a keyid (\-i) has been
\& \-e \-\-encrypt Asym\-Encrypt a message. Read from stdin or
\& specified via \-I. Output will be written
\& to stdout or the file given with \-O.
\& If a keyid (\-i) has been
\& given, use that public key for encryption.
\& If a recipient (\-r) has been given, use
\& a derived public key. If none of \-i or
\& \-r has been given, use the primary
\& secret key and the public part of it
\& for encrytion (self\-encryption mode).
\& If one or more recipient (\-r) has been given,
\& encrypt the message for all recipients
\& asymetrically, given there are matching
\& public keys installed in the vault for them.
\& If none of \-i or \-r has been given, encrypt
\& the message symetrically. This is the same
\& as \-m (self\-encryption mode).
\& \-m \-\-encrypt\-me Sym\-Encrypt a message. Specify \-I and/or
\& \-O for input/output file. You will be asked
\& for a passphrase. No key material will
\& be used. Same as \-e without \-r and \-i.
\& \-d \-\-decrypt Decrypt a message. Read from stdin or
\& specified via \-I. Output to stdout or
\& written to the file specified via \-O.
@@ -209,17 +217,25 @@ Pretty Curved Privacy \- File encryption using eliptic curve cryptography.
\& just one secret key in the vault, this
\& one will be used. Otherwise you\*(Aqll have
\& to specify the keyid (\-i) of the key.
\& You need to have the public key of the
\& sender installed in your vault.
\& If the input is self\-encrypted (symetrically)
\& a passphrase will be requested.
\&
\& Signature Options:
\& \-g \-\-sign Create a signature of file specified with
\& \-I (or from stdin) using your primary
\& secret key. If \-r has been given, a derived
\& secret key will be used for signing.
\&
\& \-c \-\-check\-signature <file> Verify a signature in file <file> against
\& the file specified with \-I (or stdin).
\& The public key required for this must
\& exist in your vault file.
\& \-a \-\-detach Write a detached signature file, which doesn\*(Aqt
\& contain the original content. Output will be
\& z85 encoded always. To verify, you need to
\& specify the original file to be verified
\& against using \-I as well (plus \-a).
\&
\& Encoding Options:
\& \-z \-\-z85\-encode Encode something to Z85 encoding. Use
@@ -289,10 +305,10 @@ sends it to Bobby, who in turn decrypts it:
.Vb 4
\& Alicia Bobby
\& echo "Love you, honey" > letter
\& pcp1 \-e \-i 0x29A323A2C295D391 \-I letter \-O letter.z85
\& cat letter.z85 | mail bobby@foo.bar
\& pcp1 \-e \-r Bobby \-I letter \-O letter.asc
\& cat letter.asc | mail bobby@foo.bar
\&
\& pcp1 \-d \-I letter.z85 | less
\& pcp1 \-d \-I letter.asc | less
.Ve
.PP
And that's it.
@@ -342,33 +358,29 @@ There are 2 modes of encryption available in pcp1:
.IP "\fBStandard public key encryption\fR" 4
.IX Item "Standard public key encryption"
In this mode, which is the default, a public key as specified
with \fB\-i\fR and a dynamically generated secret key will be used
for encryption. The public part of the generated sender key
will be included with the encrypted file, which the recipient
can use to decrypt it.
with \fB\-i\fR or \fB\-r\fR and your primary secret key will be used
for encryption.
.Sp
Example command:
.Sp
.Vb 1
\& pcp1 \-e \-i 0x2BD734B15CE2722D \-I message.txt \-O cipher.z85
\& pcp1 \-e \-i 0x2BD734B15CE2722D \-I message.txt \-O message.asc
.Ve
.Sp
Here we didn't specify a recipient. Therefore the public
key given with \-i will be used directly.
.Sp
Another example:
.Sp
.Vb 1
\& pcp1 \-e \-r Bobby \-r McCoy \-I message.txt \-O message.asc
.Ve
.IP "\fBSelf encryption mode\fR" 4
.IX Item "Self encryption mode"
Pretty Curved Privacy doesn't provide symetric file encryption.
However there are cases when you need to encrypt a file just
for yourself. In such a case the file will be encrypted using
the public key part of your primary secret key and the secret
key itself (thanks to the wonders of \s-1ECC\s0 this works like a charm).
.Sp
The file can be decrypted using the primary key pair.
.Sp
You can also encrypt a file symetrically. No public key material
will be used in this mode.
While this works, the security of it totally depends on the
strength of your password, especially if the primary secret
used for this kind of encryption is stored in a vault on the
same system.
strength of the passphrase used for encryption.
.Sp
Example command:
.Sp
@@ -377,7 +389,91 @@ Example command:
.Ve
.Sp
As you can see we didn't specify \-i or \-r and therefore pcp1
tries to use the primary keypair for encryption.
operates in self mode for encryption. It will ask you for a passphrase
to protect the encryption key.
.SH "SIGNATURES"
.IX Header "SIGNATURES"
There are 3 modes for digital signatures available on pcp1:
.IP "\fBStandard \s-1NACL\s0 binary signatures\fR" 4
.IX Item "Standard NACL binary signatures"
In this mode, which is the default, an \s-1ED25519\s0 signature will
be calculated from a \s-1BLAKE2\s0 hash of the input file content. Both
the original file content plus the signature will be written to
the output file.
.Sp
Example:
.Sp
.Vb 1
\& pcp1 \-g \-I message.txt \-O message.asc \-g
.Ve
.Sp
You will be asked for the passphrase to access your primary
secret key. The output file will be a binary file.
.IP "\fBArmored \s-1NACL\s0 signatures\fR" 4
.IX Item "Armored NACL signatures"
While this mode does the very same calculations, the output
slightly differs. The output file will be marked as a signature
file, the signature itself will be appended with its own headers
and Z85 encoded.
.Sp
Example:
.Sp
.Vb 1
\& pcp1 \-g \-I message.txt \-O message.asc \-g \-z
.Ve
.Sp
You will be asked for the passphrase to access your primary
secret key. The output file will be a text file.
.IP "\fBDetached \s-1NACL\s0 signatures\fR" 4
.IX Item "Detached NACL signatures"
In some cases you will need to have the signature separated
from the original input file, e.g. to sign download files. You
can generate detached signatures for such purposes. Still, the
signature will be calculated the same way as in standard signatures
but put out into a separate file. A detached signature file will always
be Z85 encoded.
.Sp
Example:
.Sp
.Vb 1
\& pcp1 \-g \-I message.txt \-O message.asc \-g \-\-detach
.Ve
.SH "SIGNED ENCRYPTION"
.IX Header "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 \s-1BLAKE2\s0 hash of
the file contents will be appended to it.
.PP
Example:
.PP
.Vb 1
\& pcp1 \-e \-g \-r Bobby \-I README.txt \-O README.asc
.Ve
.PP
Please note the additional \fB\-g\fR parameter. The recipient can
decrypt and verify the so created data like this:
.PP
.Vb 1
\& pcp1 \-d \-c \-I README.asc \-o README.txt
.Ve
.PP
Please note the additional \fB\-c\fR parameter.
.PP
If decryption works, the output file will be written. If signature
verification fails you will be informed, but the decrypted
output will be left untouched. It is up to you how to react
on an invalid signature.
.PP
\&\fBCaution: as of this writing (pcp version 0.2.0) there is
no offset marker included into the output which separates
the signature from the cipher. Therefore a recipient has to
know that the file is encrypted \s-1AND\s0 signed. If, for example,
the recpient leaves the \-c parameter on such a file, the decryption
process will fail. Otherwise, if the user supplies \-c on an
encrypted file without a signature, decryption will fail as well.\fR
.PP
Note: this behavior might change in the future.
.SH "VULNERABILITIES"
.IX Header "VULNERABILITIES"
Currently there are a couple of problems which are not
@@ -516,97 +612,115 @@ Key generation works like this:
.IP "\(bu" 4
Generate a random seed (32 bytes).
.IP "\(bu" 4
Generate a \s-1ED25519\s0 keypair from that seed.
Generate a \s-1ED25519\s0 sigining keypair from that seed.
.IP "\(bu" 4
Take the first 32 bytes of the generated \s-1ED25519\s0 secret
and generate a \s-1SHA512\s0 hash from it.
Generate a random seed (32 bytes).
.IP "\(bu" 4
Clamp bytes 0 and 31 which turns it into a Curve25519 secret.
.IP "\(bu" 4
Do scalar multiplication from that secret to retrieve
the matching public key.
Generate a Curve25519 encryption keypair from that seed.
.PP
So, while both secrets are stored in the sam \s-1PCP\s0 key, they
are otherwise unrelated. If one of them leaks, the other
cannot be recalculated from it.
.PP
Take a look at the function \fB\f(BIpcp_keypairs()\fB\fR for details.
.SS "\s-1ENCRYPTED\s0 \s-1OUTPUT\s0 \s-1FORMAT\s0"
.IX Subsection "ENCRYPTED OUTPUT FORMAT"
Encrypted output will always be Z85 encoded and has the following
format:
Encrypted output will always written as binary files. No armoring
supported yet. The encryption process works as this:
.IP "generate a random symetric 32 byte key \fBS\fR" 4
.IX Item "generate a random symetric 32 byte key S"
.PD 0
.IP "encrypt it asymetrically for each recipient using a unique nonce (\fBR\fR)" 4
.IX Item "encrypt it asymetrically for each recipient using a unique nonce (R)"
.IP "encrypt the input file 32k blockwise using the symetric key" 4
.IX Item "encrypt the input file 32k blockwise using the symetric key"
.PD
.PP
.Vb 9
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Field Size Description |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Pubkey | 32 | Publix key of the sender |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Nonce | 24 | Random Nonce |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Encrypted | ~ | The actual encrypted data |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
.Ve
.SS "\s-1SIGNATURE\s0 \s-1FORMAT\s0"
.IX Subsection "SIGNATURE FORMAT"
Signatures will always be Z85 encoded and have the following
format:
Symetric encryption works the very same with the recipient stuff
left out.
.PP
Formal format description, asymetric encrypted files:
.PP
.Vb 11
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Field Size Description |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Key ID | 17 | Signers key id
\& | Type | 1 | Filetype, 5=ASYM, 23=SYM |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Ctime | 4 | Creation time, sec since epoch |
\& | Len R | 4 | Number of recipients (*) |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Version | 4 | Signature version |
\& | Recipients | R*72 | C(recipient)|C(recipient)... (*) |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Signature | 96 | ED25519 signature of SHA256 Hash |
\& | Encrypted | ~ | The actual encrypted data |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
.Ve
.PP
Left out when doing symetric encryption.
.PP
Recipient field format:
.PP
.Vb 7
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Field Size Description |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Nonce | 24 | Random Nonce, one per R |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Cipher | 48 | S encrypted with PK or R |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
.Ve
.PP
R is calculated using public key encryption using the senders
secret key, the recipients public key and a random nonce.
.SS "\s-1SIGNATURE\s0 \s-1FORMAT\s0"
.IX Subsection "SIGNATURE FORMAT"
There are different signature formats. Standard binary \s-1NACL\s0
signatures have the following format:
.PP
.Vb 11
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Field Size Description |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Content | ~ | Original file content |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | \ennacl\- | 6 | Offset separator |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Hash | 64 | BLAKE2 hash of the content |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Signature | 64 | ED25519 signature of BLAKE2 Hash |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
.Ve
.PP
The actual signature is not a signature over the whole content
of an input file but of a \s-1SHA256\s0 hash of the content.
of an input file but of a \s-1BLAKE2\s0 hash of the content.
.PP
Armored signatures have the following format:
.PP
.Vb 2
\& \-\-\-\-\- BEGIN ED25519 SIGNED MESSAGE \-\-\-\-\-
\& Hash: Blake2
\&
\& MESSAGE
\&
\& \-\-\-\-\- BEGIN ED25519 SIGNATURE \-\-\-\-\-
\& Version: PCP v0.2.0
\&
\& 195j%\-^/G[cVo4dSk7hU@D>NT\-1rBJ]VbJ678H4I!%@\-)bzi>zOba5$KSgz7b@R]A0!kL$m
\& MTQ\-1DW(e1mma(<jH=QGA(VudgAMXaKF5AGo65Zx7\-5fuMZt&:6IL:n2N{KMto*KQ$:J+]d
\& dp1{3}Ju*M&+Vk7=:a=J0}B
\& \-\-\-\-\-\- END ED25519 SIGNATURE \-\-\-\-\-\-
.Ve
.PP
The Z85 encoded signature at the end contains the same signature
contents as the binary signature outlined above (hash+sig).
.SS "\s-1SIGNED\s0 \s-1ENCRYPTION\s0 \s-1FORMAT\s0"
.IX Subsection "SIGNED ENCRYPTION FORMAT"
Signed encrypted files are in binary form only. The first part is
the standard encrypted file as described in \fB\s-1ENCRYPTED\s0 \s-1OUTPUT\s0 \s-1FORMAT\s0\fR
followed by the binary signature described in \fB\s-1SIGNATURE\s0 \s-1FORMAT\s0\fR without
the offset separator.
.SS "Z85 \s-1ENCODING\s0"
.IX Subsection "Z85 ENCODING"
\&\fBpcp1\fR uses Z85 to encode exported keys and encrypted messages.
Therefore it includes a Z85 utility mode:
.PP
\&\fBpcp1\fR can be used to encode and decode strings to Z85 encoding.
.PP
The option \fB\-z\fR encodes \fBto\fR Z85, the option \fB\-Z\fR does the opposite
and decodes \fBfrom\fR Z85.
.PP
If no input file have been specified using \fB\-I\fR, \fBpcp1\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 be written to \fB\s-1STDOUT\s0\fR unless an
output file has been specified using the option \fB\-O\fR.
.PP
\fIZ85 \s-1EXAMPLES\s0\fR
.IX Subsection "Z85 EXAMPLES"
.PP
To encode a given file to Z85 and write the output to another:
.PP
.Vb 1
\& pcp1 \-z myfile.bin > myfile.z85
.Ve
.PP
To decode the file created above and restore the original:
.PP
.Vb 1
\& pcp1 \-Z \-d myfile.z85 > myfile.bin
.Ve
.PP
To encode something from stdin to Z85:
.PP
.Vb 1
\& ps axuw | pcp1 \-z > pslist.z85
.Ve
.PP
To decode the above and print to stdout:
.PP
.Vb 1
\& pcp1 \-Z \-d pslist.z85
.Ve
\&\fBpcp1\fR uses Z85 to encode exported keys and armored signatures.
.PP
\fIZ85 \s-1BACKGROUND\s0\fR
.IX Subsection "Z85 BACKGROUND"
@@ -649,6 +763,12 @@ After decoding Z85 input the process will be reversed.
\&\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.
.SS "\s-1PBP\s0 \s-1COMPATIBILITY\s0"
.IX Subsection "PBP COMPATIBILITY"
\&\s-1PCP\s0 tries to be fully compatible with \s-1PBP\s0 (https://github.com/stef/pbp). Encrypted
files and signatures \- at least their binary versions \- should be exchangable. However,
this is a work in progress and might not work under all circumstances. Also there's currently
no shared key format between pbp and pcp.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2013 by T.Linden <tom \s-1AT\s0 cpan \s-1DOT\s0 org>

285
man/pcp1.pod
View File

@@ -65,14 +65,22 @@ Pretty Curved Privacy - File encryption using eliptic curve cryptography.
as YAML formatted text. Use -O to put
the export into a file.
Encryption Options:
-e --encrypt Encrypt a message. Read from stdin or
specified via -I. If a keyid (-i) has been
-e --encrypt Asym-Encrypt a message. Read from stdin or
specified via -I. Output will be written
to stdout or the file given with -O.
If a keyid (-i) has been
given, use that public key for encryption.
If a recipient (-r) has been given, use
a derived public key. If none of -i or
-r has been given, use the primary
secret key and the public part of it
for encrytion (self-encryption mode).
If one or more recipient (-r) has been given,
encrypt the message for all recipients
asymetrically, given there are matching
public keys installed in the vault for them.
If none of -i or -r has been given, encrypt
the message symetrically. This is the same
as -m (self-encryption mode).
-m --encrypt-me Sym-Encrypt a message. Specify -I and/or
-O for input/output file. You will be asked
for a passphrase. No key material will
be used. Same as -e without -r and -i.
-d --decrypt Decrypt a message. Read from stdin or
specified via -I. Output to stdout or
written to the file specified via -O.
@@ -81,17 +89,25 @@ Pretty Curved Privacy - File encryption using eliptic curve cryptography.
just one secret key in the vault, this
one will be used. Otherwise you'll have
to specify the keyid (-i) of the key.
You need to have the public key of the
sender installed in your vault.
If the input is self-encrypted (symetrically)
a passphrase will be requested.
Signature Options:
-g --sign Create a signature of file specified with
-I (or from stdin) using your primary
secret key. If -r has been given, a derived
secret key will be used for signing.
-c --check-signature <file> Verify a signature in file <file> against
the file specified with -I (or stdin).
The public key required for this must
exist in your vault file.
-a --detach Write a detached signature file, which doesn't
contain the original content. Output will be
z85 encoded always. To verify, you need to
specify the original file to be verified
against using -I as well (plus -a).
Encoding Options:
-z --z85-encode Encode something to Z85 encoding. Use
@@ -155,10 +171,10 @@ sends it to Bobby, who in turn decrypts it:
Alicia Bobby
echo "Love you, honey" > letter
pcp1 -e -i 0x29A323A2C295D391 -I letter -O letter.z85
cat letter.z85 | mail bobby@foo.bar
pcp1 -e -r Bobby -I letter -O letter.asc
cat letter.asc | mail bobby@foo.bar
pcp1 -d -I letter.z85 | less
pcp1 -d -I letter.asc | less
And that's it.
@@ -210,42 +226,119 @@ There are 2 modes of encryption available in pcp1:
=item B<Standard public key encryption>
In this mode, which is the default, a public key as specified
with B<-i> and a dynamically generated secret key will be used
for encryption. The public part of the generated sender key
will be included with the encrypted file, which the recipient
can use to decrypt it.
with B<-i> or B<-r> and your primary secret key will be used
for encryption.
Example command:
pcp1 -e -i 0x2BD734B15CE2722D -I message.txt -O cipher.z85
pcp1 -e -i 0x2BD734B15CE2722D -I message.txt -O message.asc
Here we didn't specify a recipient. Therefore the public
key given with -i will be used directly.
Another example:
pcp1 -e -r Bobby -r McCoy -I message.txt -O message.asc
=item B<Self encryption mode>
Pretty Curved Privacy doesn't provide symetric file encryption.
However there are cases when you need to encrypt a file just
for yourself. In such a case the file will be encrypted using
the public key part of your primary secret key and the secret
key itself (thanks to the wonders of ECC this works like a charm).
The file can be decrypted using the primary key pair.
You can also encrypt a file symetrically. No public key material
will be used in this mode.
While this works, the security of it totally depends on the
strength of your password, especially if the primary secret
used for this kind of encryption is stored in a vault on the
same system.
strength of the passphrase used for encryption.
Example command:
pcp1 -e -I message.txt -O cipher.z85
As you can see we didn't specify -i or -r and therefore pcp1
tries to use the primary keypair for encryption.
operates in self mode for encryption. It will ask you for a passphrase
to protect the encryption key.
=back
=head1 SIGNATURES
There are 3 modes for digital signatures available on pcp1:
=over
=item B<Standard NACL binary signatures>
In this mode, which is the default, an ED25519 signature will
be calculated from a BLAKE2 hash of the input file content. Both
the original file content plus the signature will be written to
the output file.
Example:
pcp1 -g -I message.txt -O message.asc -g
You will be asked for the passphrase to access your primary
secret key. The output file will be a binary file.
=item B<Armored NACL signatures>
While this mode does the very same calculations, the output
slightly differs. The output file will be marked as a signature
file, the signature itself will be appended with its own headers
and Z85 encoded.
Example:
pcp1 -g -I message.txt -O message.asc -g -z
You will be asked for the passphrase to access your primary
secret key. The output file will be a text file.
=item B<Detached NACL signatures>
In some cases you will need to have the signature separated
from the original input file, e.g. to sign download files. You
can generate detached signatures for such purposes. Still, the
signature will be calculated the same way as in standard signatures
but put out into a separate file. A detached signature file will always
be Z85 encoded.
Example:
pcp1 -g -I message.txt -O message.asc -g --detach
=back
=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.
Example:
pcp1 -e -g -r Bobby -I README.txt -O README.asc
Please note the additional B<-g> parameter. The recipient can
decrypt and verify the so created data like this:
pcp1 -d -c -I README.asc -o README.txt
Please note the additional B<-c> parameter.
If decryption works, the output file will be written. If signature
verification fails you will be informed, but the decrypted
output will be left untouched. It is up to you how to react
on an invalid signature.
B<Caution: as of this writing (pcp version 0.2.0) there is
no offset marker included into the output which separates
the signature from the cipher. Therefore a recipient has to
know that the file is encrypted AND signed. If, for example,
the recpient leaves the -c parameter on such a file, the decryption
process will fail. Otherwise, if the user supplies -c on an
encrypted file without a signature, decryption will fail as well.>
Note: this behavior might change in the future.
=head1 VULNERABILITIES
@@ -392,95 +485,119 @@ Generate a random seed (32 bytes).
=item *
Generate a ED25519 keypair from that seed.
Generate a ED25519 sigining keypair from that seed.
=item *
Take the first 32 bytes of the generated ED25519 secret
and generate a SHA512 hash from it.
Generate a random seed (32 bytes).
=item *
Clamp bytes 0 and 31 which turns it into a Curve25519 secret.
=item *
Do scalar multiplication from that secret to retrieve
the matching public key.
Generate a Curve25519 encryption keypair from that seed.
=back
So, while both secrets are stored in the sam PCP key, they
are otherwise unrelated. If one of them leaks, the other
cannot be recalculated from it.
Take a look at the function B<pcp_keypairs()> for details.
=head2 ENCRYPTED OUTPUT FORMAT
Encrypted output will always be Z85 encoded and has the following
format:
Encrypted output will always written as binary files. No armoring
supported yet. The encryption process works as this:
=over
=item generate a random symetric 32 byte key B<S>
=item encrypt it asymetrically for each recipient using a unique nonce (B<R>)
=item encrypt the input file 32k blockwise using the symetric key
=back
Symetric encryption works the very same with the recipient stuff
left out.
Formal format description, asymetric encrypted files:
+---------------------------------------------------------+
| Field Size Description |
+-------------+--------+----------------------------------+
| Pubkey | 32 | Publix key of the sender |
| Type | 1 | Filetype, 5=ASYM, 23=SYM |
+-------------|--------|----------------------------------+
| Nonce | 24 | Random Nonce |
| Len R | 4 | Number of recipients (*) |
+-------------|--------|----------------------------------+
| Recipients | R*72 | C(recipient)|C(recipient)... (*) |
+-------------|--------|----------------------------------+
| Encrypted | ~ | The actual encrypted data |
+-------------|--------|----------------------------------+
=head2 SIGNATURE FORMAT
Left out when doing symetric encryption.
Signatures will always be Z85 encoded and have the following
format:
Recipient field format:
+---------------------------------------------------------+
| Field Size Description |
+-------------+--------+----------------------------------+
| Key ID | 17 | Signers key id
| Nonce | 24 | Random Nonce, one per R |
+-------------|--------|----------------------------------+
| Ctime | 4 | Creation time, sec since epoch |
| Cipher | 48 | S encrypted with PK or R |
+-------------|--------|----------------------------------+
| Version | 4 | Signature version |
R is calculated using public key encryption using the senders
secret key, the recipients public key and a random nonce.
=head2 SIGNATURE FORMAT
There are different signature formats. Standard binary NACL
signatures have the following format:
+---------------------------------------------------------+
| Field Size Description |
+-------------+--------+----------------------------------+
| Content | ~ | Original file content |
+-------------|--------|----------------------------------+
| Signature | 96 | ED25519 signature of SHA256 Hash |
| \nnacl- | 6 | Offset separator |
+-------------|--------|----------------------------------+
| Hash | 64 | BLAKE2 hash of the content |
+-------------|--------|----------------------------------+
| Signature | 64 | ED25519 signature of BLAKE2 Hash |
+-------------|--------|----------------------------------+
The actual signature is not a signature over the whole content
of an input file but of a SHA256 hash of the content.
of an input file but of a BLAKE2 hash of the content.
Armored signatures have the following format:
----- BEGIN ED25519 SIGNED MESSAGE -----
Hash: Blake2
MESSAGE
----- BEGIN ED25519 SIGNATURE -----
Version: PCP v0.2.0
195j%-^/G[cVo4dSk7hU@D>NT-1rBJ]VbJ678H4I!%@-)bzi>zOba5$KSgz7b@R]A0!kL$m
MTQ-1DW(e1mma(<jH=QGA(VudgAMXaKF5AGo65Zx7-5fuMZt&:6IL:n2N{KMto*KQ$:J+]d
dp1{3}Ju*M&+Vk7=:a=J0}B
------ END ED25519 SIGNATURE ------
The Z85 encoded signature at the end contains the same signature
contents as the binary signature outlined above (hash+sig).
=head2 SIGNED ENCRYPTION FORMAT
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.
=head2 Z85 ENCODING
B<pcp1> uses Z85 to encode exported keys and encrypted messages.
Therefore it includes a Z85 utility mode:
B<pcp1> can be used to encode and decode strings to Z85 encoding.
The option B<-z> encodes B<to> Z85, the option B<-Z> does the opposite
and decodes B<from> Z85.
If no input file have been specified using B<-I>, B<pcp1> expects the
input to come from B<STDIN>, otherwise it reads the contents
of B<file>.
Encoded or decoded output will be written to B<STDOUT> unless an
output file has been specified using the option B<-O>.
=head3 Z85 EXAMPLES
To encode a given file to Z85 and write the output to another:
pcp1 -z myfile.bin > myfile.z85
To decode the file created above and restore the original:
pcp1 -Z -d myfile.z85 > myfile.bin
To encode something from stdin to Z85:
ps axuw | pcp1 -z > pslist.z85
To decode the above and print to stdout:
pcp1 -Z -d pslist.z85
B<pcp1> uses Z85 to encode exported keys and armored signatures.
=head3 Z85 BACKGROUND
@@ -519,6 +636,12 @@ 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>.
=head2 PBP COMPATIBILITY
PCP tries to be fully compatible with PBP (https://github.com/stef/pbp). Encrypted
files and signatures - at least their binary versions - should be exchangable. However,
this is a work in progress and might not work under all circumstances. Also there's currently
no shared key format between pbp and pcp.
=head1 COPYRIGHT

6
src/usage.h
View File

@@ -94,11 +94,15 @@
" -I (or from stdin) using your primary\n" \
" secret key. If -r has been given, a derived\n" \
" secret key will be used for signing.\n" \
"\n" \
"-c --check-signature <file> Verify a signature in file <file> against\n" \
" the file specified with -I (or stdin).\n" \
" The public key required for this must\n" \
" exist in your vault file.\n" \
"-a --detach Write a detached signature file, which doesn't\n" \
" contain the original content. Output will be\n" \
" z85 encoded always. To verify, you need to\n" \
" specify the original file to be verified\n" \
" against using -I as well (plus -a).\n" \
"\n" \
"Encoding Options:\n" \
"-z --z85-encode Encode something to Z85 encoding. Use\n" \