From 3c9785e38e13351cdf19d94d7fc0801ec8ec54a8 Mon Sep 17 00:00:00 2001 From: "git@daemon.de" Date: Mon, 27 Jan 2014 16:13:35 +0100 Subject: [PATCH] updated POD to reflect recent changes --- ChangeLog | 10 ++ README.pod | 19 +-- README.txt | 6 +- man/pcp.pod | 6 +- man/pcp1.1 | 320 +++++++++++++++++++++++++++++++++++---------------- man/pcp1.pod | 287 ++++++++++++++++++++++++++++++++------------- src/usage.h | 6 +- 7 files changed, 449 insertions(+), 205 deletions(-) diff --git a/ChangeLog b/ChangeLog index 76d00ef..775c3e4 100644 --- a/ChangeLog +++ b/ChangeLog @@ -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 diff --git a/README.pod b/README.pod index 86363c4..9bcd077 100644 --- a/README.pod +++ b/README.pod @@ -1,16 +1,3 @@ -=head1 CAUTION - -B - -B - =head1 DESCRIPTION B (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. diff --git a/README.txt b/README.txt index 6a1f606..8a08fa4 100644 --- a/README.txt +++ b/README.txt @@ -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. diff --git a/man/pcp.pod b/man/pcp.pod index 0b85699..b2bc2e4 100644 --- a/man/pcp.pod +++ b/man/pcp.pod @@ -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. diff --git a/man/pcp1.1 b/man/pcp1.1 index 4d550d5..477df4b 100644 --- a/man/pcp1.1 +++ b/man/pcp1.1 @@ -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 Verify a signature in 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( 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 diff --git a/man/pcp1.pod b/man/pcp1.pod index e739f55..107370d 100644 --- a/man/pcp1.pod +++ b/man/pcp1.pod @@ -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 Verify a signature in 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 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 -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 + +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 + +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 + +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 + +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 -Take a look at the function B for details. +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 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 + +=item encrypt it asymetrically for each recipient using a unique nonce (B) + +=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( +followed by the binary signature described in B without +the offset separator. =head2 Z85 ENCODING -B uses Z85 to encode exported keys and encrypted messages. -Therefore it includes a Z85 utility mode: - -B can be used to encode and decode strings to Z85 encoding. - -The option B<-z> encodes B Z85, the option B<-Z> does the opposite -and decodes B Z85. - -If no input file have been specified using B<-I>, B expects the -input to come from B, otherwise it reads the contents -of B. - -Encoded or decoded output will be written to B 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 uses Z85 to encode exported keys and armored signatures. =head3 Z85 BACKGROUND @@ -519,6 +636,12 @@ B. +=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 diff --git a/src/usage.h b/src/usage.h index 41e1f76..62f45f2 100644 --- a/src/usage.h +++ b/src/usage.h @@ -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 Verify a signature in 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" \