scip/pcp
1
0
Fork 0
mirror of https://codeberg.org/scip/pcp.git synced 2025-12-16 19:40:57 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
d019ec4b9e2a537412f34e9c61b7a9cbab381e37
pcp/man/pcp1.1
TLINDEN d019ec4b9e removed unused code (base85 and crc32)
2015-04-19 19:49:13 +02:00

1083 lines
46 KiB
Groff
Raw Blame History

.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PCP1 1"
.TH PCP1 1 "2015-04-19" "PCP 0.2.6" "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
.nh
.SH "NAME"
Pretty Curved Privacy \- File encryption using eliptic curve cryptography.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\& Usage: pcp1 [ \-\-help | \-\-version ]
\& [ \-\-keygen | \-\-listkeys | \-\-remove\-key | \-\-edit\-key ]
\& [ \-\-export\-public | \-\-export\-secret | \-\-import ]
\& [ \-\-encrypt | \-\-decrypt ]
\& [ \-\-sign | \-\-check\-signature ]
\& [ arguments ]
\&
\& General Options:
\& \-h \-\-help Print this help message.
\& \-\-version Print program version.
\& \-D \-\-debug Enable debug output.
\& \-v \-\-verbose Enable verbose output.
\& \-V \-\-vault <vaultfile> Specify an alternate vault file.
\& \-O \-\-outfile <file> Output file. STDOUT if unspecified.
\& \-I \-\-infile <file> Input file. STDIN if unspecified.
\& \-i \-\-keyid <id> Specify a key id for various operations.
\& \-r \-\-recipient <string> Specify a recpipient, multiple allowed.
\& \-t \-\-text Print textual representation of ojects.
\&
\& Keymanagement Options:
\& \-k \-\-keygen Generate new key pair.
\& \-l \-\-listkeys List all keys stored in your vault.
\& \-R \-\-remove\-key Remove a key from the vault.
\& \-s \-\-export\-secret Export a secret key.
\& \-p \-\-export\-public Export a public key.
\& \-K \-\-import Import a secret or public key.
\& \-y \-\-export\-yaml Export all keys as YAML formatted text.
\& \-F \-\-export\-format <fmt> Specify exportformat, either \*(Aqpbp\*(Aq or \*(Aqpcp\*(Aq.
\& \*(Aqpcp\*(Aq is the default if unspecified.
\& Encryption Options:
\& \-e \-\-encrypt Asym\-Encrypt a message. If none of \-i or \-r
\& has been given, encrypt the message symetrically.
\& \-A \-\-anonymous Use anonymous sender key pair.
\& \-M \-\-add\-myself Add you primary pub key to list of recipients.
\& \-m \-\-encrypt\-sym Symetrically encrypt a message.
\& \-d \-\-decrypt Decrypt a message.
\&
\& Signature Options:
\& \-g \-\-sign Create a signature of a file.
\& \-c \-\-check\-signature Verify a signature of a file.
\& \-f \-\-sigfile <file> Write or check a detached signature file.
\&
\& Encoding Options:
\& \-z \-\-z85\-encode Armor with Z85 encoding.
\&
\& Arguments:
\& Extra arguments after options are treated as filenames or
\& recipients, depending on operation mode.
.Ve
.SH "OPTIONS"
.IX Header "OPTIONS"
.Vb 1
\& Usage: pcp1 [options]
\&
\& General Options:
\& \-V \-\-vault <vaultfile> Specify an alternate vault file.
\& The deault vault is ~/.pcpvault.
\& \-O \-\-outfile <file> Output file. If not specified, stdout
\& will be used.
\& \-I \-\-infile <file> Input file. If not specified, stdin
\& will be used.
\& \-i \-\-keyid <id> Specify a key id to import/export.
\& \-r \-\-recipient <string> Specify a recpipient, used for public
\& key export and encryption.
\& \-t \-\-text Print textual representation of some
\& item. Specify \-V to get info about a
\& vault, \-i to get info about a key id
\& installed in the vault or \-I in which
\& case it determines itself what kind of
\& file it is.
\& \-h \-\-help Print this help message.
\& \-\-version Print program version.
\& \-D \-\-debug Enable debug 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\*(Aqt 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. If you
\& leave the passphrase empty, the key will
\& be stored unencrypted.
\& \-l \-\-listkeys List all keys currently stored in your
\& vault. Only the key id\*(Aqs and some info
\& about the keys will be printed, not the
\& actual keys.
\& \-L \-\-listkeys\-verbose Display a more verbose key listing
\& \-l \-v including signature fingerprint, key
\& fingerprint, checksum and the like.
\& \-R \-\-remove\-key Remove a key from the vault. Requires
\& option \-i <keyid>.
\& \-s \-\-export\-secret Export a secret key. If your vault only
\& contains one secret key, this one will
\& be exported. If a key id have been
\& specified (\-i), this one will be used.
\& If there are more than one secret keys
\& in the vault and no key id has been
\& given, export the primary secret key.
\& Use \-O to export to a file.
\& \-p \-\-export\-public Export a public key. If no key id have
\& \-\-export been specified, the public part of your
\& primary secret key will be exported.
\& Use \-O to export to a file.
\& \-K \-\-import Import a key. pcp determines automatically
\& \-\-import\-key the key type and encodingg. Use \-I to import
\& from a file.
\& \-y \-\-export\-yaml Export all keys stored in your vault
\& as YAML formatted text. Use \-O to put
\& the export into a file.
\& \-F \-\-format Export the key in a particular format.
\& Currently supported: pcp, pbp, yaml,
\& perl and C.
\&
\& Encryption Options:
\& \-e \-\-encrypt Asym\-Encrypt a message. Read from stdin or
\& specified via \-I. Output will be written
\& to stdout or the file given with \-O.
\& If a keyid (\-i) has been
\& given, use that public key for encryption.
\& If one or more recipient (\-r) has been given,
\& encrypt the message for all recipients
\& asymetrically, given there are matching
\& public keys installed in the vault for them.
\& If none of \-i or \-r has been given, encrypt
\& the message symetrically. This is the same
\& as \-m (self\-encryption mode).
\& 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\*(Aqt 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
\& for a passphrase. No key material will
\& be used. Same as \-e without \-r and \-i.
\& \-M \-\-add\-myself Add yourself to list of recipients in asymmetric
\& encryption mode, so that you can decrypt it as
\& well.
\& \-d \-\-decrypt Decrypt a message. Read from stdin or
\& specified via \-I. Output to stdout or
\& written to the file specified via \-O.
\& 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\*(Aqll have
\& to specify the keyid (\-i) of the key.
\& You need to have the public key of the
\& sender installed in your vault.
\& If the input is self\-encrypted (symetrically)
\& a passphrase will be requested.
\&
\& Signature Options:
\& \-g \-\-sign Create a signature of file specified with
\& \-I (or from stdin) using your primary
\& secret key. If \-r has been given, a derived
\& secret key will be used for signing.
\& \-c \-\-check\-signature <file> Verify a signature in file <file> against
\& the file specified with \-I (or stdin).
\& The public key required for this must
\& exist in your vault file.
\& \-f \-\-sigfile <file> Write a detached signature file, which doesn\*(Aqt
\& contain the original content. Output will be
\& z85 encoded always. To verify, you need to
\& specify the original file to be verified
\& against using \-I as well (plus \-f <sigfile>).
\&
\& Encoding Options:
\& \-z \-\-z85\-encode Encode (armor) something to Z85 encoding.
\& \-a \-\-armor If used with encryption or singing operation
\& \-\-textmode encode its output. Otherwise encode a plain
\& file. Use \-I and \-O respectively, otherwise it
\& uses stdin/stdout.
\& \-Z \-\-z85\-decode Decode (dearmor) something from Z85 encoding.
\& Use \-I and \-O respectively, otherwise it
\& uses stdin/stdout
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBPretty Curved Privacy\fR (pcp1) is a commandline utility which can
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.
.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
to learn about the curve and see how it works.
.PP
Beside some differences it works like \fB\s-1GNUPG\s0\fR. So, if you already
know how to use gpg, you'll feel almost home.
.SH "QUICKSTART"
.IX Header "QUICKSTART"
Lets say, Alicia and Bobby want to exchange encrypted messages.
Here's what the've got to do.
.PP
First, both have create a secret key:
.PP
.Vb 2
\& Alicia Bobby
\& pcp1 \-k pcp1 \-k
.Ve
.PP
After entering their name, email address and a passphrase to protect
the key, it will be stored in their \fBvault file\fR (by default ~/.pcpvault).
.PP
Now, both of them have to export the public key, which has to be
imported by the other one. With \fBpcp\fR 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:
.PP
.Vb 2
\& Alicia Bobby
\& pcp1 \-p \-r Bobby \-O alicia.pub pcp1 \-p \-r Alicia \-O bobby.pub
.Ve
.PP
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:
.PP
.Vb 2
\& Alicia Bobby
\& pcp1 \-K \-I bobby.pub pcp1 \-K \-I alicia.pub
.Ve
.PP
They will see a response as this when done:
.PP
.Vb 1
\& key 0x29A323A2C295D391 added to .pcpvault.
.Ve
.PP
Now, Alicia finally writes the secret message, encrypts it and
sends it to Bobby, who in turn decrypts it:
.PP
.Vb 4
\& 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
.Ve
.PP
And that's it.
.PP
Please note the big difference to \fB\s-1GPG\s0\fR though: both Alicia
\&\s-1AND\s0 Bobby have to enter the passphrase for their secret key!
That's the way \s-1CURVE25519\s0 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.
.PP
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.
.SH "PCP1 KEYS"
.IX Header "PCP1 KEYS"
\&\fBpcp1\fR keys are stored in a binary file, called \fBthe vault\fR.
It's by default located in \fB~/.pcpvault\fR but you can of course
specify another location using the \fB\-V\fR option.
.PP
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.
.PP
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.
.PP
Each key can be identified using its \fBkeyid\fR which looks like this:
.PP
.Vb 1
\& 0xD49119E85266509F
.Ve
.PP
A public key exported from a secret key will have the same keyid
as the secret key.
.PP
If you just want to know details about a key or the vault, use the
\&\fB\-t\fR option.
.SH "ENCRYPTION"
.IX Header "ENCRYPTION"
There are 3 modes of encryption available in pcp1:
.IP "\fBStandard public key encryption\fR" 4
.IX Item "Standard public key encryption"
In this mode, which is the default, a public key as specified
with \fB\-i\fR or \fB\-r\fR and your primary secret key will be used
for encryption.
.Sp
Example command:
.Sp
.Vb 1
\& pcp1 \-e \-i 0x2BD734B15CE2722D \-I message.txt \-O message.asc
.Ve
.Sp
Here we didn't specify a recipient. Therefore the public
key given with \-i will be used directly.
.Sp
Another example:
.Sp
.Vb 1
\& pcp1 \-e \-r Bobby \-r McCoy \-I message.txt \-O message.asc
.Ve
.Sp
As you can see, it is also possible to encrypt a message for multiple
recipients.
.IP "\fBAonymous public key encryption\fR" 4
.IX Item "Aonymous 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.
.Sp
Example command:
.Sp
.Vb 1
\& pcp1 \-r \-r Bobby \-A \-I message.txt \-O message.asc
.Ve
.Sp
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.
.IP "\fBSelf encryption mode\fR" 4
.IX Item "Self encryption mode"
You can also encrypt a file symetrically. No public key material
will be used in this mode.
.Sp
While this works, the security of it totally depends on the
strength of the passphrase used for encryption.
.Sp
Example command:
.Sp
.Vb 1
\& pcp1 \-e \-I message.txt \-O cipher.z85
.Ve
.Sp
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 \fIscrypt()\fR.
.Sp
\&\s-1PCP\s0 doesn't validate the security of the passphrase.
.SH "SIGNATURES"
.IX Header "SIGNATURES"
There are 3 modes for digital signatures available on pcp1:
.IP "\fBStandard \s-1NACL\s0 binary signatures\fR" 4
.IX Item "Standard NACL binary signatures"
In this mode, which is the default, an \s-1ED25519\s0 signature will
be calculated from a \s-1BLAKE2\s0 hash of the input file content. Both
the original file content plus the signature will be written to
the output file.
.Sp
Example:
.Sp
.Vb 1
\& pcp1 \-g \-I message.txt \-O message.asc \-g
.Ve
.Sp
You will be asked for the passphrase to access your primary
secret key. The output file will be a binary file.
.IP "\fBArmored \s-1NACL\s0 signatures\fR" 4
.IX Item "Armored NACL signatures"
While this mode does the very same calculations, the output
slightly differs. The output file will be marked as a signature
file, the signature itself will be appended with its own headers
and Z85 encoded.
.Sp
Example:
.Sp
.Vb 1
\& pcp1 \-g \-I message.txt \-O message.asc \-g \-z
.Ve
.Sp
You will be asked for the passphrase to access your primary
secret key. The output file will be a text file.
.IP "\fBDetached \s-1NACL\s0 signatures\fR" 4
.IX Item "Detached NACL signatures"
In some cases you will need to have the signature separated
from the original input file, e.g. to sign download files. You
can generate detached signatures for such purposes. Still, the
signature will be calculated the same way as in standard signatures
but put out into a separate file. A detached signature file will always
be Z85 encoded.
.Sp
Example:
.Sp
.Vb 1
\& pcp1 \-g \-I message.txt \-O \-g \-\-sigfile message.sig
.Ve
.Sp
Verification by recipient:
.Sp
.Vb 1
\& pcp \-c \-f message.sig \-I message.txt
.Ve
.SH "SIGNED ENCRYPTION"
.IX Header "SIGNED ENCRYPTION"
Beside pure encryption and signatures pcp1 also supports signed
encryption. In this mode an input file will be encrypted and a
signature of the encrypted content and encrypted recipients with your primary
secret key will be appended.
.PP
The signature is encrypted as well.
.PP
Example:
.PP
.Vb 1
\& pcp1 \-e \-g \-r Bobby \-I README.txt \-O README.asc
.Ve
.PP
Please note the additional \fB\-g\fR parameter. The recipient can
decrypt and verify the so created data like this:
.PP
.Vb 1
\& pcp1 \-d \-I README.asc \-o README.txt
.Ve
.PP
If decryption works, the output file will be written. If signature
verification fails you will be informed, but the decrypted
output will be left untouched. It is up to you how to react
on an invalid signature.
.SH "ALTERNATIVE COMMANDLINES"
.IX Header "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.
.PP
Here is a list of commandlines and their possible alternatives:
.PP
.Vb 1
\& ORIGINAL ALTERNATIVE DESCRIPTION
\&
\& pcp \-e \-I message \-r Bob pcp \-e \-r Bob message use \*(Aqmessage\*(Aq as inputfile.
\& pcp \-e \-I message Bob use \*(AqBob\*(Aq as recipient,
\& multiple recipients supported.
\&
\& pcp \-d \-I crypted pcp \-d crypted use \*(Aqcrypted\*(Aq as inputfile.
\&
\& pcp \-g \-I message pcp \-g message use \*(Aqmessage\*(Aq as inputfile.
\&
\& pcp \-g \-I msg \-O sig pcp \-g \-I msg sig use \*(Aqsig\*(Aq as outputfile.
\&
\& pcp \-p \-O key.pcp pcp \-p key.pcp use \*(Aqkey.pcp\*(Aq as outputfile.
\&
\& pcp \-p \-O key.pcp \-r Bob pcp \-p \-O key.pcp Bob use \*(AqBob\*(Aq as recipient.
\&
\& pcp \-s \-O key.pcp pcp \-s key.pcp use \*(Aqkey.pcp\*(Aq as outputfile.
\&
\& pcp \-s \-O key.pcp \-r Bob pcp \-s \-O key.pcp Bob use \*(AqBob\*(Aq as recipient.
\&
\& pcp \-K \-I alice.pcp pcp \-K alice.pcp use \*(Aqalice.pcp\*(Aq as keyfile.
.Ve
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
pcp respects the following environment variables:
.IP "\fB\s-1PCP_VAULT\s0\fR" 4
.IX Item "PCP_VAULT"
Use an alternative vaultfile. The default is \fB~/.pcpvault\fR and
can be overridden with the \fB\-V\fR commandline option. If \s-1PCP_VAULT\s0
is set, this one will be used instead.
.IP "\fB\s-1PCP_DEBUG\s0\fR" 4
.IX Item "PCP_DEBUG"
Enable debugging output, where supported. Same as \fB\-D\fR.
.SH "EXIT STATUS"
.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."
.PD 0
.IP "1 Generic error code." 4
.IX Item "1 Generic error code."
.PD
.SH "FILES"
.IX Header "FILES"
.IP "\fB~/.pcpvault\fR" 4
.IX Item "~/.pcpvault"
Default vault file where all keys are stored.
.SH "EXPERIMENTAL STATUS"
.IX Header "EXPERIMENTAL STATUS"
Currently there are a couple of problems which are currently
unsolved or in the process to be solved.
.IP "\fBNo secure native key exchange for store-and-forward systems\fR" 4
.IX Item "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 \fBCurveCP\fR which guarantees a
secure key exchange. But CurveCP cannot be used offline.
.Sp
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 \s-1AND\s0 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.
.IP "\fBCurve25519 not widely adopted\fR" 4
.IX Item "Curve25519 not widely adopted"
At the time of this writing the \s-1ECC\s0 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
\&\s-1ECC\s0 algorithms.
.Sp
While I, as the author of pcp1 totally trust D.J.Bernstein, this
may not be the case for you.
.Sp
In short, I'd suggest not to use it on critical systems yet.
.SH "INTERNALS"
.IX Header "INTERNALS"
.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.
.PP
The file starts with a header:
.PP
.Vb 9
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Field Size Description |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | File ID | 1 | Vault Identifier 0xC4 |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Version | 4 | Big endian, version |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Checksum | 32 | SHA256 Checksum |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
.Ve
.PP
The checksum is a checksum of all keys.
.PP
The header is followed by the keys. Each key is preceded by a
key header which looks like this:
.PP
.Vb 11
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | 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 |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
.Ve
.PP
Type can be one of:
.PP
.Vb 3
\& PCP_KEY_TYPE_MAINSECRET 0x01
\& PCP_KEY_TYPE_SECRET 0x02
\& PCP_KEY_TYPE_PUBLIC 0x03
.Ve
.PP
The key header is followed by the actual key, see below.
.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
.Vb 10
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | 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 |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
.Ve
.PP
Some notes:
.PP
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.
.PP
The key id is a computed \s-1JEN\s0 Hash of the secret and public
key concatenated, put into hex, as a string.
.PP
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.
.PP
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.
.PP
Key generation works like this:
.IP "\(bu" 4
Generate a random seed (32 bytes).
.IP "\(bu" 4
Generate a \s-1ED25519\s0 sigining keypair from that seed.
.IP "\(bu" 4
Generate a random seed (32 bytes).
.IP "\(bu" 4
Generate a Curve25519 encryption keypair from that seed.
.PP
So, while both secrets are stored in the sam \s-1PCP\s0 key, they
are otherwise unrelated. If one of them leaks, the other
cannot be recalculated from it.
.PP
Take a look at the function \fB\f(BIpcp_keypairs()\fB\fR for details.
.SS "\s-1ENCRYPTED\s0 \s-1OUTPUT\s0 \s-1FORMAT\s0"
.IX Subsection "ENCRYPTED OUTPUT FORMAT"
The encryption protocol used by \s-1PCP\s0 uses mostly standard
libsodium facilities with the exception that \s-1PCP\s0 uses counter
mode (CTR-Mode) for stream encryption.
.PP
.Vb 1
\& Detailed description:
.Ve
.IP "generate a random ephemeral 32 byte key \fBS\fR" 4
.IX Item "generate a random ephemeral 32 byte key S"
.PD 0
.IP "encrypt it asymetrically for each recipient using a unique nonce (\fBR\fR)" 4
.IX Item "encrypt it asymetrically for each recipient using a unique nonce (R)"
.IP "encrypt the input file 32k blockwise using the ephemeral key" 4
.IX Item "encrypt the input file 32k blockwise using the ephemeral key"
.RS 4
.IP "for each input block with a size of 32k bytes:" 4
.IX Item "for each input block with a size of 32k bytes:"
.IP "generate a random nonce \fBN\fR" 4
.IX Item "generate a random nonce N"
.IP "put the current counter size into the first byte of the nonce" 4
.IX Item "put the current counter size into the first byte of the nonce"
.IP "put the current counter (starting with 1) into the following byte(s), if larger than 1 byte, in big endian mode" 4
.IX Item "put the current counter (starting with 1) into the following byte(s), if larger than 1 byte, in big endian mode"
.IP "encrypt the 32k block using \fB\f(BIcrypto_secretbox()\fB\fR with the nonce \fBN\fR and the ephemeral key \fBS\fR" 4
.IX Item "encrypt the 32k block using crypto_secretbox() with the nonce N and the ephemeral key S"
.RE
.RS 4
.RE
.PD
.PP
Symetric encryption works the very same without the recipient stuff.
.PP
Formal format description, asymetric encrypted files:
.PP
.Vb 10
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Field Size Description |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Type | 1 | Filetype, 5=ASYM, 23=SYM, 6=ANON |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Anon PUB * | 32 | anon pubkey, only used with type 6 |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Len R * | 4 | Number of recipients (*) |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Recipients *| R*72 | C(recipient)|C(recipient)... (*) |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Encrypted | ~ | The actual encrypted data |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
.Ve
.PP
*) not included when doing symetric encryption.
.PP
Recipient field format:
.PP
.Vb 7
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Field Size Description |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Nonce | 24 | Random Nonce, one per R |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Cipher | 48 | S encrypted with PK or R |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
.Ve
.PP
R is generated using \fB\f(BIcrypto_box()\fB\fR with the senders
secret key, the recipients public key and a random nonce.
.PP
Pseudocode:
.PP
.Vb 5
\& 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))
.Ve
.PP
where P is the public key of a recipient, \s-1SK\s0 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.
.PP
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.
.PP
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\s0 \s-1FORMAT\s0"
.IX Subsection "SIGNATURE FORMAT"
There are different signature formats. Standard binary \s-1NACL\s0
signatures have the following format:
.PP
.Vb 11
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Field Size Description |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Content | ~ | Original file content |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | \ennacl\- | 6 | Offset separator |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Hash | 64 | BLAKE2 hash of the content |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Signature | 64 | ED25519 signature of BLAKE2 Hash |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
.Ve
.PP
The actual signature is not a signature over the whole content
of an input file but of a \s-1BLAKE2\s0 hash of the content.
.PP
Pseudo code:
.PP
.Vb 2
\& H = crypto_generichash(C)
\& C | O | H | crypto_sign(H, S)
.Ve
.PP
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.
.PP
Armored signatures have the following format:
.PP
.Vb 2
\& \-\-\-\-\- BEGIN ED25519 SIGNED MESSAGE \-\-\-\-\-
\& Hash: Blake2
\&
\& MESSAGE
\&
\& \-\-\-\-\- BEGIN ED25519 SIGNATURE \-\-\-\-\-
\& Version: PCP v0.2.0
\&
\& 195j%\-^/G[cVo4dSk7hU@D>NT\-1rBJ]VbJ678H4I!%@\-)bzi>zOba5$KSgz7b@R]A0!kL$m
\& MTQ\-1DW(e1mma(<jH=QGA(VudgAMXaKF5AGo65Zx7\-5fuMZt&:6IL:n2N{KMto*KQ$:J+]d
\& dp1{3}Ju*M&+Vk7=:a=J0}B
\& \-\-\-\-\-\- END ED25519 SIGNATURE \-\-\-\-\-\-
.Ve
.PP
The Z85 encoded signature at the end contains the same signature
contents as the binary signature outlined above (hash+sig).
.SS "\s-1SIGNED\s0 \s-1ENCRYPTION\s0 \s-1FORMAT\s0"
.IX Subsection "SIGNED ENCRYPTION FORMAT"
Signed encrypted files are in binary form only. The first part is
the standard encrypted file as described in \fB\s-1ENCRYPTED\s0 \s-1OUTPUT\s0 \s-1FORMAT\s0\fR
followed by the binary 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\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
so recipients know that the signature is forged.
.PP
Formal file description of sign+encrypt format:
.PP
.Vb 10
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | 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 |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Signature | ~ | Encrypted signature(*) |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
.Ve
.PP
As usual the encrypted signature consists of a nonce and the
actual cipher, which is computed symmetrically (see above)
from the following clear signature.
.PP
Before encryption the signature format is:
.PP
.Vb 7
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Field Size Description |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Hash | 64 | BLAKE2 hash of content+R (*) |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Signature | 64 | ED25519 signature of BLAKE2 Hash |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
.Ve
.PP
where R is: C(recipient)|C(recipient)... (see \fB\s-1ENCRYPTED\s0 \s-1OUTPUT\s0 \s-1FORMAT\s0\fR).
.PP
Pseudocode:
.PP
.Vb 1
\& N | crypto_secret_box( crypto_sign( crypto_generichash( M + R, SK ) ), N, S)
.Ve
.PP
where N is the nonce, M the message, R the recipient list, \s-1SK\s0 is the senders
secret signing key and S the symmetric key.
.SS "Z85 \s-1ENCODING\s0"
.IX Subsection "Z85 ENCODING"
\&\fBpcp1\fR uses Z85 to encode binary data (if requested with \-z) such
as encrypted data, exported keys or armored signatures.
.PP
Encoded data is always enclosed by a header and a footer and may have any number
of comments. Example:
.PP
.Vb 5
\& \-\-\-\-\- 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 \-\-\-\-\-
.Ve
.PP
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.
.PP
\fIZ85 \s-1PADDING\s0\fR
.IX Subsection "Z85 PADDING"
.PP
\&\s-1PCP\s0 uses a custom padding scheme. Z85 input data size must be a multiple
of 4. To fulfill this requirement, \s-1PCP\s0 padds the input with zeros as
neccessary. To tell the decoder if padding took place and how much zeros
have been added, \s-1PCP\s0 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.
.PP
\fIZ85 \s-1BACKGROUND\s0\fR
.IX Subsection "Z85 BACKGROUND"
.PP
The Z85 encoding format is described here: \fBhttp://rfc.zeromq.org/spec:32\fR.
It's part of ZeroMQ (\fBhttp://zeromq.org\fR). Z85 is based on \s-1ASCII85\s0 with
a couple of modifications (portability, readability etc).
.PP
To fulfil the requirements of the ZeroMQ Z85 functions, \fBpcp1\fR
does some additional preparations of raw input before actually doing the
encoding, since the input for \fIzmq_z85_encode()\fR must be divisible by 4. Therefore
we pad the input with zeroes and remove them after decoding.
.PP
\&\fBTrying to use another tool to decode an Z85 encoded string produced
by z85, might not work therefore, unless the tool takes the padding scheme
outlined above into account\fR.
.PP
Z85 encoding and decoding can be used separately as well to work with
files. Examples:
.PP
Encode some file to Z85 encoding:
.PP
pcp1 \-z \-I file \-O file.z85
.PP
Reverse the process:
.PP
pcp1 \-Z \-I file.z85 \-O file
.SS "\s-1PBP\s0 \s-1COMPATIBILITY\s0"
.IX Subsection "PBP COMPATIBILITY"
\&\s-1PCP\s0 tries to be fully compatible with \s-1PBP\s0 (https://github.com/stef/pbp). Encrypted
files and signatures \- at least their binary versions \- should be exchangable. However,
this is a work in progress and might not work under all circumstances. Also there's currently
no shared key format between pbp and pcp. However, it is possible to export and
import pbp keys from/to pcp.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2013\-2015 by T.v.Dein <tom \s-1AT\s0 vondein \s-1DOT\s0 org>
.SH "ADDITIONAL COPYRIGHTS"
.IX Header "ADDITIONAL COPYRIGHTS"
.IP "\fBZeroMQ Z85 encoding routine\fR" 4
.IX Item "ZeroMQ Z85 encoding routine"
.Vb 5
\& 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
.Ve
.IP "\fBTarsnap readpass helpers\fR" 4
.IX Item "Tarsnap readpass helpers"
.Vb 1
\& Copyright 2009 Colin Percival
.Ve
.IP "\fB\f(BIjen_hash()\fB hash algorithm\fR" 4
.IX Item "jen_hash() hash algorithm"
.Vb 1
\& Bob Jenkins, Public Domain.
.Ve
.IP "\fB\s-1UTHASH\s0 hashing macros\fR" 4
.IX Item "UTHASH hashing macros"
.Vb 1
\& Copyright (c) 2003\-2013, Troy D. Hanson
.Ve
.IP "\fBRandom art image from OpenSSH keygen\fR" 4
.IX Item "Random art image from OpenSSH keygen"
.Vb 1
\& Copyright (c) 2000, 2001 Markus Friedl. All rights reserved.
\&
\& Comitted by Alexander von Gernler in rev 1.7.
.Ve
.PP
Every incorporated source code is opensource and licensed
under the \fB\s-1GPL\s0\fR as well.
.SH "AUTHORS"
.IX Header "AUTHORS"
\&\fIT.v.Dein <tom \s-1AT\s0 vondein \s-1DOT\s0 org\fR>
.SH "LICENSE"
.IX Header "LICENSE"
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
http://www.daemon.de/PrettyCurvedPrivacy. The source is
on Github: https://github.com/TLINDEN/pcp
Reference in New Issue View Git Blame Copy Permalink