mirror of
https://codeberg.org/scip/pcp.git
synced 2025-12-16 19:40:57 +01:00
444 lines
15 KiB
Groff
444 lines
15 KiB
Groff
.\" 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 "2013-10-28" "PCP 0.0.1" "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 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.
|
|
\& \-t \-\-text Print textual representation of some
|
|
\& item. Either \-V or \-i must be specified
|
|
\& as well.
|
|
\& \-h \-\-help Print this help message.
|
|
\& \-v \-\-version Print program version.
|
|
\& \-D \-\-debug Enable debug 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.
|
|
\& \-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.
|
|
\& \-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
|
|
\& been specified, the public part of your
|
|
\& primary secret key will be exported.
|
|
\& Use \-O to export to a file.
|
|
\& \-S \-\-import\-secret Import a secret key. Use \-I to import
|
|
\& from a file.
|
|
\& \-P \-\-import\-public Import a public key. Use \-I to import
|
|
\& from a file.
|
|
\&
|
|
\& Encryption Options:
|
|
\& \-e \-\-encrypt Encrypt a message. Read from stdin or
|
|
\& specified via \-I. A keyid (\-i) of the
|
|
\& public key of the receipient must be
|
|
\& specified. Output to stdout or written
|
|
\& to the file specified via \-O.
|
|
\& \-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.
|
|
\&
|
|
\& Encoding Options:
|
|
\& \-z \-\-z85\-encode Encode something to Z85 encoding. Use
|
|
\& \-I and \-O respectively, otherwise it
|
|
\& stdin/stdout.
|
|
\& \-Z \-\-z85\-decode Decode something from Z85 encoding. Use
|
|
\& \-I and \-O respectively, otherwise it
|
|
\& 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 part of their key:
|
|
.PP
|
|
.Vb 2
|
|
\& Alicia Bobby
|
|
\& pcp1 \-p \-O alicia.pub pcp1 \-p \-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 \-P \-I bobby.pub pcp1 \-P \-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 \-i 0x29A323A2C295D391 \-I letter \-O letter.z85
|
|
\& cat letter.z85 | mail bobby@foo.bar
|
|
\&
|
|
\& pcp1 \-d \-I letter.z85 | 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. When using for encryption, the keyid will be
|
|
added to the message so that the receiver knows who was the
|
|
sender of the message (\fBThis might change in the future. As of
|
|
this writing I'm not sure if this was a good idea\fR).
|
|
.PP
|
|
If you just want to know details about a key or the vault, use the
|
|
\&\fB\-t\fR option.
|
|
.SH "INTERNALS"
|
|
.IX Header "INTERNALS"
|
|
\&\s-1FIXME\s0.
|
|
.SH "Z85 ENCODING"
|
|
.IX Header "Z85 ENCODING"
|
|
\&\fBpcp1\fR uses Z85 to encode exported keys and encrypted messages.
|
|
Therefore it includes a Z85 utility mode:
|
|
.PP
|
|
\&\fBpcp1\fR can be used to encode and decode strings to Z85 encoding.
|
|
.PP
|
|
The option \fB\-z\fR encodes \fBto\fR Z85, the option \fB\-Z\fR does the opposite
|
|
and decodes \fBfrom\fR Z85.
|
|
.PP
|
|
If no input file have been specified using \fB\-I\fR, \fBpcp1\fR expects the
|
|
input to come from \fB\s-1STDIN\s0\fR, otherwise it reads the contents
|
|
of \fBfile\fR.
|
|
.PP
|
|
Encoded or decoded output will be written to \fB\s-1STDOUT\s0\fR unless an
|
|
output file has been specified using the option \fB\-O\fR.
|
|
.SS "\s-1EXAMPLES\s0"
|
|
.IX Subsection "EXAMPLES"
|
|
To encode a given file to Z85 and write the output to another:
|
|
.PP
|
|
.Vb 1
|
|
\& pcp1 \-z myfile.bin > myfile.z85
|
|
.Ve
|
|
.PP
|
|
To decode the file created above and restore the original:
|
|
.PP
|
|
.Vb 1
|
|
\& pcp1 \-Z \-d myfile.z85 > myfile.bin
|
|
.Ve
|
|
.PP
|
|
To encode something from stdin to Z85:
|
|
.PP
|
|
.Vb 1
|
|
\& ps axuw | pcp1 \-z > pslist.z85
|
|
.Ve
|
|
.PP
|
|
To decode the above and print to stdout:
|
|
.PP
|
|
.Vb 1
|
|
\& pcp1 \-Z \-d pslist.z85
|
|
.Ve
|
|
.SS "\s-1BACKGROUND\s0"
|
|
.IX Subsection "BACKGROUND"
|
|
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:
|
|
.PP
|
|
Expand the input so that the resulting size is divisible by 4.
|
|
.PP
|
|
Fill the added bytes with zeroes.
|
|
.PP
|
|
Prepend the input with a one byte value which holds the number of zeroes
|
|
added in the previous step.
|
|
.PP
|
|
Example:
|
|
.PP
|
|
Raw input:
|
|
.PP
|
|
.Vb 1
|
|
\& hello\e0
|
|
.Ve
|
|
.PP
|
|
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:
|
|
.PP
|
|
.Vb 1
|
|
\& 1hello\e0\e0
|
|
.Ve
|
|
.PP
|
|
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.
|
|
.PP
|
|
After decoding Z85 input the process will be reversed.
|
|
.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.
|
|
.SH "COPYRIGHT"
|
|
.IX Header "COPYRIGHT"
|
|
Copyright (c) 2013 by T.Linden <tom \s-1AT\s0 cpan \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.Linden <tom \s-1AT\s0 cpan \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
|