names after -C like "pcp1 -C -- file1 file2 file3".
</code></pre>
<h1id="DESCRIPTION">DESCRIPTION</h1>
<p><b>Pretty Curved Privacy</b> (pcp1) is a commandline utility which can be used to encrypt files. <b>pcp1</b> 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.</p>
<p><b>Caution</b>: since CURVE25519 is no accepted standard, <b>pcp1</b> has to be considered as experimental software. In fact, I wrote it just to learn about the curve and see how it works.</p>
<p>Beside some differences it works like <b>GNUPG</b>. So, if you already know how to use gpg, you'll feel almost home.</p>
<h1id="QUICKSTART">QUICKSTART</h1>
<p>Lets say, Alicia and Bobby want to exchange encrypted messages. Here's what the've got to do.</p>
<p>After entering their name, email address and a passphrase to protect the key, it will be stored in their <b>vault file</b> (by default ~/.pcpvault).</p>
<p>Now, both of them have to export the public key, which has to be imported by the other one. With <b>pcp</b> 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:</p>
<p>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:</p>
<p>Please note the big difference to <b>GPG</b> 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.</p>
<p>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.</p>
<h1id="FILES-AND-PIPES">FILES AND PIPES</h1>
<p>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:</p>
<pre><code> pcp1 -e -O output</code></pre>
<p>will read the text to be encrypted from standard input, because <b>-I</b> has not been specified. It works the same with <b>-O</b>:</p>
<p>here we encrypt a file symmetrically without downloading it from a remote ssh server and sending the encrypted result via email to someone.</p>
<p>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 <b>-X</b> (<b>--password-file</b>) has been used and is set to <b>-</b>, 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 <b>-X -</b>, and vice versa. IF you use <b>-X -</b> 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.</p>
<h1id="PCP1-KEYS">PCP1 KEYS</h1>
<p><b>pcp1</b> keys are stored in a binary file, called <b>the vault</b>. It's by default located in <b>~/.pcpvault</b> but you can of course specify another location using the <b>-V</b> option.</p>
<p>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.</p>
<p>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.</p>
<p>Each key can be identified using its <b>keyid</b> which looks like this:</p>
<pre><code> 0xD49119E85266509F</code></pre>
<p>A public key exported from a secret key will have the same keyid as the secret key.</p>
<p>If you just want to know details about a key or the vault, use the <b>-t</b> option.</p>
<p>In this mode, which is the default, a public key as specified with <b>-i</b> or <b>-r</b> and your primary secret key will be used for encryption.</p>
<pre><code> pcp1 -r -r Bobby -A -I message.txt -O message.asc</code></pre>
<p>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.</p>
<p>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().</p>
<p>PCP doesn't validate the security of the passphrase.</p>
<p>Self mode can be explicitly enforced with <b>-m</b>.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>Use an alternative vaultfile. The default is <b>~/.pcpvault</b> and can be overridden with the <b>-V</b> commandline option. If PCP_VAULT is set, this one will be used instead.</p>
<p>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 <b>CurveCP</b> which guarantees a secure key exchange. But CurveCP cannot be used offline.</p>
<p>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).</p>
<dtid="Curve25519-not-widely-adopted"><b>Curve25519 not widely adopted</b></dt>
<dd>
<p>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.</p>
<p>While I, as the author of pcp1 totally trust D.J.Bernstein, this may not be the case for you.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>The key id is a computed JEN Hash of the secret and public key concatenated, put into hex, as a string.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>Take a look at the function <b>pcp_keypairs()</b> for details.</p>
<p>Exported public and secret keys will be written in a portable way. Pcp uses RFC4880 export format for public keys with some slight modifications:</p>
<ul>
<li><p>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</p>
cp = encryption public key (curve25519), 32 bytes</code></pre>
</li>
<li><p>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.</p>
</li>
<li><p>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.</p>
</li>
<li><p>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:</p>
<li><p>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.</p>
</li>
<li><p>The mp keypair will be used for signing. The recipient can verify the signature, since mp is included.</p>
</li>
<li><p>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.</p>
</li>
<li><p>We use big-endian always.</p>
</li>
<li><p>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.</p>
<li><p>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.</p>
</li>
<li><p>Currently PCP only supports self-signed public key exports.</p>
</li>
<li><p>Pcp only supports one key signature per key. However, it would be easily possible to support foreign keysigs as well in the future.</p>
<p>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().</p>
<p>The encryption protocol used by PCP uses mostly standard libsodium facilities with the exception that PCP uses counter mode (CTR-Mode) for stream encryption.</p>
<dtid="encrypt-it-asymetrically-for-each-recipient-using-a-unique-nonce-R">encrypt it asymetrically for each recipient using a unique nonce (<b>R</b>)</dt>
<dd>
</dd>
<dtid="encrypt-the-input-file-32k-blockwise-using-the-ephemeral-key">encrypt the input file 32k blockwise using the ephemeral key</dt>
<dtid="put-the-current-counter-starting-with-1-into-the-following-byte-s-if-larger-than-1-byte-in-big-endian-mode">put the current counter (starting with 1) into the following byte(s), if larger than 1 byte, in big endian mode</dt>
<dtid="encrypt-the-32k-block-using-crypto_secretbox-with-the-nonce-N-and-the-ephemeral-key-S">encrypt the 32k block using <b>crypto_secretbox()</b> with the nonce <b>N</b> and the ephemeral key <b>S</b></dt>
foreach I: write (N | crypto_secret_box(I, N, S))</code></pre>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<h2id="SIGNATURE-FORMAT">SIGNATURE FORMAT</h2>
<p>There are different signature formats. Standard binary NACL signatures have the following format:</p>
<p>Signed encrypted files are in binary form only. The first part is the standard encrypted file as described in <b>ENCRYPTED OUTPUT FORMAT</b> followed by the binary encrypted signature described in <b>SIGNATURE FORMAT</b> without the offset separator.</p>
<p>However, not only the hash of the file content will be signed but the recipient list described in <b>ENCRYPTED OUTPUT FORMAT</b> as well. A valid recipient is therefore not able to re-encrypt the decrypted message, append the original signature and send it to other recipients. The signature would not match since the recipient list differs and so recipients know that the signature is forged.</p>
<p>As usual the encrypted signature consists of a nonce and the actual cipher, which is computed symmetrically (see above) from the following clear signature.</p>
<p>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.</p>
<h3id="Z85-PADDING">Z85 PADDING</h3>
<p>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.</p>
<h3id="Z85-BACKGROUND">Z85 BACKGROUND</h3>
<p>The Z85 encoding format is described here: <b>http://rfc.zeromq.org/spec:32</b>. It's part of ZeroMQ (<b>http://zeromq.org</b>). Z85 is based on ASCII85 with a couple of modifications (portability, readability etc).</p>
<p>To fulfil the requirements of the ZeroMQ Z85 functions, <b>pcp1</b> 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.</p>
<p><b>Trying to use another tool to decode an Z85 encoded string produced by z85, might not work therefore, unless the tool takes the padding scheme outlined above into account</b>.</p>
<p>Z85 encoding and decoding can be used separately as well to work with files. Examples:</p>
<p>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.</p>
<p>If pcp have been compiled with <b>--with-json</b> (which requires the libjansson library), then it supports JSON objects as input and output with the following functions:</p>
<p>JSON support can be used either with the commandline tool <b>pcp1</b> or programmatically using the C, C++ or Python API.</p>
<h2id="USING-JSON-FROM-THE-C-API">USING JSON FROM THE C API</h2>
<p>In order to use JSON all you've got to do is to switch a context flag:</p>
<pre><code> PCPCTX *ptx = ptx_new();
ptx->json = 1;</code></pre>
<p>That all to it. Now any function normally used for key import and export works with JSON, just fill the <b>Buffer</b> object with a JSON string for imports or fetch the Buffer content of an export function as a string.</p>
<h2id="USING-JSON-FROM-THE-COMMANDLINE">USING JSON FROM THE COMMANDLINE</h2>
<p>In order to use JSON on the commandline, add <b>-j</b>. This can be used in conjunction with the following options:</p>
<p>As you can see that's pretty identical to a public key json object beside the <b>secrets</b> and <b>nonce</b> fields. The <b>secrets</b> field contains the encrypted secret key material. Pcp does not support exporting a secret key unencrypted.</p>
<p>The <b>nonce</b> is required for a later import and shall not be changed or decoupled from <b>secrets</b>. This may change in the future.</p>
<p>The field <b>keys</b> is an array containing one or more of the already described key objects.</p>
<h3id="JSON-PROGRAM-OUTPUT">JSON PROGRAM OUTPUT</h3>
<p>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.</p>
<p>Every incorporated source code is opensource and licensed under the <b>GPL</b> as well.</p>
<h1id="AUTHORS">AUTHORS</h1>
<p><i>T.v.Dein <tom AT vondein DOT org</i>></p>
<h1id="LICENSE">LICENSE</h1>
<p>Licensed under the GNU GENERAL PUBLIC LICENSE version 3.</p>
<h1id="HOME">HOME</h1>
<p>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</p>
