mirror of
https://codeberg.org/scip/pcp.git
synced 2025-12-19 04:40:56 +01:00
updated doc
This commit is contained in:
TLINDEN
118
man/pcp1.1
118
man/pcp1.1
@@ -1,4 +1,4 @@
|
||||
.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20)
|
||||
.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
|
||||
.\"
|
||||
.\" Standard preamble:
|
||||
.\" ========================================================================
|
||||
@@ -124,7 +124,7 @@
|
||||
.\" ========================================================================
|
||||
.\"
|
||||
.IX Title "PCP1 1"
|
||||
.TH PCP1 1 "2014-12-24" "PCP 0.2.4" "USER CONTRIBUTED DOCUMENTATION"
|
||||
.TH PCP1 1 "2015-01-17" "PCP 0.2.5" "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
|
||||
@@ -264,7 +264,7 @@ Pretty Curved Privacy \- File encryption using eliptic curve cryptography.
|
||||
\& 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 or
|
||||
\& \-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.
|
||||
@@ -417,7 +417,7 @@ 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 2 modes of encryption available in pcp1:
|
||||
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
|
||||
@@ -438,10 +438,26 @@ Another example:
|
||||
.Vb 1
|
||||
\& pcp1 \-e \-r Bobby \-r McCoy \-I message.txt \-O message.asc
|
||||
.Ve
|
||||
.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
|
||||
@@ -451,9 +467,11 @@ Example command:
|
||||
\& pcp1 \-e \-I message.txt \-O cipher.z85
|
||||
.Ve
|
||||
.Sp
|
||||
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.
|
||||
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:
|
||||
@@ -740,37 +758,57 @@ cannot be recalculated from it.
|
||||
Take a look at the function \fB\f(BIpcp_keypairs()\fB\fR for details.
|
||||
.SS "\s-1ENCRYPTED\s0 \s-1OUTPUT\s0 \s-1FORMAT\s0"
|
||||
.IX Subsection "ENCRYPTED OUTPUT FORMAT"
|
||||
Encrypted output will always written as binary files. No armoring
|
||||
supported yet. The encryption process works as this:
|
||||
.IP "generate a random symetric 32 byte key \fBS\fR" 4
|
||||
.IX Item "generate a random symetric 32 byte key S"
|
||||
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 symetric key" 4
|
||||
.IX Item "encrypt the input file 32k blockwise using the symetric key"
|
||||
.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 with the recipient stuff
|
||||
left out.
|
||||
Symetric encryption works the very same without the recipient stuff.
|
||||
.PP
|
||||
Formal format description, asymetric encrypted files:
|
||||
.PP
|
||||
.Vb 11
|
||||
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
|
||||
\& | 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 |
|
||||
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
|
||||
.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
|
||||
Left out when doing symetric encryption.
|
||||
*) not included when doing symetric encryption.
|
||||
.PP
|
||||
Recipient field format:
|
||||
.PP
|
||||
@@ -784,7 +822,7 @@ Recipient field format:
|
||||
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
|
||||
.Ve
|
||||
.PP
|
||||
R is calculated using public key encryption using the senders
|
||||
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:
|
||||
@@ -802,6 +840,12 @@ 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.
|
||||
@@ -920,7 +964,7 @@ secret signing key and S the symmetric key.
|
||||
\&\fBpcp1\fR uses Z85 to encode binary data (if requested with \-z) such
|
||||
as encrypted data, exported keys or armored signatures.
|
||||
.PP
|
||||
Encoded data are always enclosed by a header and a footer and may have any number
|
||||
Encoded data is always enclosed by a header and a footer and may have any number
|
||||
of comments. Example:
|
||||
.PP
|
||||
.Vb 5
|
||||
@@ -933,9 +977,19 @@ of comments. Example:
|
||||
.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 are comments. Empty comments are not
|
||||
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
|
||||
@@ -971,7 +1025,7 @@ 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\-2014 by T.v.Dein <tom \s-1AT\s0 vondein \s-1DOT\s0 org>
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user