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
master
pcp/man/details.pod
git@daemon.de 64a45583d0 added check for weak passphrase using entropy test
2015-08-17 20:15:20 +02:00

975 lines
31 KiB
Plaintext
Raw Permalink Blame History

=head1 PCP1 KEYS
B<pcp1> keys are stored in a binary file, called B<the vault>.
It's by default located in B<~/.pcpvault> but you can of course
specify another location using the B<-V> option.
There are two kinds of keys: secret and public keys. In reality
a secret key always includes its public key. Both types of keys
can be exported to files and transfered to other people who can
then import them. You should usually only do this with public keys
though.
There is a primary secret key which will always used for operations
when no keyid has been specified. However, you may have as many
secret keys in your vault as you like.
Each key can be identified using its B<keyid> which looks like this:
0xD49119E85266509F
A public key exported from a secret key will have the same keyid
as the secret key.
If you just want to know details about a key or the vault, use the
B<-t> option.
=head1 ENCRYPTION
There are 3 modes of encryption available in pcp1:
=over
=item B<Standard public key encryption>
In this mode, which is the default, a public key as specified
with B<-i> or B<-r> and your primary secret key will be used
for encryption.
Example command:
pcp1 -e -i 0x2BD734B15CE2722D -I message.txt -O message.asc
Here we didn't specify a recipient. Therefore the public
key given with -i will be used directly.
Another example:
pcp1 -e -r Bobby -r McCoy -I message.txt -O message.asc
As you can see, it is also possible to encrypt a message for multiple
recipients.
=item B<Anonymous 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.
Example command:
pcp1 -r -r Bobby -A -I message.txt -O message.asc
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.
=item B<Self encryption mode>
You can also encrypt a file symetrically. No public key material
will be used in this mode.
While this works, the security of it totally depends on the
strength of the passphrase used for encryption.
Example command:
pcp1 -e -I message.txt -O cipher.z85
As you can see we didn't specify 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 scrypt().
PCP doesn't validate the security of the passphrase.
Self mode can be explicitly enforced with B<-m>.
=back
=head1 SIGNATURES
There are 3 modes for digital signatures available on pcp1:
=over
=item B<Standard NACL binary signatures>
In this mode, which is the default, an ED25519 signature will
be calculated from a BLAKE2 hash of the input file content. Both
the original file content plus the signature will be written to
the output file.
Example:
pcp1 -g -I message.txt -O message.asc -g
You will be asked for the passphrase to access your primary
secret key. The output file will be a binary file.
=item B<Armored NACL signatures>
While this mode does the very same calculations, the output
slightly differs. The output file will be marked as a signature
file, the signature itself will be appended with its own headers
and Z85 encoded.
Example:
pcp1 -g -I message.txt -O message.asc -g -z
You will be asked for the passphrase to access your primary
secret key. The output file will be a text file.
=item B<Detached NACL signatures>
In some cases you will need to have the signature separated
from the original input file, e.g. to sign download files. You
can generate detached signatures for such purposes. Still, the
signature will be calculated the same way as in standard signatures
but put out into a separate file. A detached signature file will always
be Z85 encoded.
Example:
pcp1 -g -I message.txt -O -g --sigfile message.sig
Verification by recipient:
pcp -c -f message.sig -I message.txt
=back
=head1 SIGNED ENCRYPTION
Beside pure encryption and signatures pcp1 also supports signed
encryption. In this mode an input file will be encrypted and a
signature of the encrypted content and encrypted recipients with your primary
secret key will be appended.
The signature is encrypted as well.
Example:
pcp1 -e -g -r Bobby -I README.txt -O README.asc
Please note the additional B<-g> parameter. The recipient can
decrypt and verify the so created data like this:
pcp1 -d -I README.asc -o README.txt
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.
=head1 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.
Here is a list of commandlines and their possible alternatives:
ORIGINAL ALTERNATIVE DESCRIPTION
pcp -e -I message -r Bob pcp -e -r Bob message use 'message' as inputfile.
pcp -e -I message Bob use 'Bob' as recipient,
multiple recipients supported.
pcp -d -I crypted pcp -d crypted use 'crypted' as inputfile.
pcp -g -I message pcp -g message use 'message' as inputfile.
pcp -g -I msg -O sig pcp -g -I msg sig use 'sig' as outputfile.
pcp -p -O key.pcp pcp -p key.pcp use 'key.pcp' as outputfile.
pcp -p -O key.pcp -r Bob pcp -p -O key.pcp Bob use 'Bob' as recipient.
pcp -s -O key.pcp pcp -s key.pcp use 'key.pcp' as outputfile.
pcp -s -O key.pcp -r Bob pcp -s -O key.pcp Bob use 'Bob' as recipient.
pcp -K -I alice.pcp pcp -K alice.pcp use 'alice.pcp' as keyfile.
=head1 ENVIRONMENT VARIABLES
pcp respects the following environment variables:
=over
=item B<PCP_VAULT>
Use an alternative vaultfile. The default is B<~/.pcpvault> and
can be overridden with the B<-V> commandline option. If PCP_VAULT
is set, this one will be used instead.
=item B<PCP_DEBUG>
Enable debugging output, where supported. Same as B<-D>.
=back
=head1 EXIT STATUS
Pcp may return one of several error codes if it encounters problems.
=over
=item 0 No problems occurred.
=item 1 Generic error code.
=back
=head1 FILES
=over
=item B<~/.pcpvault>
Default vault file where all keys are stored.
=back
=head1 EXPERIMENTAL STATUS
Currently there are a couple of problems which are
unsolved or in the process to be solved.
=over
=item B<No secure native key exchange for store-and-forward systems>
Pretty Curved Privacy is a store-and-forward system, it works
on files and can't use any cool key exchange protocols therefore.
For example there would be B<CurveCP> which guarantees a
secure key exchange. But CurveCP cannot be used offline.
Users have to find other means to exchange keys. That's a pity
since with Curve25519 you can't just publish your public key
to some key server because in order to encrypt a message, both
the recipient AND the sender need to have the public key of
each other. It would be possible to publish public keys,
and attach the senders public key to the encrypted message, but
I'm not sure if such an aproach would be secure enough. Pcp
implements this scheme though (refer to the option -A).
=item B<Curve25519 not widely adopted>
At the time of this writing the ECC algorithm Curve25519
is only rarely used, in most cases by experimental software
(such as Pretty Curved Privacy). As far as I know there haven't
been done the kind of exessive crypto analysis as with other
ECC algorithms.
While I, as the author of pcp1 totally trust D.J.Bernstein, this
may not be the case for you.
=item B<Unreviewed yet>
As with every crypto software, pcp has to undergo a couple rounds
of peer review (analysis) in order to be considered secure, trustable
and stable. No any such review has been undertaken on pcp yet.
Pcp is a mere fun project aimed at teaching myself better C coding
and crypto. In fact I don't even trust the software myself and I
don't use it for anything remotely serious.
=back
B<In short: don NOT use this software for production purposes!>
=head1 INTERNALS
=head2 PASSPHRASES
Passphrases are used to protect secret data at rest on various instances
by pcp, like secret keys or symmetric encrypted data.
Pcp doesn't use the passphrase directly but uses a key derivation function
to calculate a secure key from the passphrase: libsodium's
B<crypto_pwhash_scryptsalsa208sha256()> function.
In order to properly protect secret keys, pcp measures the entropy
of a given passphrase and warns the user about the possible weak
passphrase. This measurement is calculated using the Claude E. Shannon
method, where a value of 8.0 means maximum available entropy (e.g.
truly random 256 chars in no comprehensible order) and 0.0 stands
for the worst like passphrases like "aaa" or "x".
Pcp considers passphrases with an entropy measurement of 3.32 or higher
as acceptable. This may change in the future.
=head2 VAULT FORMAT
The vault file contains all public and secret keys. It's a portable
binary file.
The file starts with a header:
+-------------------------------------------+
| Field Size Description |
+-------------------------------------------+
| File ID | 1 | Vault Identifier 0xC4 |
+-------------------------------------------+
| Version | 4 | Big endian, version |
+-------------------------------------------+
| Checksum | 32 | SHA256 Checksum |
+-------------------------------------------+
The checksum is a checksum of all keys.
The header is followed by the keys. Each key is preceded by a
key header which looks like this:
+--------------------------------------------+
| Field Size Description |
+--------------------------------------------+
| Type | 1 | Key type (S,P,M) |
+--------------------------------------------+
| Size | 4 | Big endian, keysize |
+--------------------------------------------+
| Version | 4 | Big endian, keyversion |
+--------------------------------------------+
| Checksum | 32 | SHA256 Key Checksum |
+--------------------------------------------+
Type can be one of:
PCP_KEY_TYPE_MAINSECRET 0x01
PCP_KEY_TYPE_SECRET 0x02
PCP_KEY_TYPE_PUBLIC 0x03
The key header is followed by the actual key, see below.
=head2 SECRET KEY FORMAT
A secret key is a binary structure with the following format:
+---------------------------------------------------------+
| Field Size Description |
+-------------+--------+----------------------------------+
| Public | 32 | Curve25519 Public Key Part |
+-------------|--------|----------------------------------+
| Secret | 32 | Curve25519 Secret Key Unencrypted|
+-------------|--------|----------------------------------+
| ED25519 Pub | 32 | ED25519 Public Key Part |
+-------------|--------|----------------------------------+
| ED25519 Sec | 64 | ED25519 Secret Key Unencrypted |
+-------------|--------|----------------------------------+
| Nonce | 24 | Nonce for secret key encryption |
+-------------|--------|----------------------------------+
| Encrypted | 48 | Encrypted Curve25519 Secret Key |
+-------------|--------|----------------------------------+
| Owner | 255 | String, Name of Owner |
+-------------|--------|----------------------------------+
| Mail | 255 | String, Email Address |
+-------------|--------|----------------------------------+
| ID | 17 | String, Key ID |
+-------------|--------|----------------------------------+
| Ctime | 4 | Creation time, sec since epoch |
+-------------|--------|----------------------------------+
| Version | 4 | Key version |
+-------------|--------|----------------------------------+
| Serial | 4 | Serial Number |
+-------------|--------|----------------------------------+
| Type | 1 | Key Type |
+-------------+--------+----------------------------------+
Some notes:
The secret key fields will be filled with random data if the
key is encrypted. The first byte of it will be set to 0 in that
case.
The key id is a computed JEN Hash of the secret and public
key concatenated, put into hex, as a string.
The key version is a static value, currently 0x2. If the key
format changes in the future, this version number will be
increased to distinguish old from new keys.
Exported keys will be encoded in Z85 encoding. When such an
exported key is imported, only the actual Z85 encoded data
will be used. Header lines and lines starting with whitespace
will be ignored. They are only there for convenience.
Key generation works like this:
=over
=item *
Generate a random seed (32 bytes).
=item *
Generate a ED25519 sigining keypair from that seed.
=item *
Generate a random seed (32 bytes).
=item *
Generate a Curve25519 encryption keypair from that seed.
=back
So, while both secrets are stored in the same PCP key, they
are otherwise unrelated. If one of them leaks, the other
cannot be recalculated from it.
Take a look at the function B<pcp_keypairs()> for details.
=head2 PUBLIC KEY EXPORT FORMAT
Exported public and secret keys will be written in a portable
way. Pcp uses RFC4880 export format for public keys with some
slight modifications:
=over
=item
Key material is native to libsodium/pcp and not specified in the
rfc for curve25519/ed25519. Therefore pcp encodes key material doing it like
this: mp|sp|cp
where
mp = master keysigning public key (ed25519), 32 bytes
sp = signing public key (ed25519), 32 bytes
cp = encryption public key (curve25519), 32 bytes
=item
The various cipher (algorithm) id's are unspecified for
libsodium/pcp native ciphers. Therefore they are proprietary to pcp, starting at
33 (22 is the last officially assigned one). Once
those cipher numbers become official, they will be used instead.
=item
Pcp uses 64 bit integers for timestamps everywhere (ctime, expire, etc),
to be year 2038 safe. Note, that this is a violation of the
RFC spec. However, said RFC have to be modified to fit 2038
(and beyond) anyways. This applies for the keyfile ctime as
well for the key sig sub fields containing time values.
=item
The exported public key packet contains a signature. Pcp is
filling out all required fields. A signature has a variable
number of sig sub packets. Pcp uses only these types:
2 = Signature Creation Time (8 byte)
3 = Signature Expiration Time (8 byte)
9 = Key Expiration Time (8 bytes)
20 = Notation Data (4 byte flags, N bytes name+value)
27 = Key Flags (1 byte, use 0x02, 0x08 and 0x80
=item
Pcp uses 3 notation fields:
=over
=item "owner", which contains the owner name, if set
=item "mail", which contains the emailaddress, if set
=item "serial", which contains the 32bit serial number
=back
=item
The actual signature field consists of the blake2 hash of
(mp|sp|cp|keysig) followed by the nacl signature. However, pcp
does not put an extra 16 byte value of the hash, since the nacl
signature already contains the full hash. So, an implementation
could simply pull the fist 16 bytes of said hash to get
the same result if desired.
=item
The mp keypair will be used for signing. The recipient can
verify the signature, since mp is included.
=item
While pcp puts expiration dates for the key and the signature
into the export as the rfc demands, it mostly ignores them (yet).
Key expiring is not implemented in PCP yet.
=item
We use big-endian always.
=item
Unlike RC4880 public key exports, pcp uses Z85 encoding if
armoring have been requested by the user. Armored output has
a header and a footer line, however they are ignored by the
parser and are therefore optional. Newlines, if present, are
optional as well.
http://tools.ietf.org/html/rfc4880#section-5.2.3
=item
The key sig blob will be saved in the Vault unaltered during
import, so pcp is able to verify the signature at will anytime. When exporting
a foreign public key, pcp just puts out that key sig blob to the
export untouched.
=item
Currently PCP only supports self-signed public key exports.
=item
Pcp only supports one key signature per key. However, it would be easily
possible to support foreign keysigs as well in the future.
=back
So, a full pubkey export looks like this
version
ctime
cipher
3 x raw keys \
sigheader > calculate hash from this
sigsubs (header+data) /
hash
signature
=head2 SECRET KEY EXPORT FORMAT
Secret keys are exported in a proprietary format.
The exported binary blob is symmetrically encrypted using the NACL
function crypto_secret(). The passphrase will be used to derive an
encryption key using the STAR function scrypt().
The binary data before encryption consists of:
ED25519 master signing secret
Curve25519 encryption secret
ED25519 signing secret
ED25519 master signing public
Curve25519 encryption public
ED25519 signing public
Optional notations, currently supported are the 'owner' and 'mail' attributes.
If an attribute is empty, the len field is zero.
-# len(VAL) (2 byte uint)
-# VAL (string without trailing zero)
8 byte creation time (epoch)
4 byte key version
4 byte serial number
The encrypted cipher will be prepended with the random nonce used
to encrypt the data and looks after encryption as such:
Nonce | Cipher
=head2 ENCRYPTED OUTPUT FORMAT
The encryption protocol used by PCP uses mostly standard
libsodium facilities with the exception that PCP uses counter
mode (CTR-Mode) for stream encryption.
Detailed description:
=over
=item generate a random ephemeral 32 byte key B<S>
=item encrypt it asymetrically for each recipient using a unique nonce (B<R>)
=item encrypt the input file 32k blockwise using the ephemeral key
=over
=item for each input block with a size of 32k bytes:
=item generate a random nonce B<N>
=item put the current counter size into the first byte of the nonce
=item put the current counter (starting with 1) into the following byte(s), if larger than 1 byte, in big endian mode
=item encrypt the 32k block using B<crypto_secretbox()> with the nonce B<N> and the ephemeral key B<S>
=back
=back
Symetric encryption works the very same without the recipient stuff.
Formal format description, asymetric encrypted files:
+-----------------------------------------------------------+
| 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 |
+-------------|--------|------------------------------------+
*) not included when doing symetric encryption.
Recipient field format:
+---------------------------------------------------------+
| Field Size Description |
+-------------+--------+----------------------------------+
| Nonce | 24 | Random Nonce, one per R |
+-------------|--------|----------------------------------+
| Cipher | 48 | S encrypted with PK or R |
+-------------|--------|----------------------------------+
R is generated using B<crypto_box()> with the senders
secret key, the recipients public key and a random nonce.
Pseudocode:
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))
where P is the public key of a recipient, SK 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.
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.
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.
=head2 SIGNATURE FORMAT
There are different signature formats. Standard binary NACL
signatures have the following format:
+---------------------------------------------------------+
| Field Size Description |
+-------------+--------+----------------------------------+
| Content | ~ | Original file content |
+-------------|--------|----------------------------------+
| \nnacl- | 6 | Offset separator |
+-------------|--------|----------------------------------+
| Hash | 64 | BLAKE2 hash of the content |
+-------------|--------|----------------------------------+
| Signature | 64 | ED25519 signature of BLAKE2 Hash |
+-------------|--------|----------------------------------+
The actual signature is not a signature over the whole content
of an input file but of a BLAKE2 hash of the content.
Pseudo code:
H = crypto_generichash(C)
C | O | H | crypto_sign(H, S)
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.
Armored signatures have the following format:
----- BEGIN ED25519 SIGNED MESSAGE -----
Hash: Blake2
MESSAGE
----- BEGIN ED25519 SIGNATURE -----
Version: PCP v0.2.0
195j%-^/G[cVo4dSk7hU@D>NT-1rBJ]VbJ678H4I!%@-)bzi>zOba5$KSgz7b@R]A0!kL$m
MTQ-1DW(e1mma(<jH=QGA(VudgAMXaKF5AGo65Zx7-5fuMZt&:6IL:n2N{KMto*KQ$:J+]d
dp1{3}Ju*M&+Vk7=:a=J0}B
------ END ED25519 SIGNATURE ------
The Z85 encoded signature at the end contains the same signature
contents as the binary signature outlined above (hash+sig).
=head2 SIGNED ENCRYPTION FORMAT
Signed encrypted files are in binary form only. The first part is
the standard encrypted file as described in B<ENCRYPTED OUTPUT FORMAT>
followed by the binary encrypted signature described in B<SIGNATURE FORMAT>
without the offset separator.
However, not only the hash of the file content will be signed but the
recipient list described in B<ENCRYPTED OUTPUT FORMAT> 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.
Formal file description of sign+encrypt format:
+---------------------------------------------------------+
| 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(*) |
+-------------|--------|----------------------------------+
As usual the encrypted signature consists of a nonce and the
actual cipher, which is computed symmetrically (see above)
from the following clear signature.
Before encryption the signature format is:
+---------------------------------------------------------+
| Field Size Description |
+-------------+--------+----------------------------------+
| Hash | 64 | BLAKE2 hash of content+R (*) |
+-------------|--------|----------------------------------+
| Signature | 64 | ED25519 signature of BLAKE2 Hash |
+-------------|--------|----------------------------------+
where R is: C(recipient)|C(recipient)... (see B<ENCRYPTED OUTPUT FORMAT>).
Pseudocode:
N | crypto_secret_box( crypto_sign( crypto_generichash( M + R, SK ) ), N, S)
where N is the nonce, M the message, R the recipient list, SK is the senders
secret signing key and S the symmetric key.
=head2 Z85 ENCODING
B<pcp1> uses Z85 to encode binary data (if requested with -z) such
as encrypted data, exported keys or armored signatures.
Encoded data is always enclosed by a header and a footer and may have any number
of comments. Example:
----- 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 -----
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.
=head3 Z85 PADDING
PCP uses a custom padding scheme. Z85 input data size must be a multiple
of 4. To fulfill this requirement, PCP padds the input with zeros as
neccessary. To tell the decoder if padding took place and how much zeros
have been added, PCP 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.
=head3 Z85 BACKGROUND
The Z85 encoding format is described here: B<http://rfc.zeromq.org/spec:32>.
It's part of ZeroMQ (B<http://zeromq.org>). Z85 is based on ASCII85 with
a couple of modifications (portability, readability etc).
To fulfil the requirements of the ZeroMQ Z85 functions, B<pcp1>
does some additional preparations of raw input before actually doing the
encoding, since the input for zmq_z85_encode() must be divisible by 4. Therefore
we pad the input with zeroes and remove them after decoding.
B<Trying to use another tool to decode an Z85 encoded string produced
by z85, might not work therefore, unless the tool takes the padding scheme
outlined above into account>.
Z85 encoding and decoding can be used separately as well to work with
files. Examples:
Encode some file to Z85 encoding:
pcp1 -z -I file -O file.z85
Reverse the process:
pcp1 -Z -I file.z85 -O file
=head2 PBP COMPATIBILITY
PCP tries to be fully compatible with PBP (https://github.com/stef/pbp). Encrypted
files and signatures - at least their binary versions - should be exchangable. However,
this is a work in progress and might not work under all circumstances. Also there's currently
no shared key format between pbp and pcp. However, it is possible to export and
import pbp keys from/to pcp.
=head1 JSON ENCODING SUPPORT
If pcp have been compiled with B<--with-json> (which requires the libjansson
library), then it supports JSON objects as input and output with the following
functions:
=over
=item public key export
=item secret key export
=item whole vault export
=item public key import
=item secret key import
=back
JSON support can be used either with the commandline tool B<pcp1> or programmatically
using the C, C++ or Python API.
=head2 USING JSON FROM THE C API
In order to use JSON all you've got to do is to switch a context flag:
PCPCTX *ptx = ptx_new();
ptx->json = 1;
That all to it. Now any function normally used for key import and export works
with JSON, just fill the B<Buffer> object with a JSON string for imports or
fetch the Buffer content of an export function as a string.
=head2 USING JSON FROM THE COMMANDLINE
In order to use JSON on the commandline, add B<-j>. This can be used in
conjunction with the following options:
=over
=item B<-p>
Public key export.
=item B<-s>
Secret key export.
=item B<-K>
Public and secret key import.
=item B<-t>
Text view mode (aka inspect mode).
=back
The B<-z> and B<-Z> options are ignored in JSON mode.
=head2 JSON OBJECT STRUCTURE
=head3 JSON PUBLIC KEY (pcp1 -p -j)
The JSON object for a public key looks like this:
{
"id": "6BF2980419E0986A",
"owner": "tom",
"mail": "tom@local",
"ctime": 1436170865,
"expire": 1467706865,
"version": 6,
"serial": 1509801135,
"type": "public",
"cipher": "CURVE25519-ED25519-POLY1305-SALSA20",
"cryptpub": "0fdf0f7269f901b7f0fba989a1fddbf576c7cc148a2e5987fdeea3523978fe01",
"sigpub": "6980b76e17170194626b49cbab1ab35369a0635f52fe1a7cf39cc5421fb5c0c2",
"masterpub": "947a49f29e9cb0e92b61e2a1dea95f8ec81a24baed78e85c1b52cc3714f5e45e",
"signature": "947a49f29e9cb0e92b61e2a1dea95f8ec81a24baed78e85c1b52cc3714f5e45[..]"
}
Actually the field B<signature> contains the whole encoded public key.
Fields containing byte arrays are hex encoded.
Numbers are represented as literal integers.
=head3 JSON SECRET KEY (pcp1 -s -j)
The JSON object for a public key looks like this:
{
"id": "6BF2980419E0986A",
"owner": "tom",
"mail": "tom@local",
"ctime": 1436170865,
"expire": 1467706865,
"version": 6,
"serial": 1509801135,
"type": "secret",
"cipher": "CURVE25519-ED25519-POLY1305-SALSA20",
"cryptpub": "0fdf0f7269f901b7f0fba989a1fddbf576c7cc148a2e5987fdeea3523978fe01",
"sigpub": "6980b76e17170194626b49cbab1ab35369a0635f52fe1a7cf39cc5421fb5c0c2",
"masterpub": "947a49f29e9cb0e92b61e2a1dea95f8ec81a24baed78e85c1b52cc3714f5e45e",
"secrets": "ad5ce150f3cd7bffa299d4db5bf3d26ae56c3808ccba7[..]",
"nonce": "858ef9870fc8f39903cfb281d697ca29a935d2ae929fa4ea"
}
As you can see that's pretty identical to a public key json object beside the
B<secrets> and B<nonce> fields. The B<secrets> field contains the encrypted
secret key material. Pcp does not support exporting a secret key unencrypted.
The B<nonce> is required for a later import and shall not be changed or
decoupled from B<secrets>. This may change in the future.
=head3 JSON VAULT (pcp1 -t)
The JSON object for the vault looks like this:
{
"keyvaultfile": "/home/tom/.pcpvault",
"version": 2,
"checksum": "27b583dc2dacf5ccc874b7be3a39748d107c6b9e9f9d473f1c716a94561ef793",
"secretkeys": 1,
"publickey": 3,
"keys": []
}
The field B<keys> is an array containing one or more of the already
described key objects.
=head3 JSON PROGRAM OUTPUT
Currently pcp does not support JSON program output, that is, success or
error messages on STDERR are not encoded as json. This may change in the future.
Reference in New Issue View Git Blame Copy Permalink