Write a 8 byte (64 bit) number in binary form into the buffer, converted to big endian.
+
+
+
Detailed Description
+
Flexible buffer management, idea from openssh/buffer.c.
+
This class allows us to dissect buffers into parts at will whithout the hassle of boundary checking in each and every line. Therefore it is more secure, since this system wraps all this stuff from us, so in case we're attemt to overflow a buffer or the like, the buffer functions will catch this, warn us and die.
Adds data of the size len to the buffer and resizes the buffer, if neccessary. The write position ('end' field) will be updated accordingly. Each byte will be put in its HEX form into the buffer (%02x).
+
Data will be copied, you can free() the given pointer after copying..
This clears the buffer by filling it with zeroes and resetting all counters. Memory will not be free'd. Called from buffer_free() before free'ing memory.
This function reads in len bytes from the FILE stream 'in' into the Buffer. The file must already be opened by the caller.
+
Parameters
+
+
[in,out]
b
The Buffer object to read from.
+
[in]
in
The FILE stream to read from.
+
[in]
len
The number of bytes to read.
+
+
+
+
Returns
Returns the number of bytes read or 0 in case of an error or EOF. Use feof() and ferror() to check this afterwards, call fatals_ifany() in case of errors.
This clears the buffer by filling it with zeroes and frees any allocated memory, including the Buffer object itself. Use this function instead of directly calling free(Buffer).
This function returns the whole buffer contents as a pointer to the internal data member (Buffer->buf). The returned pointer is allocated and filled with data up to buffer_size(Buffer), however, the allocated memory might be more than size, in fact it will be a multitude of Buffer-blocksize.
+
Don't free() the pointer directly, use buffer_free() always.
Read some chunk of data from the Buffer, starting from current read
+offset til len.
+
+Example: suppose you've got a buffer with the following content:
+
+@code
+AAAABBBBCCCC
+@endcode
+
+Then the following code would:
+
+@code
+unsigned char g[4];
+buffer_get_chunk(b, g, 4); // => g now contains 'AAAA'
+buffer_get_chunk(b, g, 4); // => g now contains 'BBBB'
+buffer_get_chunk(b, g, 4); // => g now contains 'CCCC'
+@endcode
+
+In order to catch buffer overflow, check the return value, which will
+be 0 in case of errors. See also: fatals_ifany(), buffer_done() and buffer_left().
+
+\param[in] b The Buffer object to read from.
+
+\param[out] buf The destination pointer where the data will be copied to. This pointer
+
must be allocated by the caller properly and it must have at least a size of len.
+
\param[in] len The number of bytes to read from the Buffer.
Read the remaining data after current read offset.
+
Fetch whatever is left in the buffer. This works like buffer_get() but instead doesn't return everything, but only the part of the buffer, which follows after the current read offset.
+
The returned pointer will be allocated by buffer_get_remainder() with a size of buffer_left(). It's up to the caller to free() the returned pointer later on.
+
Example: suppose you've got a buffer with the following content:
The returned pointer is allocated and filled with data up to buffer_size(Buffer), however, the allocated memory might be more than size, in fact it will be a multitude of Buffer-blocksize.
+
The byte after buffer_size(Buffer) will be a \0.
+
Don't free() the pointer directly, use buffer_free() always.
Create a new buffer, but don't allocate memory nor copy data. Instead the provided data pointer will be used as internal storage directly.
+
This kind of buffer can be used to put the Buffer API into use with existing data from other sources. In most cases you'll use it for reading. However, please be aware, that it can be used for writing as well and in this case the data pointer maybe resized (by calling realloc()).
+
When calling buffer_free() on this Buffer, the memory pointed to by the given data pointer will not be free'd and remains accessible. It's the responsibility of the caller to do so.
Tell how much data there is in the buffer available.
+
This function returns the number of bytes stored in the buffer so far. Please note, that the actual allocation might be bigger, because we always allocate memory blockwise.
+
Parameters
+
+
[in]
b
The Buffer object to get the size from.
+
+
+
+
Returns
The number of bytes stored in the Buffer.
+
+
+
+
+
+
+Generated on Thu Feb 20 2014 19:59:14 for libpcp by
+
+ 1.8.2
+
+
+
diff --git a/man/html/group__CRYPTO.html b/man/html/group__CRYPTO.html
new file mode 100644
index 0000000..2db4a4e
--- /dev/null
+++ b/man/html/group__CRYPTO.html
@@ -0,0 +1,595 @@
+
+
+
+
+
+libpcp: CRYPTO
+
+
+
+
+
+
+
Functions for symmetrical or asymmetrical encryption using NaCL.
+
+Introduction
+
Encryption is done 32k blockwise using an ephemeral key.
+
If using asymmetrical encryption the ephemeral key is encrypted asymmetrically using Curve25519 for all recipients and added to the output.
+
If sign+crypt is requested, a hash of the clear content plus the recipient list will be made and signed. That signature will be encrypted using the ephemeral key as well and appended to the output.
+
For each encryption cycle (per block) a unique nonce will be used.
+
+Encrypted Output Format
+
Encrypted output will always written as binary files. No armoring supported yet. The encryption process works as this:
+
+
generate a random symetric 32 byte key B<S>
+
encrypt it asymetrically for each recipient using a unique nonce (B<R>)
+
encrypt the input file 32k blockwise using the symetric key
+
+
Symmetric encryption works the very same with the recipient stuff left out.
+
Formal format description, asymmetric encrypted files:
+
+---------------------------------------------------------+
+ | 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 |
+ +-------------|--------|----------------------------------+
+
The following will be Left out 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 calculated using public key encryption using 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.
This function is used internally and normally a user doesn't need to use it. However, from time to time there maybe the requirement to work with raw NaCL crypto_box() output. This function adds the neccessary padding and it uses PCP key structures.
+
Parameters
+
+
[in]
secret
The secret key structure from the sender.
+
[in]
pub
The public key structure from the recipient.
+
[in]
cipher
The encrypted message.
+
[in]
ciphersize
The size in bytes of the encrypted message.
+
[out]
dsize
A pointer which will be set to the size of the decrypted result if successful.
+
+
+
+
Returns
Returns an allocated unsigned char array of the size csize which contains the encrypted result. In case of an error, it returns NULL sets csize to 0. Use fatals_ifany() to check for errors.
This function is used internally and normally a user doesn't need to use it. However, from time to time there maybe the requirement to work with raw NaCL crypto_box() output. This function adds the neccessary padding and it uses PCP key structures.
+
Parameters
+
+
[in]
secret
The secret key structure from the sender.
+
[in]
pub
The public key structure from the recipient.
+
[in]
message
The clear unencrypted message.
+
[in]
messagesize
The size in bytes of the message.
+
[out]
csize
A pointer which will be set to the size of the encrypted result if successful.
+
+
+
+
Returns
Returns an allocated unsigned char array of the size csize which contains the encrypted result. In case of an error, it returns NULL sets csize to 0. Use fatals_ifany() to check for errors.
This function decrypts a stream 32k+16-blockwise using a given ephemeral key. Usually compute this key using the pcp_scrypt() function. If not called directly, the key have been extracted from the recipient list.
+
Uses crypto_secret_box_open() for each 32k+16-block with a random nonce for each.
+
Parameters
+
+
[in]
in
Stream to read the data to decrypt from.
+
[out]
out
Stream to write decrypted result to.
+
[in]
symkey
Ephemeral key to use for decryption.
+
recverify
Flag to indicate sign+crypt. If 1 it tries to verify a signature, otherwise not.
+
+
+
+
Returns
Returns the size of the output written to the output stream or 0 in case of errors.
Generate a detached signature from a stream in 32k block mode.
+
This function reads blockwise from the stream in and generates a hash of the contents of the stream. It then signs that hash and writes the hash and the signature to the output stream out.
+
Parameters
+
+
[in]
in
Stream to read from.
+
[out]
out
Stream to write to.
+
[in]
s
Pointer to secret key.
+
+
+
+
Returns
Returns the size of the detached signature written or 0 in case of errors. Check fatals_if_any().
Verify a detached signature from a stream in 32k block mode.
+
This function reads blockwise from the stream in and generates a hash of the contents of the stream. It then reads the signature from the stream sigfd and verifies the signature from it using p->edpub and compares the signature hash with the hash it calculated from the signed content.
+
Parameters
+
+
[in]
in
Stream to read from.
+
[in]
sigfd
Stream containing the detached signature.
+
[in]
p
Pointer to public key structure.
+
+
+
+
Returns
Returns a pointer to a public key which were used to verify the signature or NULL if an error occurred. Check fatals_if_any().
This function reads blockwise from the stream in and generates a hash of the contents of the stream. It outputs the stream to out, also blockwise and appends the signature afterwards, which consists of the hash+nacl-signature.
+
Parameters
+
+
[in]
in
Stream to read from.
+
[out]
out
Stream to write to.
+
[in]
s
Pointer to secret key.
+
[in]
z85
Flag which indicates if to create an armored signature or not. 1=armored, 0=raw.
+
+
+
+
Returns
Returns the number of bytes written to the output stream.
The signature must contain the message+nacl signature (with size crypto_sign_BYTES).
+
Parameters
+
+
[in]
signature
Message+signature.
+
[in]
siglen
Size of message+signature.
+
[in]
p
Pointer to public key structure.
+
+
+
+
Returns
If the signature verifies return the raw message with the signature removed (size: siglen - crypto_sign_BYTES), returns NULL in case of errors. Check fatals_if_any().
Verify a signature from a stream in 32k block mode.
+
This function reads blockwise from the stream in and generates a hash of the contents of the stream. While reading from the stream it extracts the appended signature (hash+sig). It then verifies the signature using p->edpub and compares the signature hash with the hash it calculated from the signed content.
+
The parameter p can be NULL. In this case the function loops through the global public key hash pcppubkey_hash to find a public key which is able to verify the signature.
+
Parameters
+
+
[in]
in
Stream to read from.
+
[in]
p
Pointer to public key structure.
+
+
+
+
Returns
Returns a pointer to a public key which were used to verify the signature or NULL if an error occurred. Check fatals_if_any().
Verify a signature of size siglen using p->masterpub.
+
The signature must contain the message+nacl signature (with size crypto_sign_BYTES).
+
Parameters
+
+
[in]
signature
Message+signature.
+
[in]
siglen
Size of message+signature.
+
[in]
p
Pointer to public key structure.
+
+
+
+
Returns
If the signature verifies return the raw message with the signature removed (size: siglen - crypto_sign_BYTES), returns NULL in case of errors. Check fatals_if_any().
+
+
+
+
+
+
+Generated on Thu Feb 20 2014 19:59:14 for libpcp by
+
+ 1.8.2
+
+
+
diff --git a/man/html/group__FATALS.html b/man/html/group__FATALS.html
new file mode 100644
index 0000000..7429fd0
--- /dev/null
+++ b/man/html/group__FATALS.html
@@ -0,0 +1,221 @@
+
+
+
+
+
+libpcp: FATALS
+
+
+
+
+
+
+
Libpcp uses the uthash system to maintain lists of keys. There's one hash per key type. The hash has the same type as the key structure itself, but is global.
This function generates a 24 byte nonce used for cryptographic functions. It allocates the memory and the caller is responsible to clear and free() it after use.
+
Returns
Returns a pointer to a 24 byte unsigned char array.
This function calculates 2 JEN Hashes: one from the 'pub' field and one from the 'edpub' field. It the puts them together into a newly allocated char pointer of 17 bytes length as hex, terminated with a 0.
+
The key-id is supposed to be collision save, but there's no guarantee. However, it's used locally only, it wont be transmitted over the network and it's not part of any exported packet.
+
Parameters
+
+
[in]
k
The secret key structure.
+
+
+
+
Returns
Returns a char pointer containing the key-id string.
The given passphrase will be used to calculate an encryption key using the scrypt() function.
+
The encryption key will be used to decrypt the 'encrypted' field of the structure. If it works, the result will be dissected and put into the correspondig secret key fields.
+
The data structure will be modified directly, no new memory will be allocated.
+
The caller is responsible to clear the passphrase right after use and free() it as soon as possible.
+
Parameters
+
+
[in,out]
key
The secret key structure.
+
[in]
passphrase
The passphrase used to decrypt the key.
+
+
+
+
Returns
Returns a pointer to the decrypted key structure or NULL in case of an error. Use fatals_ifany() to catch them.
The given passphrase will be used to calculate an encryption key using the scrypt() function.
+
The secret keys will be concatenated and encrypted, the result will be put into the 'encrypted' field. The first byte of each secret key field will be set to 0 to indicate the key is encrypted.
+
The data structure will be modified directly, no new memory will be allocated.
+
The caller is responsible to clear the passphrase right after use and free() it as soon as possible.
+
Parameters
+
+
[in,out]
key
The secret key structure.
+
[in]
passphrase
The passphrase used to encrypt the key.
+
+
+
+
Returns
Returns a pointer to the encrypted key structure or NULL in case of an error. Use fatals_ifany() to catch them.
This functions originally appeared in OpenSSH rev 1.70, comitted by Alexander von Gernler, published under the BSD license.
+
Human beings are bad at memorizing numbers, especially large numbers, but we are very good at recognizing images. This function calculates an ascii art image of a public key, which the user shall always see, when used. If the image changes, the user would immediately recognize the change, even unconsciously.
+
Sample random art image from the following public key:
Check if an error occurred during a read or write operation.
+
+
+
Detailed Description
+
I/O wrapper for files or buffers.
+
Simple wrapper around FILE streams or Buffers, depending how the user initialized them. The Pcpstream object behaves always the same and it doesn't matter how it's backed.
+
We use it in the lib, e.g. in the crypto routines. That way we can support blockwise crypto on buffers or files.
+
Streams are, just like iostreams in c++, either output or input mode.
Use this function to access the underlying Buffer object of an output stream to access the contents written to it. Only usefull if the stream have been initialized with ps_new_outbuffer().
This function can be used to check if there are no more bytes to read. This will happen if we reach EOF with a FILE backed stream or buffer_done() with a Buffer backed stream.
Read bytes into the given buffer from the current stream.
+
This function reads 'readbytes' bytes from the stream into given buf. The buffer needs to be properly allocated by the caller in advance to have at least readbytes len.
+
Sets eof=1 if end of file or end of buffer has been reached.
+
Sets err=1 if an error occurred, fatals() maybe set, or errno.
RFC4880 alike public key export with some modifications.
+
RFC4880 alike public key export with the following modifications:
+
+
Key material is native to us and not specified in the rfc for curve25519/ed25519. Therefore we're doing it like so: 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
+
+
+
The various cipher (algorithm) id's are unspecified for our native ciphers. Therefore I created them, starting at 33 (afaik 22 is the last officially assigned one). Once those cipher numbers become official, I'll use them instead of my own.
+
+
+
The exported public key packet contains a signature. We're filling out all required fields. A signature has a variable number of sig sub packets. We use only these types:
2 = Signature Creation Time (4 byte)
+ 3 = Signature Expiration Time (4 byte)
+ 9 = Key Expiration Time (4 bytes)
+ 20 = Notation Data (4 byte flags, N bytes name+value)
+ 27 = Key Flags (1 byte, use 0x02, 0x08 and 0x80
+
+
+
+
We use 3 notation fields: "owner", which contains the owner name, if set "mail", which contains the emailaddress, if set "serial", which contains the 32bit serial number
+
+
+
The actual signature field consists of the blake2 hash of (mp|sp|cp|keysig) followed by the nacl signature. However, we do not put an extra 16byte 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.
+
+
+
The mp keypair will be used for signing. The recipient can verify the signature, since mp is included.
+
+
+
While we put expiration dates for the key and the signature into the export as the rfc demands, we ignore them. Key expiring is not implemented in PCP yet.
+
+
So, a full pubkey export looks like this
+
version
+ ctime
+ cipher
+ 3 x raw keys \
+ sigheader > calc hash from this
+ sigsubs (header+data) /
+ hash
+ signature
+
We use big-endian always.
+
Unlike RC4880 public key exports, we're using 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.
The key sig blob will be saved in the Vault if we import a public key unaltered, so we can verify the signature at will anytime. When exporting a foreign public key, we will just put out that key sig blob to the export untouched.
+
Currently PCP only support self-signed public key exports.
+
We only support one key signature per key. However, it would be easily possible to support foreign keysigs as well in the future.
+
Parameters
+
+
sk
a secret key structure of type pcp_key_t. The secret keys in there have to be already decrypted.
+
+
+
+
Returns
the function returns a Buffer object containing the binary blob in the format described above.
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 contains 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
+
Parameters
+
+
sk
a secret key structure of type pcp_key_t. The secret keys in there have to be already decrypted.
+
passphrase
the passphrase to be used to encrypt the export, a null terminated char array.
+
+
+
+
Returns
the function returns a Buffer object containing the binary blob in the format described above.
This function determines the size of the item to write based on the given type. It converts the internal structure to a binary blob and converty multibyte values to big endian.
+
It copies the given vault file to a temporary vault file, adds the item and if this went ok, copies the temporary file back to the original location. It then re-calculates the vault checksum and puts it into the vault header.
If the vault is in unsafed state, write everything to disk and close the vault. Before overwriting the current vault file a backup will be made. If anything fails during writing the backup file will be retained and the error message will contain the filename of the backup file, so that the user doesn't loose data.
Each item will be converted put into the aproprieate structure, multibyte values will be converted to host endianess. It also calculates the checksum of the vault contents and compares it with the one stored in the vault header. If it doesn't match an error will be thrown.
+
Parameters
+
+
[out]
vault
The vault object.
+
+
+
+
Returns
Returns 0 on success or -1 in case of errors. Check fatals_if_any().
The Z85 encoding format is described here: ZeroMQ Spec.32. It's part of ZeroMQ. Z85 is based on ASCII85 with a couple of modifications (portability, readability etc).
+
To fulfil the requirements of the ZeroMQ Z85 functions, PCP 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.
+
Function Documentation
+
+
+
+
+
+
unsigned char* pcp_padfour
+
(
+
unsigned char *
+
src,
+
+
+
+
+
size_t
+
srclen,
+
+
+
+
+
size_t *
+
dstlen
+
+
+
+
)
+
+
+
+
+
+
Zero-pad some input data.
+
This function allocates new memory for the returned data. It puts the original pointer into it and adds a number of zeros so that the result has a size divisable by 4.
+
Parameters
+
+
[in]
src
Unpadded data.
+
[in]
srclen
Size of unpadded data.
+
[in]
dstlen
Returned size of padded data (pointer to int).
+
+
+
+
Returns
Returns a pointer to the padded data.
+
+
+
+
+
+
+
+
+
char* pcp_readz85file
+
(
+
FILE *
+
infile
)
+
+
+
+
+
+
Read a Z85 encoded file.
+
Reads a file and returns the raw Z85 encoded string. It ignores newlines, comments and Headerstrings.
+
Parameters
+
+
[in]
infile
FILE stream to read from.
+
+
+
+
Returns
Raw Z85 encoded string with comments, headers and newlines removed.
+
+
+
+
+
+
+
+
+
char* pcp_readz85string
+
(
+
unsigned char *
+
input,
+
+
+
+
+
size_t
+
bufsize
+
+
+
+
)
+
+
+
+
+
+
Read a Z85 encoded string.
+
Parses the given input string and returns the raw Z85 encoded string. It ignores newlines, comments and Headerstrings.
+
Parameters
+
+
[in]
input
Z85 encoded string.
+
[in]
bufsize
Size of the string.
+
+
+
+
Returns
Raw Z85 encoded string with comments, headers and newlines removed.
+
+
+
+
+
+
+
+
+
size_t pcp_unpadfour
+
(
+
unsigned char *
+
src,
+
+
+
+
+
size_t
+
srclen
+
+
+
+
)
+
+
+
+
+
+
Unpad padded input data.
+
It just calculates the size of the unpadded result (size - all trailing zeroes). Doesn't allocate any memory or modify anything.
+
Parameters
+
+
[in]
src
Padded data.
+
[in]
srclen
Size of padded data.
+
+
+
+
Returns
Returns the unpadded size of the data.
+
+
+
+
+
+
+
+
+
unsigned char* pcp_z85_decode
+
(
+
char *
+
z85block,
+
+
+
+
+
size_t *
+
dstlen
+
+
+
+
)
+
+
+
+
+
+
Decode data from Z85 encoding.
+
The input z85block may contain newlines which will be removed.
+
Parameters
+
+
[in]
z85block
The Z85 encoded string.
+
[in]
dstlen
Returned size of decoded data (pointer to int).
+
+
+
+
Returns
Returns a newly allocated pointer to the decoded data. If decoding failed, returns NULL. Check fatals_if_any().
+
+
+
+
+
+
+
+
+
char* pcp_z85_encode
+
(
+
unsigned char *
+
raw,
+
+
+
+
+
size_t
+
srclen,
+
+
+
+
+
size_t *
+
dstlen
+
+
+
+
)
+
+
+
+
+
+
Encode data to Z85 encoding.
+
Beside Z85 encoding it also adds a newline everiy 72 characters.
+
Parameters
+
+
[in]
raw
Pointer to raw data.
+
[in]
srclen
Size of the data.
+
[in]
dstlen
Returned size of encoded data (pointer to int).
+
+
+
+
Returns
Returns a string (char array) containing the Z85 encoded data.
+
+
+
+
+
+
+Generated on Thu Feb 20 2014 19:59:14 for libpcp by
+
+ 1.8.2
+
+
+
diff --git a/man/html/index.html b/man/html/index.html
new file mode 100644
index 0000000..efc1d90
--- /dev/null
+++ b/man/html/index.html
@@ -0,0 +1,130 @@
+
+
+
+
+
+libpcp: Main Page
+
+
+
+
+
+
+
This is the API documentation of libpcp, the library behind Pretty Curved Privacy (pcp). The library can be used independently of pcp to manage keys and to encrypt or sign files or buffers.
_pcp_buffer
+