pcp/man/details.pod

# -*-perl-*-

=head1 PCP1 KEYS

B<pcp1> keys are stored in a binary file, called B<the vault>.
It's by default located in B<~/.pcpvault> but you can of course
specify another location using the B<-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 B<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
B<-t> option.

=head1 ENCRYPTION

There are 2 modes of encryption available in pcp1:

=over

=item B<Standard public key encryption>

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

Example command:

 pcp1 -e -i 0x2BD734B15CE2722D -I message.txt -O message.asc

Here we didn't specify a recipient. Therefore the public
key given with -i will be used directly.

Another example:

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

=item B<Self encryption mode>

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 -i or -r and therefore pcp1
operates in self mode for encryption. It will ask you for a passphrase
to protect the encryption key.

=back

=head1 SIGNATURES

There are 3 modes for digital signatures available on pcp1:

=over

=item B<Standard NACL binary signatures>

In this mode, which is the default, an ED25519 signature will
be calculated from a BLAKE2 hash of the input file content. Both
the original file content plus the signature will be written to
the output file.

Example:

 pcp1 -g -I message.txt -O message.asc -g

You will be asked for the passphrase to access your primary
secret key. The output file will be a binary file.

=item B<Armored NACL signatures>

While this mode does the very same calculations, the output
slightly differs. The output file will be marked as a signature
file, the signature itself will be appended with its own headers
and Z85 encoded.


Example:

 pcp1 -g -I message.txt -O message.asc -g -z

You will be asked for the passphrase to access your primary
secret key. The output file will be a text file.

=item B<Detached NACL signatures>

In some cases you will need to have the signature separated
from the original input file, e.g. to sign download files. You
can generate detached signatures for such purposes. Still, the
signature will be calculated the same way as in standard signatures
but put out into a separate file. A detached signature file will always
be Z85 encoded.

Example:

 pcp1 -g -I message.txt -O -g --sigfile message.sig

Verification by recipient:

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

=back

=head1 SIGNED ENCRYPTION

Beside pure encryption and signatures pcp1 also supports signed
encryption. In this mode an input file will be encrypted and
a signature using your primary secret key from a BLAKE2 hash of
the file contents will be appended to it.

Example:

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

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

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

Please note the additional B<-c> parameter.

If decryption works, the output file will be written. If signature
verification fails you will be informed, but the decrypted
output will be left untouched. It is up to you how to react
on an invalid signature.

B<Caution: as of this writing (pcp version 0.2.0) there is
no offset marker included into the output which separates
the signature from the cipher. Therefore a recipient has to
know that the file is encrypted AND signed. If, for example,
the recpient leaves the -c parameter on such a file, the decryption
process will fail. Otherwise, if the user supplies -c on an
encrypted file without a signature, decryption will fail as well.>

Note: this behavior might change in the future.

=head1 VULNERABILITIES

Currently there are a couple of problems which are not
addressed. These are usually protocol problems, which are
not caused by pcp1.

=over

=item B<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 B<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.

=item B<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.

In short, I'd suggest not to use it on critical systems yet.

=back

=head1 INTERNALS

=head2 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 |
 +-------------------------------------------+
 | 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:

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

Type can be one of:

 PCP_KEY_TYPE_MAINSECRET 0x01
 PCP_KEY_TYPE_SECRET     0x02
 PCP_KEY_TYPE_PUBLIC     0x03

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

=head2 SECRET KEY FORMAT

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


 +---------------------------------------------------------+
 | Field         Size      Description                     |
 +-------------+--------+----------------------------------+
 | Public      |     32 | Curve25519 Public Key Part       |
 +-------------|--------|----------------------------------+
 | Secret      |     32 | Curve25519 Secret Key Unencrypted|
 +-------------|--------|----------------------------------+
 | ED25519 Pub |     32 | ED25519 Public Key Part          |
 +-------------|--------|----------------------------------+
 | ED25519 Sec |     64 | ED25519 Secret Key Unencrypted   |
 +-------------|--------|----------------------------------+
 | Nonce       |     24 | Nonce for secret key encryption  |
 +-------------|--------|----------------------------------+
 | Encrypted   |     48 | Encrypted Curve25519 Secret Key  |
 +-------------|--------|----------------------------------+
 | Owner       |    255 | String, Name of Owner            |
 +-------------|--------|----------------------------------+
 | Mail        |    255 | String, Email Address            |
 +-------------|--------|----------------------------------+
 | ID          |     17 | String, Key ID                   |
 +-------------|--------|----------------------------------+
 | Ctime       |      4 | Creation time, sec since epoch   |
 +-------------|--------|----------------------------------+
 | Version     |      4 | Key version                      |
 +-------------|--------|----------------------------------+
 | 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.

