diff --git a/README b/README index 033d187..eab92e4 100644 --- a/README +++ b/README @@ -111,7 +111,20 @@ INSTALLATION sudo ldconfig cd .. - Next, pcp: + If you want to have JSON support, you'll need to install the Jansson + library (optional): + + git clone git://github.com/akheron/jansson.git + cd jansson + autoreconf -i + ./configure && make + sudo make install + cd .. + + In order to use the python binding, you need to install the cffi python + package. + + Next, build pcp: git clone git://github.com/tlinden/pcp.git cd pcp diff --git a/README.pod b/README.pod index eac0f9b..ede4cf5 100644 --- a/README.pod +++ b/README.pod @@ -163,7 +163,7 @@ To learn how to use B, read the manpage: =head1 COPYRIGHT -Copyright (c) 2013-2016 by T.v.Dein +Copyright (c) 2013-2015 by T.v.Dein =head1 ADDITIONAL COPYRIGHTS diff --git a/bindings/py/pypcp/raw.py b/bindings/py/pypcp/raw.py index 129c083..1dcedfc 100644 --- a/bindings/py/pypcp/raw.py +++ b/bindings/py/pypcp/raw.py @@ -749,43 +749,43 @@ int pcp_readpass_fromprog(PCPCTX *ptx, char **passwd, const char *askpass); /*** ./gencffi.pl: from ../../include/pcp/scrypt.h:42 */ byte * pcp_scrypt(PCPCTX *ptx, char *passwd, size_t passwdlen, byte *nonce, size_t noncelen); -/*** ./gencffi.pl: from ../../include/pcp/util.h:141 */ +/*** ./gencffi.pl: from ../../include/pcp/util.h:142 */ char *_lc(char *in); -/*** ./gencffi.pl: from ../../include/pcp/util.h:141 */ +/*** ./gencffi.pl: from ../../include/pcp/util.h:142 */ long int _findoffset(byte *bin, size_t binlen, char *sigstart, size_t hlen); -/*** ./gencffi.pl: from ../../include/pcp/util.h:141 */ +/*** ./gencffi.pl: from ../../include/pcp/util.h:142 */ void _xorbuf(byte *iv, byte *buf, size_t xlen); -/*** ./gencffi.pl: from ../../include/pcp/util.h:141 */ +/*** ./gencffi.pl: from ../../include/pcp/util.h:142 */ void _dump(char *n, byte *d, size_t s); -/*** ./gencffi.pl: from ../../include/pcp/util.h:141 */ +/*** ./gencffi.pl: from ../../include/pcp/util.h:142 */ char *_bin2hex(byte *bin, size_t len); -/*** ./gencffi.pl: from ../../include/pcp/util.h:141 */ +/*** ./gencffi.pl: from ../../include/pcp/util.h:142 */ size_t _hex2bin(const char *hex_str, unsigned char *byte_array, size_t byte_array_max); -/*** ./gencffi.pl: from ../../include/pcp/util.h:141 */ +/*** ./gencffi.pl: from ../../include/pcp/util.h:142 */ int cst_time_memcmp(const void *m1, const void *m2, size_t n); -/*** ./gencffi.pl: from ../../include/pcp/util.h:141 */ +/*** ./gencffi.pl: from ../../include/pcp/util.h:142 */ uint64_t _wireto64(byte *data); -/*** ./gencffi.pl: from ../../include/pcp/util.h:141 */ +/*** ./gencffi.pl: from ../../include/pcp/util.h:142 */ uint32_t _wireto32(byte *data); -/*** ./gencffi.pl: from ../../include/pcp/util.h:141 */ +/*** ./gencffi.pl: from ../../include/pcp/util.h:142 */ uint16_t _wireto16(byte *data); -/*** ./gencffi.pl: from ../../include/pcp/util.h:141 */ +/*** ./gencffi.pl: from ../../include/pcp/util.h:142 */ void _64towire(uint64_t i, byte *data); -/*** ./gencffi.pl: from ../../include/pcp/util.h:141 */ +/*** ./gencffi.pl: from ../../include/pcp/util.h:142 */ void _32towire(uint32_t i, byte *data); -/*** ./gencffi.pl: from ../../include/pcp/util.h:141 */ +/*** ./gencffi.pl: from ../../include/pcp/util.h:142 */ void _16towire(uint16_t i, byte *data); /*** ./gencffi.pl: from ../../include/pcp/vault.h:230 */ @@ -898,91 +898,7 @@ PCP_ASYM_CIPHER = 5 # ./gencffi.pl: from ../../include/pcp/defines.h:185 -EXP_HASH_NAME = "BLAKE2" - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -EXP_SIG_TYPE = 0x1F - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -EXP_SIG_CIPHER_NAME = "ED25519" - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -PCP_ASYM_CIPHER_SIG = 24 - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -PCP_RFC_CIPHER = 0x21 - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -PCP_SYM_CIPHER = 23 - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -PCP_ZFILE_HEADER = "----- BEGIN Z85 ENCODED FILE -----" - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -PCP_SIG_START = "----- BEGIN ED25519 SIGNATURE -----" - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -EXP_SIG_SUB_KEYEXPIRE = 9 - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -PCP_VAULT_ID = 14 - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -EXP_SK_FOOTER = "----- END ED25519-CURVE29915 PRIVATE KEY -----" - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -PCP_SIGPREFIX = "\nnacl-" - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -EXP_PK_FOOTER = "----- END ED25519-CURVE29915 PUBLIC KEY -----" - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -EXP_SIG_SUB_SIGEXPIRE = 3 - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -PCP_SIG_END = "----- END ED25519 SIGNATURE -----" - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -EXP_FORMAT_NATIVE = 1 - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -PCP_ZFILE_FOOTER = "----- END Z85 ENCODED FILE -----" - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -EXP_FORMAT_PBP = 2 - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -EXP_PK_CIPHER = 0x21 - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -EXP_SIG_SUB_KEYFLAGS = 27 - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -EXP_SIG_SUB_CTIME = 2 - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -EXP_HASH_CIPHER = 0x22 +PCP_BLOCK_SIZE = 32 * 1024 # ./gencffi.pl: from ../../include/pcp/defines.h:185 @@ -990,23 +906,7 @@ EXP_PK_HEADER = "----- BEGIN ED25519-CURVE29915 PUBLIC KEY -----" # ./gencffi.pl: from ../../include/pcp/defines.h:185 -PCP_ENFILE_FOOTER = "\r\n----- END PCP ENCRYPTED FILE -----\r\n" - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -PCP_ASYM_CIPHER_ANON = 6 - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -EXP_SK_HEADER = "----- BEGIN ED25519-CURVE29915 PRIVATE KEY -----" - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -PBP_COMPAT_SALT = "qa~t](84z<1t<1oz:ik.@IRNyhG=8q(on9}4#!/_h#a7wqK{Nt$T?W>,mt8NqYq&6U,rSYI2GRDd:Bcm" - - -# ./gencffi.pl: from ../../include/pcp/defines.h:185 -EXP_SIG_CIPHER = 0x23 +EXP_SK_FOOTER = "----- END ED25519-CURVE29915 PRIVATE KEY -----" # ./gencffi.pl: from ../../include/pcp/defines.h:185 @@ -1014,24 +914,124 @@ PCP_ENFILE_HEADER = "----- BEGIN PCP ENCRYPTED FILE -----\r\n" # ./gencffi.pl: from ../../include/pcp/defines.h:185 -PCP_ME = "Pretty Curved Privacy" +EXP_FORMAT_NATIVE = 1 # ./gencffi.pl: from ../../include/pcp/defines.h:185 -EXP_PK_CIPHER_NAME = "CURVE25519-ED25519-POLY1305-SALSA20" +PBP_COMPAT_SALT = "qa~t](84z<1t<1oz:ik.@IRNyhG=8q(on9}4#!/_h#a7wqK{Nt$T?W>,mt8NqYq&6U,rSYI2GRDd:Bcm" # ./gencffi.pl: from ../../include/pcp/defines.h:185 -PCP_BLOCK_SIZE = 32 * 1024 +EXP_HASH_CIPHER = 0x22 + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +EXP_HASH_NAME = "BLAKE2" # ./gencffi.pl: from ../../include/pcp/defines.h:185 EXP_SIG_SUB_NOTATION = 20 +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +EXP_SIG_CIPHER_NAME = "ED25519" + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +EXP_SIG_CIPHER = 0x23 + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +PCP_ZFILE_HEADER = "----- BEGIN Z85 ENCODED FILE -----" + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +PCP_SIG_END = "----- END ED25519 SIGNATURE -----" + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +EXP_PK_CIPHER = 0x21 + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +PCP_RFC_CIPHER = 0x21 + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +PCP_ASYM_CIPHER_ANON = 6 + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +PCP_ENFILE_FOOTER = "\r\n----- END PCP ENCRYPTED FILE -----\r\n" + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +PCP_SYM_CIPHER = 23 + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +EXP_SIG_TYPE = 0x1F + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +EXP_SIG_SUB_KEYFLAGS = 27 + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +EXP_SK_HEADER = "----- BEGIN ED25519-CURVE29915 PRIVATE KEY -----" + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +PCP_SIGPREFIX = "\nnacl-" + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +PCP_ME = "Pretty Curved Privacy" + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +PCP_ZFILE_FOOTER = "----- END Z85 ENCODED FILE -----" + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +EXP_SIG_SUB_SIGEXPIRE = 3 + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +EXP_SIG_SUB_CTIME = 2 + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +EXP_PK_FOOTER = "----- END ED25519-CURVE29915 PUBLIC KEY -----" + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +PCP_VAULT_ID = 14 + + # ./gencffi.pl: from ../../include/pcp/defines.h:185 PCP_ASYM_CIPHER_ANON_SIG = 7 # ./gencffi.pl: from ../../include/pcp/defines.h:185 PCP_SIG_HEADER = "----- BEGIN ED25519 SIGNED MESSAGE -----" + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +PCP_ASYM_CIPHER_SIG = 24 + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +EXP_PK_CIPHER_NAME = "CURVE25519-ED25519-POLY1305-SALSA20" + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +EXP_FORMAT_PBP = 2 + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +EXP_SIG_SUB_KEYEXPIRE = 9 + + +# ./gencffi.pl: from ../../include/pcp/defines.h:185 +PCP_SIG_START = "----- BEGIN ED25519 SIGNATURE -----" diff --git a/include/pcp.h b/include/pcp.h index 9c1213d..bf2f993 100644 --- a/include/pcp.h +++ b/include/pcp.h @@ -7,7 +7,6 @@ extern "C" { #include "pcp/config.h" #include "pcp/buffer.h" -#include "pcp/config.h" #include "pcp/context.h" #include "pcp/crypto.h" #include "pcp/defines.h" diff --git a/man/pcp1.1 b/man/pcp1.1 index ac4146d..74c5fb0 100644 --- a/man/pcp1.1 +++ b/man/pcp1.1 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) +.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" Standard preamble: .\" ======================================================================== @@ -38,8 +38,6 @@ . ds PI \(*p . ds L" `` . ds R" '' -. ds C` -. ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. @@ -50,24 +48,17 @@ .\" 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. -.\" -.\" Avoid warning from groff about undefined register 'F'. -.de IX +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX .. -.nr rF 0 -.if \n(.g .if rF .nr rF 1 -.if (\n(rF:(\n(.g==0)) \{ -. if \nF \{ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. if !\nF==2 \{ -. nr % 0 -. nr F 2 -. \} -. \} .\} -.rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. @@ -133,7 +124,7 @@ .\" ======================================================================== .\" .IX Title "PCP1 1" -.TH PCP1 1 "2016-10-21" "PCP 0.4.0" "USER CONTRIBUTED DOCUMENTATION" +.TH PCP1 1 "2016-10-26" "PCP 0.4.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 @@ -351,7 +342,7 @@ Pretty Curved Privacy \- File encryption using eliptic curve cryptography. be used to encrypt files. \fBpcp1\fR uses eliptc curve cryptography for encryption (\s-1CURVE25519\s0 by Dan J. Bernstein). While \s-1CURVE25519\s0 is no worldwide accepted standard it hasn't been compromised by -the \s-1NSA \-\s0 which might be better, depending on your point of view. +the \s-1NSA\s0 \- which might be better, depending on your point of view. .PP \&\fBCaution\fR: since \s-1CURVE25519\s0 is no accepted standard, \fBpcp1\fR has to be considered as experimental software. In fact, I wrote it just @@ -677,10 +668,10 @@ Enable debugging output, where supported. Same as \fB\-D\fR. .IX Header "EXIT STATUS" Pcp may return one of several error codes if it encounters problems. .IP "0 No problems occurred." 4 -.IX Item "0 No problems occurred." +.IX Item "0 No problems occurred." .PD 0 .IP "1 Generic error code." 4 -.IX Item "1 Generic error code." +.IX Item "1 Generic error code." .PD .SH "FILES" .IX Header "FILES" @@ -747,7 +738,7 @@ for the worst like passphrases like \*(L"aaa\*(R" or \*(L"x\*(R". .PP Pcp considers passphrases with an entropy measurement of 3.32 or higher as acceptable. This may change in the future. -.SS "\s-1VAULT FORMAT\s0" +.SS "\s-1VAULT\s0 \s-1FORMAT\s0" .IX Subsection "VAULT FORMAT" The vault file contains all public and secret keys. It's a portable binary file. @@ -794,7 +785,7 @@ Type can be one of: .Ve .PP The key header is followed by the actual key, see below. -.SS "\s-1SECRET KEY FORMAT\s0" +.SS "\s-1SECRET\s0 \s-1KEY\s0 \s-1FORMAT\s0" .IX Subsection "SECRET KEY FORMAT" A secret key is a binary structure with the following format: .PP @@ -863,7 +854,7 @@ 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-1PUBLIC KEY EXPORT FORMAT\s0" +.SS "\s-1PUBLIC\s0 \s-1KEY\s0 \s-1EXPORT\s0 \s-1FORMAT\s0" .IX Subsection "PUBLIC KEY EXPORT FORMAT" Exported public and secret keys will be written in a portable way. Pcp uses \s-1RFC4880\s0 export format for public keys with some @@ -967,7 +958,7 @@ So, a full pubkey export looks like this \& hash \& signature .Ve -.SS "\s-1SECRET KEY EXPORT FORMAT\s0" +.SS "\s-1SECRET\s0 \s-1KEY\s0 \s-1EXPORT\s0 \s-1FORMAT\s0" .IX Subsection "SECRET KEY EXPORT FORMAT" Secret keys are exported in a proprietary format. .PP @@ -999,7 +990,7 @@ to encrypt the data and looks after encryption as such: .Vb 1 \& Nonce | Cipher .Ve -.SS "\s-1ENCRYPTED OUTPUT FORMAT\s0" +.SS "\s-1ENCRYPTED\s0 \s-1OUTPUT\s0 \s-1FORMAT\s0" .IX Subsection "ENCRYPTED OUTPUT FORMAT" The encryption protocol used by \s-1PCP\s0 uses mostly standard libsodium facilities with the exception that \s-1PCP\s0 uses counter @@ -1092,7 +1083,7 @@ of the sender. The encrypted output maybe Z85 encoded. In this case the Z85 encoding will be done blockwise with blocks of 16k bytes. The decoded content inside will be as described above. -.SS "\s-1SIGNATURE FORMAT\s0" +.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: @@ -1144,15 +1135,15 @@ Armored signatures have the following format: .PP The Z85 encoded signature at the end contains the same signature contents as the binary signature outlined above (hash+sig). -.SS "\s-1SIGNED ENCRYPTION FORMAT\s0" +.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 OUTPUT FORMAT\s0\fR -followed by the binary encrypted signature described in \fB\s-1SIGNATURE FORMAT\s0\fR +the standard encrypted file as described in \fB\s-1ENCRYPTED\s0 \s-1OUTPUT\s0 \s-1FORMAT\s0\fR +followed by the binary encrypted signature described in \fB\s-1SIGNATURE\s0 \s-1FORMAT\s0\fR without the offset separator. .PP However, not only the hash of the file content will be signed but the -recipient list described in \fB\s-1ENCRYPTED OUTPUT FORMAT\s0\fR as well. A +recipient list described in \fB\s-1ENCRYPTED\s0 \s-1OUTPUT\s0 \s-1FORMAT\s0\fR 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 @@ -1192,7 +1183,7 @@ Before encryption the signature format is: \& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ .Ve .PP -where R is: C(recipient)|C(recipient)... (see \fB\s-1ENCRYPTED OUTPUT FORMAT\s0\fR). +where R is: C(recipient)|C(recipient)... (see \fB\s-1ENCRYPTED\s0 \s-1OUTPUT\s0 \s-1FORMAT\s0\fR). .PP Pseudocode: .PP @@ -1259,9 +1250,9 @@ pcp1 \-z \-I file \-O file.z85 Reverse the process: .PP pcp1 \-Z \-I file.z85 \-O file -.SS "\s-1PBP COMPATIBILITY\s0" +.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 +\&\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. However, it is possible to export and @@ -1285,8 +1276,8 @@ functions: .PD .PP \&\s-1JSON\s0 support can be used either with the commandline tool \fBpcp1\fR or programmatically -using the C, \*(C+ or Python \s-1API.\s0 -.SS "\s-1USING JSON FROM THE C API\s0" +using the C, \*(C+ or Python \s-1API\s0. +.SS "\s-1USING\s0 \s-1JSON\s0 \s-1FROM\s0 \s-1THE\s0 C \s-1API\s0" .IX Subsection "USING JSON FROM THE C API" In order to use \s-1JSON\s0 all you've got to do is to switch a context flag: .PP @@ -1296,9 +1287,9 @@ In order to use \s-1JSON\s0 all you've got to do is to switch a context flag: .Ve .PP That all to it. Now any function normally used for key import and export works -with \s-1JSON,\s0 just fill the \fBBuffer\fR object with a \s-1JSON\s0 string for imports or +with \s-1JSON\s0, just fill the \fBBuffer\fR object with a \s-1JSON\s0 string for imports or fetch the Buffer content of an export function as a string. -.SS "\s-1USING JSON FROM THE COMMANDLINE\s0" +.SS "\s-1USING\s0 \s-1JSON\s0 \s-1FROM\s0 \s-1THE\s0 \s-1COMMANDLINE\s0" .IX Subsection "USING JSON FROM THE COMMANDLINE" In order to use \s-1JSON\s0 on the commandline, add \fB\-j\fR. This can be used in conjunction with the following options: @@ -1316,9 +1307,9 @@ Public and secret key import. Text view mode (aka inspect mode). .PP The \fB\-z\fR and \fB\-Z\fR options are ignored in \s-1JSON\s0 mode. -.SS "\s-1JSON OBJECT STRUCTURE\s0" +.SS "\s-1JSON\s0 \s-1OBJECT\s0 \s-1STRUCTURE\s0" .IX Subsection "JSON OBJECT STRUCTURE" -\fI\s-1JSON PUBLIC KEY \s0(pcp1 \-p \-j)\fR +\fI\s-1JSON\s0 \s-1PUBLIC\s0 \s-1KEY\s0 (pcp1 \-p \-j)\fR .IX Subsection "JSON PUBLIC KEY (pcp1 -p -j)" .PP The \s-1JSON\s0 object for a public key looks like this: @@ -1347,7 +1338,7 @@ Fields containing byte arrays are hex encoded. .PP Numbers are represented as literal integers. .PP -\fI\s-1JSON SECRET KEY \s0(pcp1 \-s \-j)\fR +\fI\s-1JSON\s0 \s-1SECRET\s0 \s-1KEY\s0 (pcp1 \-s \-j)\fR .IX Subsection "JSON SECRET KEY (pcp1 -s -j)" .PP The \s-1JSON\s0 object for a public key looks like this: @@ -1378,7 +1369,7 @@ secret key material. Pcp does not support exporting a secret key unencrypted. The \fBnonce\fR is required for a later import and shall not be changed or decoupled from \fBsecrets\fR. This may change in the future. .PP -\fI\s-1JSON VAULT \s0(pcp1 \-t)\fR +\fI\s-1JSON\s0 \s-1VAULT\s0 (pcp1 \-t)\fR .IX Subsection "JSON VAULT (pcp1 -t)" .PP The \s-1JSON\s0 object for the vault looks like this: @@ -1397,7 +1388,7 @@ The \s-1JSON\s0 object for the vault looks like this: The field \fBkeys\fR is an array containing one or more of the already described key objects. .PP -\fI\s-1JSON PROGRAM OUTPUT\s0\fR +\fI\s-1JSON\s0 \s-1PROGRAM\s0 \s-1OUTPUT\s0\fR .IX Subsection "JSON PROGRAM OUTPUT" .PP Currently pcp does not support \s-1JSON\s0 program output, that is, success or @@ -1446,7 +1437,7 @@ under the \fB\s-1GPL\s0\fR as well. \&\fIT.v.Dein .SH "LICENSE" .IX Header "LICENSE" -Licensed under the \s-1GNU GENERAL PUBLIC LICENSE\s0 version 3. +Licensed under the \s-1GNU\s0 \s-1GENERAL\s0 \s-1PUBLIC\s0 \s-1LICENSE\s0 version 3. .SH "HOME" .IX Header "HOME" The homepage of Pretty Curved Privacy can be found on diff --git a/man/pcp1.html b/man/pcp1.html index 3c5f9f8..538fa73 100644 --- a/man/pcp1.html +++ b/man/pcp1.html @@ -2,78 +2,94 @@ - +Privacy - File encryption using eliptic curve cryptography. - + + +
+

-
+ +

+

+

NAME

Pretty Curved Privacy - File encryption using eliptic curve cryptography.

- -

SYNOPSIS

- -
  Usage: pcp1 [ --help          | --version ]
+

+

+

+
SYNOPSIS

+
+  
+  Usage: pcp1 [ --help          | --version ]
               [ --keygen        | --listkeys      | --remove-key | --edit-key ]
               [ --export-public | --export-secret | --import ]
               [ --encrypt       | --decrypt       ]
@@ -103,8 +119,8 @@
   -s --export-secret        Export a secret key.
   -p --export-public        Export a public key.
   -K --import               Import a secret or public key.
-  -F --export-format <fmt>  Specify exportformat, either 'pbp' or 'pcp'.
-                            'pcp' is the default if unspecified.
+  -F --export-format <fmt>  Specify exportformat, either 'pbp' or 'pcp'.
+                            'pcp' is the default if unspecified.
   -j --json                 Enable JSON output (with -t, -p, -s and -K).
   
   Encryption Options:
@@ -131,12 +147,16 @@
   
   Arguments:
   Extra arguments after options are treated as filenames or
-  recipients, depending on operation mode.

+  recipients, depending on operation mode.
+

+

+
+

OPTIONS

+
 
-
OPTIONS

+ Usage: pcp1 [options]
+
 
-
 Usage: pcp1 [options]
- 
  General Options:
  -V --vault <vaultfile>    Specify an alternate vault file.
                            The deault vault is ~/.pcpvault.
@@ -163,19 +183,20 @@
  -h --help                 Print this help message.
     --version              Print program version.
  -D --debug                Enable debug output.
- -v --verbose              Enable verbose output.
- 
+ -v --verbose              Enable verbose output.

+
+
  Keymanagement Options:
  -k --keygen               Generate a CURVE25519 secret key. If
                            the generated key is the first one in
                            your vault, it will become the primary
                            secret key. If an output file (-O) has
-                           been specified, don't store the generated
+                           been specified, don't store the generated
                            key to the vault but export it to the
                            file instead. You will be asked for
                            an owner, mail and a passphrase.
  -l --listkeys             List all keys currently stored in your
-                           vault. Only the key id's and some info
+                           vault. Only the key id's and some info
                            about the keys will be printed, not the
                            actual keys.
  -L --listkeys-verbose     Display a more verbose key listing
@@ -202,8 +223,9 @@
                            Currently supported: pcp and pbp.
  -j --json                 enable JSON output. Can be used with info
                            output (-t) and key export (-p and -s).
-                           and import (-K).
- 
+                           and import (-K).

+
+
  Encryption Options:
  -e --encrypt              Asym-Encrypt a message. Read from stdin or
                            specified via -I. Output will be written
@@ -220,7 +242,7 @@
                            Add -z to ascii armor the output using Z85.
  -A --anonymous            Use anonymous sender key pair instead of
                            your own primary key pair. In this mode the
-                           recipient doesn't need to have your public
+                           recipient doesn't need to have your public
                            key.
  -m --encrypt-sym          Sym-Encrypt a message. Specify -I and/or
                            -O for input/output file. You will be asked
@@ -235,13 +257,14 @@
                            The primary secret key will be used for
                            decryption, if there is no primary and
                            just one secret key in the vault, this
-                           one will be used. Otherwise you'll have
+                           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.
- 
+                           a passphrase will be requested.

+
+
  Signature Options:
  -g --sign                 Create a signature of file specified with
                            -I (or from stdin) using your primary
@@ -251,12 +274,13 @@
                            the file specified with -I (or stdin).
                            The public key required for this must
                            exist in your vault file.
- -f --sigfile <file>       Write a detached signature file, which doesn't
+ -f --sigfile <file>       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 -f <sigfile>).
- 
+                           against using -I as well (plus -f <sigfile>).

+
+
  Encoding Options:
  -z --z85-encode           Encode (armor) something to Z85 encoding.
  -a --armor                If used with encryption or singing operation
@@ -265,347 +289,398 @@
                            uses stdin/stdout.
  -Z --z85-decode           Decode (dearmor) something from Z85 encoding.
                            Use -I and -O respectively, otherwise it
-                           uses stdin/stdout
- 
+                           uses stdin/stdout

+
+
  Misc Options:
  -C --checksum             Calculate a Blake2b checksum of one or more files.
                            If -x is provided, an authenticated hash will
                            be calculated, otherwise a normal hash.
                            Use -I to specify one file or put multiple file
-                           names after -C like "pcp1 -C -- file1 file2 file3".
- 

-
-
DESCRIPTION

-
-
Pretty Curved Privacy (pcp1) is a commandline utility which can be used to encrypt files. pcp1 uses eliptc curve cryptography for encryption (CURVE25519 by Dan J. Bernstein). While CURVE25519 is no worldwide accepted standard it hasn't been compromised by the NSA - which might be better, depending on your point of view.

-
-
Caution: since CURVE25519 is no accepted standard, pcp1 has to be considered as experimental software. In fact, I wrote it just to learn about the curve and see how it works.

-
-
Beside some differences it works like GNUPG. So, if you already know how to use gpg, you'll feel almost home.

-
-
QUICKSTART

-
-
Lets say, Alicia and Bobby want to exchange encrypted messages. Here's what the've got to do.

-
+                           names after -C like "pcp1 -C -- file1 file2 file3".
+

+

+
+

DESCRIPTION

+

Pretty Curved Privacy (pcp1) is a commandline utility which can +be used to encrypt files. pcp1 uses eliptc curve cryptography +for encryption (CURVE25519 by Dan J. Bernstein). While CURVE25519 +is no worldwide accepted standard it hasn't been compromised by +the NSA - which might be better, depending on your point of view.

+

Caution: since CURVE25519 is no accepted standard, pcp1 has +to be considered as experimental software. In fact, I wrote it just +to learn about the curve and see how it works.

+

Beside some differences it works like GNUPG. So, if you already +know how to use gpg, you'll feel almost home.

+

+

+
+

QUICKSTART

+

Lets say, Alicia and Bobby want to exchange encrypted messages. +Here's what the've got to do.

First, both have create a secret key:

- -
 Alicia                             Bobby
- pcp1 -k                            pcp1 -k
- -

After entering their name, email address and a passphrase to protect the key, it will be stored in their vault file (by default ~/.pcpvault).

- -

Now, both of them have to export the public key, which has to be imported by the other one. With pcp you can export the public part of your primary key, but the better solution is to export a derived public key especially for the recipient:

- -
 Alicia                             Bobby
- pcp1 -p -r Bobby -O alicia.pub     pcp1 -p -r Alicia -O bobby.pub
- -

They've to exchange the public key somehow (which is not my problem at the moment, use ssh, encrypted mail, whatever). Once exchanged, they have to import it:

- -
 Alicia                             Bobby
- pcp1 -K -I bobby.pub               pcp1 -K -I alicia.pub
- +
+ Alicia                             Bobby
+ pcp1 -k                            pcp1 -k
+

After entering their name, email address and a passphrase to protect +the key, it will be stored in their vault file (by default ~/.pcpvault).

+

Now, both of them have to export the public key, which has to be +imported by the other one. With pcp you can export the public +part of your primary key, but the better solution is to export +a derived public key especially for the recipient:

+
+ Alicia                             Bobby
+ pcp1 -p -r Bobby -O alicia.pub     pcp1 -p -r Alicia -O bobby.pub
+

They've to exchange the public key somehow (which is not my +problem at the moment, use ssh, encrypted mail, whatever). Once exchanged, +they have to import it:

+
+ Alicia                             Bobby
+ pcp1 -K -I bobby.pub               pcp1 -K -I alicia.pub

They will see a response as this when done:

- -
 key 0x29A323A2C295D391 added to .pcpvault.
- -

Now, Alicia finally writes the secret message, encrypts it and sends it to Bobby, who in turn decrypts it:

- -
 Alicia                             Bobby
+
+ key 0x29A323A2C295D391 added to .pcpvault.

+
Now, Alicia finally writes the secret message, encrypts it and
+sends it to Bobby, who in turn decrypts it:

+
+ Alicia                             Bobby
  echo "Love you, honey" > letter
  pcp1 -e -r Bobby -I letter -O letter.asc
- cat letter.asc | mail bobby@foo.bar
-
-                                    pcp1 -d -I letter.asc | less

-
-
And that's it.

-
-
Please note the big difference to GPG though: both Alicia AND Bobby have to enter the passphrase for their secret key! That's the way CURVE25519 works: you encrypt a message using your secret key and the recipients public key and the recipient does the opposite, he uses his secret key and your public key to actually decrypt the message.

-
-
Oh - and if you're wondering why I named them Alicia and Bobby: I was just sick of Alice and Bob. We're running NSA-free, so we're using other sample names as well.

-
-
FILES AND PIPES

-
-
Pcp behaves like any other unix tool. If not otherwise specified it will read input from standard input (STDIN) and print output to standard output (STDOUT). For instance:

-
-
 pcp1 -e -O output

-
-
will read the text to be encrypted from standard input, because -I has not been specified. It works the same with -O:

-
-
 pcp1 -e -I myfile

-
+ cat letter.asc | mail bobby@foo.bar
+
+                                    pcp1 -d -I letter.asc | less
+

And that's it.

+

Please note the big difference to GPG though: both Alicia +AND Bobby have to enter the passphrase for their secret key! +That's the way CURVE25519 works: you encrypt a message using +your secret key and the recipients public key and the recipient +does the opposite, he uses his secret key and your public key +to actually decrypt the message.

+

Oh - and if you're wondering why I named them Alicia and Bobby: +I was just sick of Alice and Bob. We're running NSA-free, so we're +using other sample names as well.

+

+

+
+

FILES AND PIPES

+

Pcp behaves like any other unix tool. If not otherwise specified +it will read input from standard input (STDIN) and print output +to standard output (STDOUT). For instance:

+
+ pcp1 -e -O output
+

will read the text to be encrypted from standard input, because -I +has not been specified. It works the same with -O:

+
+ pcp1 -e -I myfile

In this case the encrypted result will be written to standard output.

- -

Therefore it is possible to use pcp within pipes. Another more realistic example:

- -
 ssh remote cat file | pcp1 -ez | mailx -s 'as requested' bob@somewhere
- -

here we encrypt a file symmetrically without downloading it from a remote ssh server and sending the encrypted result via email to someone.

- -

The behavior is the same with any other functionality where files are involved like importing or exporting keys. However, there's one exception: If the option -X (--password-file) has been used and is set to -, then this will take precedence over any other possible use of standard input. So if you want to encrypt something and don't specify an input file you cannot use -X -, and vice versa. IF you use -X - the passphrase will be read from standard input, which then can't be used further for input files elsewhere. Pcp will exit with an error in such a case.

- -

PCP1 KEYS

- -

pcp1 keys are stored in a binary file, called the vault. It's by default located in ~/.pcpvault but you can of course specify another location using the -V option.

- -

There are two kinds of keys: secret and public keys. In reality a secret key always includes its public key. Both types of keys can be exported to files and transfered to other people who can then import them. You should usually only do this with public keys though.

- -

There is a primary secret key which will always used for operations when no keyid has been specified. However, you may have as many secret keys in your vault as you like.

- -

Each key can be identified using its keyid which looks like this:

- -
 0xD49119E85266509F
- -

A public key exported from a secret key will have the same keyid as the secret key.

- -

If you just want to know details about a key or the vault, use the -t option.

- -

ENCRYPTION

- +

Therefore it is possible to use pcp within pipes. Another more +realistic example:

+
+ ssh remote cat file | pcp1 -ez | mailx -s 'as requested' bob@somewhere
+

here we encrypt a file symmetrically without downloading it from a +remote ssh server and sending the encrypted result via email to +someone.

+

The behavior is the same with any other functionality where files are involved +like importing or exporting keys. However, there's one exception: +If the option -X (--password-file) has been used and is set +to -, then this will take precedence over any other possible use +of standard input. So if you want to encrypt something and don't +specify an input file you cannot use -X -, and vice versa. IF +you use -X - the passphrase will be read from standard input, which +then can't be used further for input files elsewhere. Pcp will exit +with an error in such a case.

+

+

+
+

PCP1 KEYS

+

pcp1 keys are stored in a binary file, called the vault. +It's by default located in ~/.pcpvault but you can of course +specify another location using the -V option.

+

There are two kinds of keys: secret and public keys. In reality +a secret key always includes its public key. Both types of keys +can be exported to files and transfered to other people who can +then import them. You should usually only do this with public keys +though.

+

There is a primary secret key which will always used for operations +when no keyid has been specified. However, you may have as many +secret keys in your vault as you like.

+

Each key can be identified using its keyid which looks like this:

+
+ 0xD49119E85266509F
+

A public key exported from a secret key will have the same keyid +as the secret key.

+

If you just want to know details about a key or the vault, use the +-t option.

+

+

+
+

ENCRYPTION

There are 3 modes of encryption available in pcp1:

-
+
Standard public key encryption
-
Standard public key encryption
- -

In this mode, which is the default, a public key as specified with -i or -r and your primary secret key will be used for encryption.

- +

In this mode, which is the default, a public key as specified +with -i or -r and your primary secret key will be used +for encryption.

Example command:

- -
 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.

- +
+ 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
- -

As you can see, it is also possible to encrypt a message for multiple recipients.

- +
+ pcp1 -e -r Bobby -r McCoy -I message.txt -O message.asc
+

As you can see, it is also possible to encrypt a message for multiple +recipients.

-
Anonymous public key encryption
+
Anonymous public key encryption
+
- -

In anonymous mode a random generated keypair will be used on the sender side. This way the recipient doesn't have to have your public key.

- +

In anonymous mode a random generated keypair will be used on the +sender side. This way the recipient doesn't have to have your public +key.

Example command:

- -
 pcp1 -r -r Bobby -A -I message.txt -O message.asc
- -

The public key part of the generated key pair will be included in the output, which potentiall lessens security. Use with care and avoid this mode when possible.

- +
+ pcp1 -r -r Bobby -A -I message.txt -O message.asc
+

The public key part of the generated key pair will be included in +the output, which potentiall lessens security. Use with care and +avoid this mode when possible.

-
Self encryption mode
+
Self encryption mode
+
- -

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 the passphrase used for encryption.

- +

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 the passphrase used for encryption.

Example command:

- -
 pcp1 -e -I message.txt -O cipher.z85
- -

As you can see we didn't specify any recipients (-i or -r) and therefore pcp1 operates in self mode encryption. It will ask you for a passphrase, from which an encryption key will be derived using scrypt().

- -

PCP doesn't validate the security of the passphrase.

- -

Self mode can be explicitly enforced with -m.

- +
+ pcp1 -e -I message.txt -O cipher.z85
+

As you can see we didn't specify any recipients (-i or -r) and therefore pcp1 +operates in self mode encryption. It will ask you for a passphrase, from which +an encryption key will be derived using scrypt().

+

PCP doesn't validate the security of the passphrase.

+

Self mode can be explicitly enforced with -m.

- -

SIGNATURES

- +

+

+
+

SIGNATURES

There are 3 modes for digital signatures available on pcp1:

-
+
Standard NACL binary signatures
-
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.

- +

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.

- +
+ 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.

-
Armored NACL signatures
+
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.

- +

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.

- +
+ 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.

-
Detached NACL signatures
+
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.

- +

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 -g --sigfile message.sig
- +
+ pcp1 -g -I message.txt -O -g --sigfile message.sig

Verification by recipient:

- -
 pcp -c -f message.sig -I message.txt
- +
+ pcp -c -f message.sig -I message.txt
- -

SIGNED ENCRYPTION

- -

Beside pure encryption and signatures pcp1 also supports signed encryption. In this mode an input file will be encrypted and a signature of the encrypted content and encrypted recipients with your primary secret key will be appended.

- +

+

+
+

SIGNED ENCRYPTION

+

Beside pure encryption and signatures pcp1 also supports signed +encryption. In this mode an input file will be encrypted and a +signature of the encrypted content and encrypted recipients with your primary +secret key will be appended.

The signature is encrypted as well.

-

Example:

- -
 pcp1 -e -g -r Bobby -I README.txt -O README.asc
- -

Please note the additional -g parameter. The recipient can decrypt and verify the so created data like this:

- -
 pcp1 -d -I README.asc -o README.txt
- -

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.

- -

ALTERNATIVE COMMANDLINES

- -

You can save typing if you supply additional arguments to pcp after commandline options. Such arguments are treated as filenames or recipients, depending what options you already specified.

- +
+ pcp1 -e -g -r Bobby -I README.txt -O README.asc
+

Please note the additional -g parameter. The recipient can +decrypt and verify the so created data like this:

+
+ pcp1 -d -I README.asc -o README.txt
+

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.

+

+

+
+

ALTERNATIVE COMMANDLINES

+

You can save typing if you supply additional arguments to +pcp after commandline options. Such arguments are treated +as filenames or recipients, depending what options you already +specified.

Here is a list of commandlines and their possible alternatives:

- -
 ORIGINAL                    ALTERNATIVE               DESCRIPTION
-
- pcp -e -I message -r Bob    pcp -e -r Bob message     use 'message' as inputfile.
-                             pcp -e -I message Bob     use 'Bob' as recipient,
-                                                       multiple recipients supported.
-
- pcp -d -I crypted           pcp -d crypted            use 'crypted' as inputfile.
-
- pcp -g -I message           pcp -g message            use 'message' as inputfile.
-
- pcp -g -I msg -O sig        pcp -g -I msg sig         use 'sig' as outputfile.
-
- pcp -p -O key.pcp           pcp -p key.pcp            use 'key.pcp' as outputfile.
-
- pcp -p -O key.pcp -r Bob    pcp -p -O key.pcp Bob     use 'Bob' as recipient.
-
- pcp -s -O key.pcp           pcp -s key.pcp            use 'key.pcp' as outputfile.
-
- pcp -s -O key.pcp -r Bob    pcp -s -O key.pcp Bob     use 'Bob' as recipient.
-
- pcp -K -I alice.pcp         pcp -K alice.pcp          use 'alice.pcp' as keyfile.
- -

ENVIRONMENT VARIABLES

- +
+ ORIGINAL                    ALTERNATIVE               DESCRIPTION
+
+ pcp -e -I message -r Bob    pcp -e -r Bob message     use 'message' as inputfile.
+                             pcp -e -I message Bob     use 'Bob' as recipient,
+                                                       multiple recipients supported.
+
+ pcp -d -I crypted           pcp -d crypted            use 'crypted' as inputfile.
+
+ pcp -g -I message           pcp -g message            use 'message' as inputfile.
+
+ pcp -g -I msg -O sig        pcp -g -I msg sig         use 'sig' as outputfile.
+
+ pcp -p -O key.pcp           pcp -p key.pcp            use 'key.pcp' as outputfile.
+
+ pcp -p -O key.pcp -r Bob    pcp -p -O key.pcp Bob     use 'Bob' as recipient.
+
+ pcp -s -O key.pcp           pcp -s key.pcp            use 'key.pcp' as outputfile.
+
+ pcp -s -O key.pcp -r Bob    pcp -s -O key.pcp Bob     use 'Bob' as recipient.
+
+ pcp -K -I alice.pcp         pcp -K alice.pcp          use 'alice.pcp' as keyfile.
+

+

+
+

ENVIRONMENT VARIABLES

pcp respects the following environment variables:

-
+
PCP_VAULT
-
PCP_VAULT
- -

Use an alternative vaultfile. The default is ~/.pcpvault and can be overridden with the -V commandline option. If PCP_VAULT is set, this one will be used instead.

- +

Use an alternative vaultfile. The default is ~/.pcpvault and +can be overridden with the -V commandline option. If PCP_VAULT +is set, this one will be used instead.

-
PCP_DEBUG
+
PCP_DEBUG
+
- -

Enable debugging output, where supported. Same as -D.

- +

Enable debugging output, where supported. Same as -D.

- -

EXIT STATUS

- +

+

+
+

EXIT STATUS

Pcp may return one of several error codes if it encounters problems.

+
    +
  1. No problems occurred. +
    2. +
  2. Generic error code. + +
    3. +
+

+

+
+

FILES

+
~/.pcpvault
-
0 No problems occurred.
- -
-
1 Generic error code.
-
- -
-
- -

FILES

- -
- -
~/.pcpvault
-
-

Default vault file where all keys are stored.

-
- -

EXPERIMENTAL STATUS

- -

Currently there are a couple of problems which are unsolved or in the process to be solved.

- +

+

+
+

EXPERIMENTAL STATUS

+

Currently there are a couple of problems which are +unsolved or in the process to be solved.

+
No secure native key exchange for store-and-forward systems
-
No secure native key exchange for store-and-forward systems
- -

Pretty Curved Privacy is a store-and-forward system, it works on files and can't use any cool key exchange protocols therefore. For example there would be CurveCP which guarantees a secure key exchange. But CurveCP cannot be used offline.

- -

Users have to find other means to exchange keys. That's a pity since with Curve25519 you can't just publish your public key to some key server because in order to encrypt a message, both the recipient AND the sender need to have the public key of each other. It would be possible to publish public keys, and attach the senders public key to the encrypted message, but I'm not sure if such an aproach would be secure enough. Pcp implements this scheme though (refer to the option -A).

- +

Pretty Curved Privacy is a store-and-forward system, it works +on files and can't use any cool key exchange protocols therefore. +For example there would be CurveCP which guarantees a +secure key exchange. But CurveCP cannot be used offline.

+

Users have to find other means to exchange keys. That's a pity +since with Curve25519 you can't just publish your public key +to some key server because in order to encrypt a message, both +the recipient AND the sender need to have the public key of +each other. It would be possible to publish public keys, +and attach the senders public key to the encrypted message, but +I'm not sure if such an aproach would be secure enough. Pcp +implements this scheme though (refer to the option -A).

-
Curve25519 not widely adopted
+
Curve25519 not widely adopted
+
- -

At the time of this writing the ECC algorithm Curve25519 is only rarely used, in most cases by experimental software (such as Pretty Curved Privacy). As far as I know there haven't been done the kind of exessive crypto analysis as with other ECC algorithms.

- -

While I, as the author of pcp1 totally trust D.J.Bernstein, this may not be the case for you.

- +

At the time of this writing the ECC algorithm Curve25519 +is only rarely used, in most cases by experimental software +(such as Pretty Curved Privacy). As far as I know there haven't +been done the kind of exessive crypto analysis as with other +ECC algorithms.

+

While I, as the author of pcp1 totally trust D.J.Bernstein, this +may not be the case for you.

-
Unreviewed yet
+
Unreviewed yet
+
- -

As with every crypto software, pcp has to undergo a couple rounds of peer review (analysis) in order to be considered secure, trustable and stable. No any such review has been undertaken on pcp yet.

- -

Pcp is a mere fun project aimed at teaching myself better C coding and crypto. In fact I don't even trust the software myself and I don't use it for anything remotely serious.

- +

As with every crypto software, pcp has to undergo a couple rounds +of peer review (analysis) in order to be considered secure, trustable +and stable. No any such review has been undertaken on pcp yet.

+

Pcp is a mere fun project aimed at teaching myself better C coding +and crypto. In fact I don't even trust the software myself and I +don't use it for anything remotely serious.

- -

In short: don NOT use this software for production purposes!

- -

INTERNALS

- -

PASSPHRASES

- -

Passphrases are used to protect secret data at rest on various instances by pcp, like secret keys or symmetric encrypted data.

- -

Pcp doesn't use the passphrase directly but uses a key derivation function to calculate a secure key from the passphrase: libsodium's crypto_pwhash_scryptsalsa208sha256() function.

- -

In order to properly protect secret keys, pcp measures the entropy of a given passphrase and warns the user about the possible weak passphrase. This measurement is calculated using the Claude E. Shannon method, where a value of 8.0 means maximum available entropy (e.g. truly random 256 chars in no comprehensible order) and 0.0 stands for the worst like passphrases like "aaa" or "x".

- -

Pcp considers passphrases with an entropy measurement of 3.32 or higher as acceptable. This may change in the future.

- -

VAULT FORMAT

- -

The vault file contains all public and secret keys. It's a portable binary file.

- +

In short: don NOT use this software for production purposes!

+

+

+
+

INTERNALS

+

+

+

PASSPHRASES

+

Passphrases are used to protect secret data at rest on various instances +by pcp, like secret keys or symmetric encrypted data.

+

Pcp doesn't use the passphrase directly but uses a key derivation function +to calculate a secure key from the passphrase: libsodium's +crypto_pwhash_scryptsalsa208sha256() function.

+

In order to properly protect secret keys, pcp measures the entropy +of a given passphrase and warns the user about the possible weak +passphrase. This measurement is calculated using the Claude E. Shannon +method, where a value of 8.0 means maximum available entropy (e.g. +truly random 256 chars in no comprehensible order) and 0.0 stands +for the worst like passphrases like "aaa" or "x".

+

Pcp considers passphrases with an entropy measurement of 3.32 or higher +as acceptable. This may change in the future.

+

+

+

VAULT FORMAT

+

The vault file contains all public and secret keys. It's a portable +binary file.

The file starts with a header:

- -
 +-------------------------------------------+
+
+ +-------------------------------------------+
  | Field        Size   Description           |
  +-------------------------------------------+
  | File ID    |    1 | Vault Identifier 0xC4 |
@@ -613,13 +688,12 @@
  | Version    |    4 | Big endian, version   |
  +-------------------------------------------+
  | Checksum   |   32 | SHA256 Checksum       |
- +-------------------------------------------+

-
+ +-------------------------------------------+

The checksum is a checksum of all keys.

- -

The header is followed by the keys. Each key is preceded by a key header which looks like this:

- -
 +--------------------------------------------+
+
The header is followed by the keys. Each key is preceded by a
+key header which looks like this:

+
+ +--------------------------------------------+
  | Field        Size   Description            |
  +--------------------------------------------+
  | Type       |    1 | Key type (S,P,M)       |
@@ -629,21 +703,19 @@
  | Version    |    4 | Big endian, keyversion |
  +--------------------------------------------+
  | Checksum   |   32 | SHA256 Key Checksum    |
- +--------------------------------------------+

-
+ +--------------------------------------------+

Type can be one of:

- -
 PCP_KEY_TYPE_MAINSECRET 0x01
+
+ PCP_KEY_TYPE_MAINSECRET 0x01
  PCP_KEY_TYPE_SECRET     0x02
- PCP_KEY_TYPE_PUBLIC     0x03

-
+ PCP_KEY_TYPE_PUBLIC     0x03

The key header is followed by the actual key, see below.

- -

SECRET KEY FORMAT

- +

+

+

SECRET KEY FORMAT

A secret key is a binary structure with the following format:

- -
 +---------------------------------------------------------+
+
+ +---------------------------------------------------------+
  | Field         Size      Description                     |
  +-------------+--------+----------------------------------+
  | Public      |     32 | Curve25519 Public Key Part       |
@@ -671,205 +743,215 @@
  | Serial      |      4 | Serial Number                    |
  +-------------|--------|----------------------------------+
  | Type        |      1 | Key Type                         |
- +-------------+--------+----------------------------------+

-
+ +-------------+--------+----------------------------------+

Some notes:

- -

The secret key fields will be filled with random data if the key is encrypted. The first byte of it will be set to 0 in that case.

- -

The key id is a computed JEN Hash of the secret and public key concatenated, put into hex, as a string.

- -

The key version is a static value, currently 0x2. If the key format changes in the future, this version number will be increased to distinguish old from new keys.

- -

Exported keys will be encoded in Z85 encoding. When such an exported key is imported, only the actual Z85 encoded data will be used. Header lines and lines starting with whitespace will be ignored. They are only there for convenience.

- +

The secret key fields will be filled with random data if the +key is encrypted. The first byte of it will be set to 0 in that +case.

+

The key id is a computed JEN Hash of the secret and public +key concatenated, put into hex, as a string.

+

The key version is a static value, currently 0x2. If the key +format changes in the future, this version number will be +increased to distinguish old from new keys.

+

Exported keys will be encoded in Z85 encoding. When such an +exported key is imported, only the actual Z85 encoded data +will be used. Header lines and lines starting with whitespace +will be ignored. They are only there for convenience.

Key generation works like this:

-
    - -

  • Generate a random seed (32 bytes).

    - +
  • +

    Generate a random seed (32 bytes).

    • -

  • Generate a ED25519 sigining keypair from that seed.

    - +
  • +

    Generate a ED25519 sigining keypair from that seed.

    • -

  • Generate a random seed (32 bytes).

    - +
  • +

    Generate a random seed (32 bytes).

    • -

  • Generate a Curve25519 encryption keypair from that seed.

    - +
  • +

    Generate a Curve25519 encryption keypair from that seed.

- -

So, while both secrets are stored in the same PCP key, they are otherwise unrelated. If one of them leaks, the other cannot be recalculated from it.

- -

Take a look at the function pcp_keypairs() for details.

- -

PUBLIC KEY EXPORT FORMAT

- -

Exported public and secret keys will be written in a portable way. Pcp uses RFC4880 export format for public keys with some slight modifications:

- -
    - -

  • Key material is native to libsodium/pcp and not specified in the rfc for curve25519/ed25519. Therefore pcp encodes key material doing it like this: mp|sp|cp

    - +

    So, while both secrets are stored in the same PCP key, they +are otherwise unrelated. If one of them leaks, the other +cannot be recalculated from it.

    +

    Take a look at the function pcp_keypairs() for details.

    +

    +

    +

    PUBLIC KEY EXPORT FORMAT

    +

    Exported public and secret keys will be written in a portable +way. Pcp uses RFC4880 export format for public keys with some +slight modifications:

    +
    +
    +
    +

    Key material is native to libsodium/pcp and not specified in the +rfc for curve25519/ed25519. Therefore pcp encodes key material doing it like +this: mp|sp|cp

    where

    - -
     mp = master keysigning public key (ed25519), 32 bytes
+
    + mp = master keysigning public key (ed25519), 32 bytes
  sp = signing public key (ed25519), 32 bytes
- cp = encryption public key (curve25519), 32 bytes
    
-
-
    • -

  • The various cipher (algorithm) id's are unspecified for libsodium/pcp native ciphers. Therefore they are proprietary to pcp, starting at 33 (22 is the last officially assigned one). Once those cipher numbers become official, they will be used instead.

    - -
    • -

  • Pcp uses 64 bit integers for timestamps everywhere (ctime, expire, etc), to be year 2038 safe. Note, that this is a violation of the RFC spec. However, said RFC have to be modified to fit 2038 (and beyond) anyways. This applies for the keyfile ctime as well for the key sig sub fields containing time values.

    - -
    • -

  • The exported public key packet contains a signature. Pcp is filling out all required fields. A signature has a variable number of sig sub packets. Pcp uses only these types:

    - -
      2 = Signature Creation Time     (8 byte)
+ cp = encryption public key (curve25519), 32 bytes
    + +
    +
    +

    The various cipher (algorithm) id's are unspecified for +libsodium/pcp native ciphers. Therefore they are proprietary to pcp, starting at +33 (22 is the last officially assigned one). Once +those cipher numbers become official, they will be used instead.

    +
    +
    +
    +

    Pcp uses 64 bit integers for timestamps everywhere (ctime, expire, etc), +to be year 2038 safe. Note, that this is a violation of the +RFC spec. However, said RFC have to be modified to fit 2038 +(and beyond) anyways. This applies for the keyfile ctime as +well for the key sig sub fields containing time values.

    +
    +
    +
    +

    The exported public key packet contains a signature. Pcp is +filling out all required fields. A signature has a variable +number of sig sub packets. Pcp uses only these types:

    +
    +  2 = Signature Creation Time     (8 byte)
   3 = Signature Expiration Time   (8 byte)
   9 = Key Expiration Time         (8 bytes)
  20 = Notation Data               (4 byte flags, N bytes name+value)
- 27 = Key Flags                   (1 byte, use 0x02, 0x08 and 0x80
    - -
    • -

  • Pcp uses 3 notation fields:

    - + 27 = Key Flags (1 byte, use 0x02, 0x08 and 0x80 + +
    +
    +

    Pcp uses 3 notation fields:

    +
    "owner", which contains the owner name, if set
    -
    "owner", which contains the owner name, if set
    -
    +
    "mail", which contains the emailaddress, if set
    +
    "serial", which contains the 32bit serial number
    + +
    -
    "mail", which contains the emailaddress, if set
    +
    - +

    The actual signature field consists of the blake2 hash of +(mp|sp|cp|keysig) followed by the nacl signature. However, pcp +does not put an extra 16 byte value of the hash, since the nacl +signature already contains the full hash. So, an implementation +could simply pull the fist 16 bytes of said hash to get +the same result if desired.

    -
    "serial", which contains the 32bit serial number
    +
    - +

    The mp keypair will be used for signing. The recipient can +verify the signature, since mp is included.

    +
    +
    +
    +

    While pcp puts expiration dates for the key and the signature +into the export as the rfc demands, it mostly ignores them (yet). +Key expiring is not implemented in PCP yet.

    +
    +
    +
    +

    We use big-endian always.

    +
    +
    +
    +

    Unlike RC4880 public key exports, pcp uses Z85 encoding if +armoring have been requested by the user. Armored output has +a header and a footer line, however they are ignored by the +parser and are therefore optional. Newlines, if present, are +optional as well.

    +

    http://tools.ietf.org/html/rfc4880#section-5.2.3

    +
    +
    +
    +

    The key sig blob will be saved in the Vault unaltered during +import, so pcp is able to verify the signature at will anytime. When exporting +a foreign public key, pcp just puts out that key sig blob to the +export untouched.

    +
    +
    +
    +

    Currently PCP only supports self-signed public key exports.

    +
    +
    +
    +

    Pcp only supports one key signature per key. However, it would be easily +possible to support foreign keysigs as well in the future.

    - -
    • -

  • The actual signature field consists of the blake2 hash of (mp|sp|cp|keysig) followed by the nacl signature. However, pcp does not put an extra 16 byte value of the hash, since the nacl signature already contains the full hash. So, an implementation could simply pull the fist 16 bytes of said hash to get the same result if desired.

    - -
    • -

  • The mp keypair will be used for signing. The recipient can verify the signature, since mp is included.

    - -
    • -

  • While pcp puts expiration dates for the key and the signature into the export as the rfc demands, it mostly ignores them (yet). Key expiring is not implemented in PCP yet.

    - -
    • -

  • We use big-endian always.

    - -
    • -

  • Unlike RC4880 public key exports, pcp uses Z85 encoding if armoring have been requested by the user. Armored output has a header and a footer line, however they are ignored by the parser and are therefore optional. Newlines, if present, are optional as well.

    - -

    http://tools.ietf.org/html/rfc4880#section-5.2.3

    - -
    • -

  • The key sig blob will be saved in the Vault unaltered during import, so pcp is able to verify the signature at will anytime. When exporting a foreign public key, pcp just puts out that key sig blob to the export untouched.

    - -
    • -

  • Currently PCP only supports self-signed public key exports.

    - -
    • -

  • Pcp only supports one key signature per key. However, it would be easily possible to support foreign keysigs as well in the future.

    - -
    • -
-

So, a full pubkey export looks like this

- -
    version
+
+    version
     ctime
     cipher
     3 x raw keys             \
     sigheader                 > calculate hash from this
        sigsubs (header+data) /
     hash
-    signature

-
-
SECRET KEY EXPORT FORMAT

-
+    signature
+

+

+

SECRET KEY EXPORT FORMAT

Secret keys are exported in a proprietary format.

- -

The exported binary blob is symmetrically encrypted using the NACL function crypto_secret(). The passphrase will be used to derive an encryption key using the STAR function scrypt().

- +

The exported binary blob is symmetrically encrypted using the NACL +function crypto_secret(). The passphrase will be used to derive an +encryption key using the STAR function scrypt().

The binary data before encryption consists of:

- -
 ED25519 master signing secret
+
+ ED25519 master signing secret
  Curve25519 encryption secret
  ED25519 signing secret
  ED25519 master signing public
  Curve25519 encryption public
  ED25519 signing public
- Optional notations, currently supported are the 'owner' and 'mail' attributes.
+ Optional notations, currently supported are the 'owner' and 'mail' attributes.
   If an attribute is empty, the len field is zero.
   -# len(VAL) (2 byte uint)
   -# VAL (string without trailing zero)
  8 byte creation time (epoch)
  4 byte key version
- 4 byte serial number

+ 4 byte serial number
+

The encrypted cipher will be prepended with the random nonce used +to encrypt the data and looks after encryption as such:

+
+  Nonce | Cipher
+

+

+

ENCRYPTED OUTPUT FORMAT

+

The encryption protocol used by PCP uses mostly standard +libsodium facilities with the exception that PCP uses counter +mode (CTR-Mode) for stream encryption.

+
+ Detailed description:
+
+
generate a random ephemeral 32 byte key S
-

The encrypted cipher will be prepended with the random nonce used to encrypt the data and looks after encryption as such:

+
encrypt it asymetrically for each recipient using a unique nonce (R)
-
  Nonce | Cipher
- -

ENCRYPTED OUTPUT FORMAT

- -

The encryption protocol used by PCP uses mostly standard libsodium facilities with the exception that PCP uses counter mode (CTR-Mode) for stream encryption.

- -
 Detailed description:
+
encrypt the input file 32k blockwise using the ephemeral key
+
for each input block with a size of 32k bytes:
-
generate a random ephemeral 32 byte key S
-
+
generate a random nonce N
- -
encrypt it asymetrically for each recipient using a unique nonce (R)
-
+
put the current counter size into the first byte of the nonce
- -
encrypt the input file 32k blockwise using the ephemeral key
-
+
put the current counter (starting with 1) into the following byte(s), if larger than 1 byte, in big endian mode
-
- -
for each input block with a size of 32k bytes:
-
- -
-
generate a random nonce N
-
- -
-
put the current counter size into the first byte of the nonce
-
- -
-
put the current counter (starting with 1) into the following byte(s), if larger than 1 byte, in big endian mode
-
- -
-
encrypt the 32k block using crypto_secretbox() with the nonce N and the ephemeral key S
-
+
encrypt the 32k block using crypto_secretbox() with the nonce N and the ephemeral key S
+
- - -
-

Symetric encryption works the very same without the recipient stuff.

-

Formal format description, asymetric encrypted files:

- -
 +-----------------------------------------------------------+
+
+ +-----------------------------------------------------------+
  | Field         Size      Description                       |
  +-------------+--------+------------------------------------+
  | Type        |      1 | Filetype, 5=ASYM, 23=SYM, 6=ANON   |
@@ -881,41 +963,45 @@
  | Recipients *|   R*72 | C(recipient)|C(recipient)... (*)   |
  +-------------|--------|------------------------------------+
  | Encrypted   |      ~ | The actual encrypted data          |
- +-------------|--------|------------------------------------+

-
+ +-------------|--------|------------------------------------+

*) not included when doing symetric encryption.

-

Recipient field format:

- -
 +---------------------------------------------------------+
+
+ +---------------------------------------------------------+
  | Field         Size      Description                     |
  +-------------+--------+----------------------------------+
  | Nonce       |     24 | Random Nonce, one per R          |
  +-------------|--------|----------------------------------+
  | Cipher      |     48 | S encrypted with PK or R         |
- +-------------|--------|----------------------------------+

-
-
R is generated using crypto_box() with the senders secret key, the recipients public key and a random nonce.

-
+ +-------------|--------|----------------------------------+
+

R is generated using crypto_box() with the senders +secret key, the recipients public key and a random nonce.

Pseudocode:

- -
 R = foreach P: N | crypto_box(S, N, P, SK)
+
+ 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.

-
-
If using anonymous encryption, the sender generates a ephemeral key pair, uses the secret part of it to generate R. The public part will be included with the output (right after the file type. In this mode a recipient is not required to have the public key of the sender.

-
-
The encrypted output maybe Z85 encoded. In this case the Z85 encoding will be done blockwise with blocks of 16k bytes. The decoded content inside will be as described above.

-
-
SIGNATURE FORMAT

-
-
There are different signature formats. Standard binary NACL signatures have the following format:

-
-
 +---------------------------------------------------------+
+ 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.

+
If using anonymous encryption, the sender generates a ephemeral
+key pair, uses the secret part of it to generate R. The public
+part will be included with the output (right after the file type.
+In this mode a recipient is not required to have the public key
+of the sender.

+
The encrypted output maybe Z85 encoded. In this case the Z85
+encoding will be done blockwise with blocks of 16k bytes. The
+decoded content inside will be as described above.

+

+

+
SIGNATURE FORMAT

+
There are different signature formats. Standard binary NACL
+signatures have the following format:

+
+ +---------------------------------------------------------+
  | Field         Size      Description                     |
  +-------------+--------+----------------------------------+
  | Content     |      ~ | Original file content            |
@@ -925,20 +1011,19 @@
  | 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 BLAKE2 hash of the content.

-
+ +-------------|--------|----------------------------------+
+

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.

- +
+ 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 -----
+
+ ----- BEGIN ED25519 SIGNED MESSAGE -----
  Hash: Blake2
  
  MESSAGE
@@ -949,19 +1034,25 @@
  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).

-
-
SIGNED ENCRYPTION FORMAT

-
-
Signed encrypted files are in binary form only. The first part is the standard encrypted file as described in ENCRYPTED OUTPUT FORMAT followed by the binary encrypted signature described in SIGNATURE FORMAT without the offset separator.

-
-
However, not only the hash of the file content will be signed but the recipient list described in 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.

-
+ ------ END ED25519 SIGNATURE ------
+

The Z85 encoded signature at the end contains the same signature +contents as the binary signature outlined above (hash+sig).

+

+

+

SIGNED ENCRYPTION FORMAT

+

Signed encrypted files are in binary form only. The first part is +the standard encrypted file as described in ENCRYPTED OUTPUT FORMAT +followed by the binary encrypted signature described in SIGNATURE FORMAT +without the offset separator.

+

However, not only the hash of the file content will be signed but the +recipient list described in 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         |
@@ -973,148 +1064,146 @@
  | 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.

-
+ +-------------|--------|----------------------------------+
+

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 ENCRYPTED OUTPUT FORMAT).

-
+ +-------------|--------|----------------------------------+
+

where R is: C(recipient)|C(recipient)... (see 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.

- -

Z85 ENCODING

- -

pcp1 uses Z85 to encode binary data (if requested with -z) such as encrypted data, exported keys or armored signatures.

- -

Encoded data is always enclosed by a header and a footer and may have any number of comments. Example:

- -
 ----- PCP ENCRYPTED FILE -----
+
+ 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.

+

+

+
Z85 ENCODING

+
pcp1 uses Z85 to encode binary data (if requested with -z) such
+as encrypted data, exported keys or armored signatures.

+
Encoded data is always enclosed by a header and a footer and may have any number
+of comments. Example:

+
+ ----- PCP ENCRYPTED FILE -----
  Version: PCP 0.2.1
  246ge]+yn={<I&&Z%(pm[09lc5[dx4TZALi/6cjVe)Kx5S}7>}]Xi3*N3Xx34Y^0rz:r.5j
  v#6Sh/m3XKwy?VlA+h8ks]9:kVj{D[fd7]NA]T-(ne+xo!W5X5-gIUWqM
- ----- END PCP ENCRYPTED FILE -----

-
-
However, the parser tries to be as tolerant as possible. It also accepts Z85 encoded data without headers or without newlines, empty lines or lines containing a space are ignored as well as comments. Empty comments are not allowed.

-
-
Z85 PADDING

-
-
PCP uses a custom padding scheme. Z85 input data size must be a multiple of 4. To fulfill this requirement, PCP padds the input with zeros as neccessary. To tell the decoder if padding took place and how much zeros have been added, PCP adds another 4 bytes after each Z85 encoded block, from the last one which contains the number of zeros used for padding, even if the input hasn't been padded.

-
-
Z85 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 ASCII85 with a couple of modifications (portability, readability etc).

-
-
To fulfil the requirements of the ZeroMQ Z85 functions, pcp1 does some additional preparations of raw input before actually doing the encoding, since the input for zmq_z85_encode() must be divisible by 4. Therefore we pad the input with zeroes and remove them after decoding.

-
-
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.

-
-
Z85 encoding and decoding can be used separately as well to work with files. Examples:

-
+ ----- END PCP ENCRYPTED FILE -----
+

However, the parser tries to be as tolerant as possible. It also accepts +Z85 encoded data without headers or without newlines, empty lines or lines +containing a space are ignored as well as comments. Empty comments are not +allowed.

+

+

+

Z85 PADDING

+

PCP uses a custom padding scheme. Z85 input data size must be a multiple +of 4. To fulfill this requirement, PCP padds the input with zeros as +neccessary. To tell the decoder if padding took place and how much zeros +have been added, PCP adds another 4 bytes after each Z85 encoded block, +from the last one which contains the number of zeros used for padding, +even if the input hasn't been padded.

+

+

+

Z85 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 ASCII85 with +a couple of modifications (portability, readability etc).

+

To fulfil the requirements of the ZeroMQ Z85 functions, pcp1 +does some additional preparations of raw input before actually doing the +encoding, since the input for zmq_z85_encode() must be divisible by 4. Therefore +we pad the input with zeroes and remove them after decoding.

+

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.

+

Z85 encoding and decoding can be used separately as well to work with +files. Examples:

Encode some file to Z85 encoding:

-

pcp1 -z -I file -O file.z85

-

Reverse the process:

-

pcp1 -Z -I file.z85 -O file

- -

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. However, it is possible to export and import pbp keys from/to pcp.

- -

JSON ENCODING SUPPORT

- -

If pcp have been compiled with --with-json (which requires the libjansson library), then it supports JSON objects as input and output with the following functions:

- +

+

+

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. However, it is possible to export and +import pbp keys from/to pcp.

+

+

+
+

JSON ENCODING SUPPORT

+

If pcp have been compiled with --with-json (which requires the libjansson +library), then it supports JSON objects as input and output with the following +functions:

+
public key export
-
public key export
-
+
secret key export
- -
secret key export
-
+
whole vault export
- -
whole vault export
-
+
public key import
- -
public key import
-
+
secret key import
- -
secret key import
-
- -
- -

JSON support can be used either with the commandline tool pcp1 or programmatically using the C, C++ or Python API.

- -

USING JSON FROM THE C API

- -

In order to use JSON all you've got to do is to switch a context flag:

- -
 PCPCTX *ptx = ptx_new();
- ptx->json = 1;
- -

That all to it. Now any function normally used for key import and export works with JSON, just fill the Buffer object with a JSON string for imports or fetch the Buffer content of an export function as a string.

- -

USING JSON FROM THE COMMANDLINE

- -

In order to use JSON on the commandline, add -j. This can be used in conjunction with the following options:

- +

JSON support can be used either with the commandline tool pcp1 or programmatically +using the C, C++ or Python API.

+

+

+

USING JSON FROM THE C API

+

In order to use JSON all you've got to do is to switch a context flag:

+
+ PCPCTX *ptx = ptx_new();
+ ptx->json = 1;
+

That all to it. Now any function normally used for key import and export works +with JSON, just fill the Buffer object with a JSON string for imports or +fetch the Buffer content of an export function as a string.

+

+

+

USING JSON FROM THE COMMANDLINE

+

In order to use JSON on the commandline, add -j. This can be used in +conjunction with the following options:

+
-p
-
-p
-

Public key export.

-
-
-s
-
+
-s
+

Secret key export.

-
-
-K
-
+
-K
+

Public and secret key import.

-
-
-t
+
-t
+
-

Text view mode (aka inspect mode).

-
- -

The -z and -Z options are ignored in JSON mode.

- -

JSON OBJECT STRUCTURE

- -

JSON PUBLIC KEY (pcp1 -p -j)

- +

The -z and -Z options are ignored in JSON mode.

+

+

+

JSON OBJECT STRUCTURE

+

+

+

JSON PUBLIC KEY (pcp1 -p -j)

The JSON object for a public key looks like this:

- -
 {
+
+ {
     "id": "6BF2980419E0986A",
     "owner": "tom",
     "mail": "tom@local",
@@ -1128,19 +1217,16 @@
     "sigpub": "6980b76e17170194626b49cbab1ab35369a0635f52fe1a7cf39cc5421fb5c0c2",
     "masterpub": "947a49f29e9cb0e92b61e2a1dea95f8ec81a24baed78e85c1b52cc3714f5e45e",
     "signature": "947a49f29e9cb0e92b61e2a1dea95f8ec81a24baed78e85c1b52cc3714f5e45[..]"
- }

-
-
Actually the field signature contains the whole encoded public key.

-
+ }
+

Actually the field signature contains the whole encoded public key.

Fields containing byte arrays are hex encoded.

-

Numbers are represented as literal integers.

- -

JSON SECRET KEY (pcp1 -s -j)

- +

+

+

JSON SECRET KEY (pcp1 -s -j)

The JSON object for a public key looks like this:

- -
 {
+
+ {
     "id": "6BF2980419E0986A",
     "owner": "tom",
     "mail": "tom@local",
@@ -1155,94 +1241,99 @@
     "masterpub": "947a49f29e9cb0e92b61e2a1dea95f8ec81a24baed78e85c1b52cc3714f5e45e",
     "secrets": "ad5ce150f3cd7bffa299d4db5bf3d26ae56c3808ccba7[..]",
     "nonce": "858ef9870fc8f39903cfb281d697ca29a935d2ae929fa4ea"
-}

-
-
As you can see that's pretty identical to a public key json object beside the secrets and nonce fields. The secrets field contains the encrypted secret key material. Pcp does not support exporting a secret key unencrypted.

-
-
The nonce is required for a later import and shall not be changed or decoupled from secrets. This may change in the future.

-
-
JSON VAULT (pcp1 -t)

-
+}
+

As you can see that's pretty identical to a public key json object beside the +secrets and nonce fields. The secrets field contains the encrypted +secret key material. Pcp does not support exporting a secret key unencrypted.

+

The nonce is required for a later import and shall not be changed or +decoupled from secrets. This may change in the future.

+

+

+

JSON VAULT (pcp1 -t)

The JSON object for the vault looks like this:

- -
  {
+
+  {
     "keyvaultfile": "/home/tom/.pcpvault",
     "version": 2,
     "checksum": "27b583dc2dacf5ccc874b7be3a39748d107c6b9e9f9d473f1c716a94561ef793",
     "secretkeys": 1,
     "publickey": 3,
     "keys": []
- }

-
-
The field keys is an array containing one or more of the already described key objects.

-
-
JSON PROGRAM OUTPUT

-
-
Currently pcp does not support JSON program output, that is, success or error messages on STDERR are not encoded as json. This may change in the future.

-
-
COPYRIGHT

-
+ }
+

The field keys is an array containing one or more of the already +described key objects.

+

+

+

JSON PROGRAM OUTPUT

+

Currently pcp does not support JSON program output, that is, success or +error messages on STDERR are not encoded as json. This may change in the future.

+

+

+
+

COPYRIGHT

Copyright (c) 2013-2015 by T.v.Dein <tom AT vondein DOT org>

- -

ADDITIONAL COPYRIGHTS

- +

+

+
+

ADDITIONAL COPYRIGHTS

+
ZeroMQ Z85 encoding routine
-
ZeroMQ Z85 encoding routine
- -
 Copyright (c) 2007-2013 iMatix Corporation
+
+ Copyright (c) 2007-2013 iMatix Corporation
  Copyright (c) 2009-2011 250bpm s.r.o.
  Copyright (c) 2010-2011 Miru Limited
  Copyright (c) 2011 VMware, Inc.
- Copyright (c) 2012 Spotify AB

-
+ Copyright (c) 2012 Spotify AB
-
Tarsnap readpass helpers
+
Tarsnap readpass helpers
+
- -
 Copyright 2009 Colin Percival
- +
+ Copyright 2009 Colin Percival
-
jen_hash() hash algorithm
+
jen_hash() hash algorithm
+
- -
 Bob Jenkins, Public Domain.
- +
+ Bob Jenkins, Public Domain.
-
UTHASH hashing macros
+
UTHASH hashing macros
+
- -
 Copyright (c) 2003-2013, Troy D. Hanson
- +
+ Copyright (c) 2003-2013, Troy D. Hanson
-
Random art image from OpenSSH keygen
+
Random art image from OpenSSH keygen
+
- -
 Copyright (c) 2000, 2001 Markus Friedl.  All rights reserved.
-
- Comitted by Alexander von Gernler in rev 1.7.
- +
+ Copyright (c) 2000, 2001 Markus Friedl.  All rights reserved.
+
+ Comitted by Alexander von Gernler in rev 1.7.
- -

Every incorporated source code is opensource and licensed under the GPL as well.

- -

AUTHORS

- -

T.v.Dein <tom AT vondein DOT org>

- -

LICENSE

- -

Licensed under the GNU GENERAL PUBLIC LICENSE version 3.

- -

HOME

- -

The homepage of Pretty Curved Privacy can be found on http://www.daemon.de/PrettyCurvedPrivacy. The source is on Github: https://github.com/TLINDEN/pcp

- +

Every incorporated source code is opensource and licensed +under the GPL as well.

+

+

+
+

AUTHORS

+

T.v.Dein <tom AT vondein DOT org>

+

+

+
+

LICENSE

+

Licensed under the GNU GENERAL PUBLIC LICENSE version 3.

+

+

+
+

HOME

+

The homepage of Pretty Curved Privacy can be found on +http://www.daemon.de/PrettyCurvedPrivacy. The source is +on Github: https://github.com/TLINDEN/pcp

- -