.\" 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-11-28" "PCP 0.1.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 .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 Specify an alternate vault file. \& The deault vault is ~/.pcpvault. \& \-O \-\-outfile Output file. If not specified, stdout \& will be used. \& \-I \-\-infile Input file. If not specified, stdin \& will be used. \& \-i \-\-keyid Specify a key id to import/export. \& \-r \-\-recipient 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. \& \-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. 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. \& \-R \-\-remove\-key Remove a key from the vault. Requires \& option \-i . \& \-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. \& \-y \-\-export\-yaml Export all keys stored in your vault \& as YAML formatted text. Use \-O to put \& the export into a file. \& Encryption Options: \& \-e \-\-encrypt Encrypt a message. Read from stdin or \& specified via \-I. If a keyid (\-i) has been \& given, use that public key for encryption. \& If a recipient (\-r) has been given, use \& a derived public key. If none of \-i or \& \-r has been given, use the primary \& secret key and the public part of it \& for encrytion (self\-encryption mode). \& \-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. \& \& 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 Verify a signature in file against \& the file specified with \-I (or stdin). \& The public key required for this must \& exist in your vault file. \& \& 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, 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 \-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. .PP # \-*\-perl\-*\- .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. .SS "Derived Public Keys" .IX Subsection "Derived Public Keys" In the real world you would not use your primary key to encrypt messages, because this would require to send the public key part to your recipient in one way or another. The much better and more secure way is to use a \fBDerived Public Key\fR: .PP Such a key will be dynamically generated from a hash of your primary secret key and the recipient (an email address, name or key id). The public part of this dynamic key will be exported and sent to the recipient. A public key generated this way will only be usable by the recipient (and yourself) and each recipient will have a different public key from you (and vice versa). .SH "ENCRYPTION" .IX Header "ENCRYPTION" There are 3 modi for 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 and the primary secret key will be used for encryption. The public key in question maybe a derived public key, which is transparent for the sender however. .Sp If you don't use derived keys, you will have to transfer the public key part of your primary keypair to the recipient, which is considered insecure if the transfer channel itself uses untrusted transports or if the transferred public key ends up on a public system (a shared server, a workstation at your employer or the like). You should avoid this encryption mode in such cases and use derived keys instead. .Sp Example command: .Sp .Vb 1 \& pcp1 \-e \-i 0x2BD734B15CE2722D \-I message.txt \-O cipher.z85 .Ve .Sp Here we didn't specify a recipient. Therefore the public key given with \-i will be used directly. .IP "\fBDerived public key encryption\fR" 4 .IX Item "Derived public key encryption" Derived keys will be generated dynamically at runtime (see \fBDerived Public Keys\fR above). Therefore an exported derived public key is unique for the sender \s-1AND\s0 recipient. .Sp This mode can be considered the most secure. If such a key gets lost (or into the wrong hands), only this specific communication channel will be compromised. .Sp Example command: .Sp .Vb 1 \& pcp1 \-e \-r bobby@local \-I message.txt \-O cipher.z85 .Ve .Sp We specified a recipient. pcp1 searches the vault for a matching public key and generates a derived keypair for encryption. You need to have a public key installed from the recipient anyway, it won't work without one. You may also specify a key id (\-i) as well to make sure, the right key will be used for derivation. .IP "\fBSelf encryption mode\fR" 4 .IX Item "Self encryption mode" Pretty Curved Privacy doesn't provide symetric file encryption. However there are cases when you need to encrypt a file just for yourself. In such a case the file will be encrypted using the public key part of your primary secret key and the secret key itself (thanks to the wonders of \s-1ECC\s0 this works like a charm). .Sp The file can be decrypted using the primary key pair. .Sp While this works, the security of it totally depends on the strength of your password, especially if the primary secret used for this kind of encryption is stored in a vault on the same system. .Sp Example command: .Sp .Vb 1 \& pcp1 \-e \-I message.txt \-O cipher.z85 .Ve .Sp As you can see we didn't specify \-i or \-r and therefore pcp1 tries to use the primary keypair for encryption. .SH "VULNERABILITIES" .IX Header "VULNERABILITIES" Currently there are a couple of problems which are not addressed. These are usually protocol problems, which are not caused by pcp1. .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 keypair from that seed. .IP "\(bu" 4 Take the first 32 bytes of the generated \s-1ED25519\s0 secret and generate a \s-1SHA512\s0 hash from it. .IP "\(bu" 4 Clamp bytes 0 and 31 which turns it into a Curve25519 secret. .IP "\(bu" 4 Do scalar multiplication from that secret to retrieve the matching public key. .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" Encrypted output will always be Z85 encoded and has the following format: .PP .Vb 7 \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | Field Size Description | \& +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | Hash | 32 | Hash of the sender key id | \& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | Encrypted | ~ | The actual encrypted data | \& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ .Ve .SS "\s-1SIGNATURE\s0 \s-1FORMAT\s0" .IX Subsection "SIGNATURE FORMAT" Signatures will always be Z85 encoded and have the following format: .PP .Vb 11 \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | Field Size Description | \& +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | Key ID | 17 | Signers key id \& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | Ctime | 4 | Creation time, sec since epoch | \& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | Version | 4 | Signature version | \& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | Signature | 96 | ED25519 signature of SHA256 Hash | \& +\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ .Ve .PP The actual signature is not a signature over the whole content of an input file but of a \s-1SHA256\s0 hash of the content. .SS "Z85 \s-1ENCODING\s0" .IX Subsection "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. .PP \fIZ85 \s-1EXAMPLES\s0\fR .IX Subsection "Z85 EXAMPLES" .PP 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 .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: .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 .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 .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