Key generation works like this:

=over

=item *

Generate a random seed (32 bytes).

=item *

Generate a ED25519 sigining keypair from that seed.

=item *

Generate a random seed (32 bytes).

=item *

Generate a Curve25519 encryption keypair from that seed.

=back

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

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

=head2 ENCRYPTED OUTPUT FORMAT

Encrypted output will always written as binary files. No armoring
supported yet. The encryption process works as this:

=over

=item generate a random symetric 32 byte key B<S>

=item encrypt it asymetrically for each recipient using a unique nonce (B<R>)

=item encrypt the input file 32k blockwise using the symetric key

=back

Symetric encryption works the very same with the recipient stuff
left out.

Formal format description, asymetric encrypted files:

 +---------------------------------------------------------+
 | Field         Size      Description                     |
 +-------------+--------+----------------------------------+
 | Type        |      1 | Filetype, 5=ASYM, 23=SYM         |
 +-------------|--------|----------------------------------+
 | Len R       |      4 | Number of recipients         (*) |
 +-------------|--------|----------------------------------+
 | Recipients  |   R*72 | C(recipient)|C(recipient)... (*) |
 +-------------|--------|----------------------------------+
 | Encrypted   |      ~ | The actual encrypted data        |
 +-------------|--------|----------------------------------+

Left out 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 calculated using public key encryption using the senders
secret key, the recipients public key and a random nonce.

=head2 SIGNATURE FORMAT

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

 +---------------------------------------------------------+
 | Field         Size      Description                     |
 +-------------+--------+----------------------------------+
 | Content     |      ~ | Original file content            |
 +-------------|--------|----------------------------------+
 | \nnacl-     |      6 | Offset separator                 |
 +-------------|--------|----------------------------------+
 | Hash        |     64 | BLAKE2 hash of the content       |
 +-------------|--------|----------------------------------+
 | Signature   |     64 | ED25519 signature of BLAKE2 Hash |
 +-------------|--------|----------------------------------+

The actual signature is not a signature over the whole content
of an input file but of a BLAKE2 hash of the content.

Armored signatures have the following format:

 ----- BEGIN ED25519 SIGNED MESSAGE -----
 Hash: Blake2
 
 MESSAGE
 
 ----- BEGIN ED25519 SIGNATURE -----
  Version: PCP v0.2.0
 
 195j%-^/G[cVo4dSk7hU@D>NT-1rBJ]VbJ678H4I!%@-)bzi>zOba5$KSgz7b@R]A0!kL$m
 MTQ-1DW(e1mma(<jH=QGA(VudgAMXaKF5AGo65Zx7-5fuMZt&:6IL:n2N{KMto*KQ$:J+]d
 dp1{3}Ju*M&+Vk7=:a=J0}B
 ------ END ED25519 SIGNATURE ------

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

=head2 SIGNED ENCRYPTION FORMAT

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

=head2 Z85 ENCODING

B<pcp1> uses Z85 to encode exported keys and armored signatures.

=head3 Z85 BACKGROUND

The Z85 encoding format is described here: B<http://rfc.zeromq.org/spec:32>.
It's part of ZeroMQ (B<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, B<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:

Expand the input so that the resulting size is divisible by 4.

Fill the added bytes with zeroes.

Prepend the input with a one byte value which holds the number of zeroes
added in the previous step.

Example:

Raw input:

 hello\0

Here, the input size is 6, which is insufficient, therefore it has to be expanded
to be 8. After the process the input looks like this:

 1hello\0\0

So, we padded the input with 1 zero (makes 7 bytes) and preprended it with the
value 1 (the number of zeros added): makes 8 bytes total.

After decoding Z85 input the process will be reversed.

B<Trying to use another tool to decode an Z85 encoded string produced
by z85, might not work therefore, unless the tool takes the padding scheme
outlined above into account>.

=head2 PBP COMPATIBILITY

PCP tries to be fully compatible with PBP (https://github.com/stef/pbp). Encrypted
files and signatures - at least their binary versions - should be exchangable. However,
this is a work in progress and might not work under all circumstances. Also there's currently
no shared key format between pbp and pcp.