scip/pcp
1
0
Fork 0
mirror of https://codeberg.org/scip/pcp.git synced 2025-12-18 04:10:57 +01:00
Code Issues Packages Projects Releases Wiki Activity

started documenting the api.

Browse Source
This commit is contained in:
git@daemon.de
2014-02-17 17:05:32 +01:00
parent 1afb5cc3d7
commit be867bdc26
5 changed files with 1695 additions and 191 deletions
Download Patch File Download Diff File Expand all files Collapse all files

523
include/pcp/buffer.h
View File

@@ -19,18 +19,6 @@
You can contact me by mail: <tom AT vondein DOT org>.
*/
/*
Flexible buffer management, idea from openssh/buffer.c.
This 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.
*/
#ifndef HAVE_PCP_BUFFER_H
#define HAVE_PCP_BUFFER_H
@@ -40,116 +28,551 @@
#include "util.h"
#include "defines.h"
/**
* \defgroup Buffer Buffer, a flexible buffer management class.
* @{
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.
*/
/** \struct _pcp_buffer
A flexible buffer object wich automatically resizes, if neccessary.
*/
struct _pcp_buffer {
char *name; /* just for convenience in error messages and the
like, so we know which buffer cause trouble */
uint8_t allocated;
size_t blocksize;
size_t size;
size_t offset; /* read position */
size_t end; /* write position, data end */
uint8_t isstring; /* treat as char array */
void *buf;
char *name; /**< just for convenience in error messages and the like, so we know which buffer cause trouble */
uint8_t allocated; /**< marks the buffer as allocated */
size_t blocksize; /**< the blocksize to use when resizing, also used for initial malloc() */
size_t size; /**< stores the current allocated size of the object */
size_t offset; /**< current read position */
size_t end; /**< current write position, data end. maybe less than size. */
uint8_t isstring; /**< treat as char array/string */
void *buf; /**< the actual storage buffer */
};
/** The name used everywhere */
typedef struct _pcp_buffer Buffer;
/* create a new buffer, initially alloc'd to blocksize and zero-filled */
/** Create a new buffer.
Create a new buffer, initially alloc'd to blocksize and zero-filled.
\param[in] blocksize Initial blocksize. The smaller the more often
the buffer will be resized. Choose with care.
\param[in] name A name for the Buffer. Just used for debugging purposes or in error messages.
\return Returns a new Buffer object.
*/
Buffer *buffer_new(size_t blocksize, char *name);
/* same, but enable isstring */
/** Create a new buffer.
Create a new buffer, initially alloc'd to a blocksize of 32 bytes and zero-filled.
The buffer will be a string buffer. See buffer_get_str().
\param[in] name A name for the Buffer. Just used for debugging purposes or in error messages.
\return Returns a new Buffer object.
*/
Buffer *buffer_new_str(char *name);
/* initialize buffer vars */
void buffer_init(Buffer *b, size_t blocksize, char *name);
/* zero the buffer and free it, if allocated */
/** Clears and frees the Buffer.
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).
\param[in] b The Buffer object.
*/
void buffer_free(Buffer *b);
/* zero the buffer, reset counters, always called from buffer_free() */
/** Clears the Buffer.
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.
\param[in] b The Buffer object.
*/
void buffer_clear(Buffer *b);
/* put read offset to start */
/** Put read offset back to start.
This function sets the read offset counter back to 0 (start
of the buffer).
\param[in] b The Buffer object.
*/
void buffer_rewind(Buffer *b);
/* add data to the buffer, memorize end position */
/** Add data to the buffer.
Adds data of the size len to the buffer and resizes the
buffer, if neccessary. The write position ('end' field)
will be updated accordingly.
Data will be copied, you can free() the given pointer after copying..
\param[in] b The Buffer object.
\param[out] data Arbitrary data to add to the Buffer.
\param[in] len The size of the data to add in Bytes.
*/
void buffer_add(Buffer *b, const void *data, size_t len);
/* the same but use another buffer as source */
/** Add data to the buffer.
Adds data from the given Buffer src to the buffer and resizes the
buffer, if neccessary. The write position ('end' field)
will be updated accordingly.
Data will be copied, you can buffer_free() the given src Buffer after the copying.
\param[out] dst The destination Buffer object to copy data into.
\param[in] src The source Buffer object to copy data from.
*/
void buffer_add_buf(Buffer *dst, Buffer *src);
/* add a string, support printf style */
/** Add a formated string to the buffer.
Use printf() like syntax to add a formatted string
to the buffer. Refer to the documentation of printf() for
details.
Data will be copied, you can free() the given format string and params after copying.
Example:
@code
Buffer *x = buffer_new_str("test");
buffer_add_str(x, "There are %d elements left in %s\n", 4, "list");
@endcode
\param[in] b The Buffer object.
\param[in] fmt The printf() compatible format description.
\param[in] ... A variable number of arguments for the format string.
*/
void buffer_add_str(Buffer *b, const char * fmt, ...);
/* add some binary data to the buffer, but as hex string */
/** Add data as hex string to the buffer.
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..
\param[in] b The Buffer object.
\param[in] data Arbitrary data to add as hex into the Buffer.
\param[in] len The size of the data to add in Bytes.
*/
void buffer_add_hex(Buffer *b, void *data, size_t len);
/* resize the buffer if necessary */
/* resize the buffer if necessary, used internally only */
void buffer_resize(Buffer *b, size_t len);
/* return true if there are no more bytes to read */
/** Tell if there are no more bytes to read.
This functions tells if the EOF of the buffer is reached
during read operations (no more data to read left).
\param[in] b The Buffer object.
\return Returns 1 of EOF has been reached or 0 if there are more data left to read.
*/
int buffer_done(Buffer *b);
/* get some chunk of data from the buffer, starting from offset til len */
/** Read some chunk of data from the Buffer.
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.
*/
size_t buffer_get_chunk(Buffer *b, void *buf, size_t len);
/* return the whole buffer contents */
/** Read the whole Buffer content.
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.
\param[in] b The Buffer object to read from.
\return Pointer to the buffer data storage.
*/
unsigned char *buffer_get(Buffer *b);
/* access the buffer content as string (char *) the returned pointer
points to b->buf and should not be free'd directly*/
/** Read the whole Buffer content as string.
Access the Buffer content as string (char *).
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.
Sample usage:
@code
[..]
fprintf(stdout, "Our buffer content: %s\n", buffer_get_str(b));
@endcode
\param[in] b The Buffer object to read from.
\return Pointer to the buffer data storage.
*/
char *buffer_get_str(Buffer *b);
/* fetch whatever is left in 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:
@code
AAAABBBBCCCC
@endcode
Then:
@code
[..]
unsigned char g[4];
unsigned char *r = NULL;
buffer_get_chunk(b, g, 4); // => g now contains 'AAAA'
size_t rs = buffer_left(b); // => rs = 8
r = buffer_get_remainder(b); // => r now contains 'BBBBCCCC' and has a size of 8
memset(r, 0, rs); // zerofill r
free(r); // done with it
@endcode
\param[in] b The Buffer object to read from.
\return Pointer to the remaining chunk of data (copy).
*/
unsigned char *buffer_get_remainder(Buffer *b);
/* same as buffer_get() but fetch some data chunk from somewhere
in the middle of the buffer */
/** Read some data inside the Buffer.
Same as buffer_get() but fetch some data chunk from somewhere
in the middle of the buffer.
The returned pointer has to be allocated by the caller to
at least a size of len bytes.
The read offset will be left untouched by this function.
Example: suppose you've got a buffer with the following content:
@code
AAAABBBBCCCC
@endcode
Then:
@code
[..]
unsigned char g[4];
buffer_extract(b, g, 4, 4); // => g now contains 'BBBB'
@endcode
\param[in] b The Buffer object to read from.
\param[out] buf The buffer to copy data to.
\param[in] offset Where to start copying.
\param[in] len How mush data to copy.
\return Returns the size of bytes read. Returns 0 in case of
an overflow, which can be catched with fatals_ifany().
*/
size_t buffer_extract(Buffer *b, void *buf, size_t offset, size_t len);
/* dump the buffer contents to stderr */
/** Dump the Buffer contents to stderr in hex form.
\param[in] b The Buffer object to dump.
*/
void buffer_dump(const Buffer *b);
/* print buffer counters to stderr */
/** Print Buffer counters to stderr.
\param[in] b The Buffer object to print infos about.
*/
void buffer_info(const Buffer *b);
/* tell how much data there is in the buffer */
/** 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.
\param[in] b The Buffer object to get the size from.
\return The number of bytes stored in the Buffer.
*/
size_t buffer_size(const Buffer *b);
/* tell how much data is left to read */
/** Tell how much data is left to read in the Buffer.
Use this function to check if it's ok to read more
bytes from to buffer to avoid buffer overflows.
Example: suppose you've got a buffer with the following content:
@code
AAAABBBBCCCC
@endcode
Then:
@code
[..]
unsigned char g[4];
unsigned char x[16];
buffer_get_chunk(b, g, 4); // => g now contains 'BBBB'
if(buffer_left(b) >= 16) // => will return 8 and therefore fail
buffer_get_chunk(b, x, 16);
else
printf("not enough data"); // => will be printed
@endcode
\param[in] b The Buffer object to get the size from.
\return The number of bytes left to read from the Buffer.
*/
size_t buffer_left(const Buffer *b);
/* same as get_chunk, but return numbers directly */
/** Read 1 byte (8 bit) number from a Buffer.
\param[in] b The Buffer object to read from.
\return a uint8_t.
*/
uint8_t buffer_get8(Buffer *b);
/** Read 2 bytes (16 bit) number from a Buffer.
\param[in] b The Buffer object to read from.
\return a uint16_t.
*/
uint16_t buffer_get16(Buffer *b);
/** Read 4 byte (32 bit) number from a Buffer.
\param[in] b The Buffer object to read from.
\return a uint32_t.
*/
uint32_t buffer_get32(Buffer *b);
/** Read 8 byte (64 bit) from a Buffer.
\param[in] b The Buffer object to read from.
\return a uint64_t.
*/
uint64_t buffer_get64(Buffer *b);
/* same, but convert to native endian before return */
/** Read 2 bytes (16 bit) number from a Buffer, converted to host endian.
\param[in] b The Buffer object to read from.
\return a uint16_t.
*/
uint16_t buffer_get16na(Buffer *b);
/** Read 4 byte (32 bit) number from a Buffer, converted to host endian.
\param[in] b The Buffer object to read from.
\return a uint32_t.
*/
uint32_t buffer_get32na(Buffer *b);
/** Read 8 byte (64 bit) from a Buffer, converted to host endian.
\param[in] b The Buffer object to read from.
\return a uint64_t.
*/
uint64_t buffer_get64na(Buffer *b);
/* access the last byte(s) as numbers directly, save typing,
in contrast to buffer_get() it doesn't increment offset */
/** Read the last 1 byte (8 bit) number from a Buffer.
Doesn't increment offset.
\param[in] b The Buffer object to read from.
\return a uint8_t.
*/
uint8_t buffer_last8(Buffer *b);
/** Read the last 2 byte (16 bit) number from a Buffer.
Doesn't increment offset.
\param[in] b The Buffer object to read from.
\return a uint16_t.
*/
uint16_t buffer_last16(Buffer *b);
/** Read the last 4 byte (32 bit) number from a Buffer.
Doesn't increment offset.
\param[in] b The Buffer object to read from.
\return a uint32_t.
*/
uint32_t buffer_last32(Buffer *b);
/** Read the last 8 byte (64 bit) number from a Buffer.
Doesn't increment offset.
\param[in] b The Buffer object to read from.
\return a uint64_t.
*/
uint64_t buffer_last64(Buffer *b);
/* read from a file directly into a buffer object */
/** Read data from a file directly into a Buffer.
This function reads in len bytes from the FILE stream
'in' into the Buffer. The file must already be opened
by the caller.
\param[in,out] b The Buffer object to read from.
\param[in] in The FILE stream to read from.
\param[in] len The number of bytes to read.
\return 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.
*/
size_t buffer_fd_read(Buffer *b, FILE *in, size_t len);
/* write numbers as binary into the buffer */
/** Write a 1 byte (8 bit) number in binary form into the buffer.
\param[out] b The Buffer object to write to.
\param[in] v The uint8_t to write to the buffer.
*/
void buffer_add8(Buffer *b, uint8_t v);
/** Write a 2 byte (16 bit) number in binary form into the buffer.
\param[out] b The Buffer object to write to.
\param[in] v The uint16_t to write to the buffer.
*/
void buffer_add16(Buffer *b, uint16_t v);
/** Write a 4 byte (32 bit) number in binary form into the buffer.
\param[out] b The Buffer object to write to.
\param[in] v The uint32_t to write to the buffer.
*/
void buffer_add32(Buffer *b, uint32_t v);
/** Write a 8 byte (64 bit) number in binary form into the buffer.
\param[out] b The Buffer object to write to.
\param[in] v The uint64_t to write to the buffer.
*/
void buffer_add64(Buffer *b, uint64_t v);
/* the same, but convert to big-endian before doing so */
/** Write a 2 byte (16 bit) number in binary form into the buffer, converted to big endian.
\param[out] b The Buffer object to write to.
\param[in] v The uint16_t to write to the buffer.
*/
void buffer_add16be(Buffer *b, uint16_t v);
/** Write a 4 byte (32 bit) number in binary form into the buffer, converted to big endian.
\param[out] b The Buffer object to write to.
\param[in] v The uint32_t to write to the buffer.
*/
void buffer_add32be(Buffer *b, uint32_t v);
/** Write a 8 byte (64 bit) number in binary form into the buffer, converted to big endian.
\param[out] b The Buffer object to write to.
\param[in] v The uint64_t to write to the buffer.
*/
void buffer_add64be(Buffer *b, uint64_t v);
#endif // HAVE_PCP_BUFFER_H
/**@}*/

49
include/pcp/defines.h
View File

@@ -92,21 +92,62 @@ typedef unsigned int qbyte; /* Quad byte = 32 bits */
#define PCP_RFC_CIPHER 0x21 /* curve25519+ed25519+poly1305+salsa20+blake2 */
/**
* \defgroup FATALS global variables and functions for error handling.
* @{
*/
/* error handling */
/** \var PCP_ERR
Global variable holding the last error message.
Can be retrieved with fatals_ifany().
*/
extern char *PCP_ERR;
/** \var PCP_ERRSET
Global variable indicating if an error occurred.
*/
extern byte PCP_ERRSET;
/** \var PCP_EXIT
Exitcode for the pcp commandline utility.
*/
extern int PCP_EXIT;
/* set error */
/** Set an error message.
This function gets a printf() like error message,
which it stores in the global PCP_ERR variable
and sets PCP_ERRSET to 1.
\param[in] fmt printf() like format description.
\param[in] ... format parameters, if any.
*/
void fatal(const char * fmt, ...);
/* fetch error */
/** Prints error messages to STDERR, if there are some.
FIXME: add something like this which returns the
message.
*/
void fatals_ifany();
/* reset */
/** Reset the error variables.
This can be used to ignore previous errors.
Use with care.
*/
void fatals_reset();
/* free mem */
/** Cleans up memory allocation of global error variables.
*/
void fatals_done();
#endif /* _DEFINES_H */
/**@}*/

325
include/pcp/key.h
View File

@@ -40,11 +40,21 @@
#include "scrypt.h"
#include "keysig.h"
/*
/**
* \defgroup PCPKEY PCP public and secret key functions
* @{
*/
/** \struct _pcp_key_t
PCP private key structure. Most fields are self explanatory.
Some notes:
'encrypted' contains the encrypted ed25519 secret key. If it's set,
'encrypted' contains the encrypted secret keys (contatenated mastersecret,
secret and edsecret). If it's set,
the field 'secret' which contains the clear secret key will
be zeroed with random values, the first byte will be 0. Same
for the field 'edsecret'.
@@ -76,41 +86,55 @@
*/
struct _pcp_key_t {
byte masterpub[32];
byte mastersecret[64];
byte pub[32];
byte secret[32];
byte edpub[32];
byte edsecret[64];
byte nonce[24];
byte encrypted[176]; /* both sign+ed+curve encrypted */
char owner[255];
char mail[255];
char id[17];
uint8_t type;
uint64_t ctime; /* 8 */
uint32_t version; /* 4 */
uint32_t serial; /* 4 */
byte masterpub[32]; /**< ED25519 master public key signing key */
byte mastersecret[64]; /**< ED25519 master secret key signing key */
byte pub[32]; /**< Curve25519 encryption public key */
byte secret[32]; /**< Curve25519 encryption secret key */
byte edpub[32]; /**< ED25519 public signing key */
byte edsecret[64]; /**< ED25519 secret signing key */
byte nonce[24]; /**< random nonce used to encrypt secret keys */
byte encrypted[176]; /**< concatenated and encrypted secret keys */
char owner[255]; /**< the key owner, string */
char mail[255]; /**< mail address of the owner, string */
char id[17]; /**< key-id, used internally only, jenhash of public keys */
uint8_t type; /**< key type: MASTER_SECRET or SECRET */
uint64_t ctime; /**< creation time, epoch */
uint32_t version; /**< key version */
uint32_t serial; /**< serial number of the key, randomly generated */
UT_hash_handle hh;
};
/** Typedef for secret keys */
typedef struct _pcp_key_t pcp_key_t;
/** \struct _pcp_pubkey_t
PCP public key structure.
This structure contains a subset of the pcp_key_t structure
without the secret and nonce fields.
*/
struct _pcp_pubkey_t {
byte masterpub[32];
byte sigpub[32];
byte pub[32];
byte edpub[32];
char owner[255];
char mail[255];
char id[17];
uint8_t type;
uint64_t ctime;
uint32_t version;
uint32_t serial;
uint8_t valid;
byte signature[crypto_generichash_BYTES_MAX + crypto_sign_BYTES];
byte masterpub[32]; /**< ED25519 master public key signing key */
byte sigpub[32]; /**< ED25519 public signing key */
byte pub[32]; /**< Curve25519 encryption public key */
byte edpub[32]; /**< ED25519 public signing key (FIXME: huh? 2 of them???) */
char owner[255]; /**< the key owner, string */
char mail[255]; /**< mail address of the owner, string */
char id[17]; /**< key-id, used internally only, jenhash of public keys */
uint8_t type; /**< key type: MASTER_SECRET or SECRET */
uint64_t ctime; /**< creation time, epoch */
uint32_t version; /**< key version */
uint32_t serial; /**< serial number of the key, randomly generated */
uint8_t valid; /**< 1 if import signature verified, 0 if not */
byte signature[crypto_generichash_BYTES_MAX + crypto_sign_BYTES]; /**< raw binary blob of pubkey export signature */
UT_hash_handle hh;
};
/** Typedef for public keys */
typedef struct _pcp_pubkey_t pcp_pubkey_t;
/* the PBP public key format */
/* keys.mp+keys.cp+keys.sp+keys.name */
struct _pbp_pubkey_t {
@@ -122,9 +146,6 @@ struct _pbp_pubkey_t {
char name[1024];
};
typedef struct _pcp_key_t pcp_key_t;
typedef struct _pcp_pubkey_t pcp_pubkey_t;
typedef struct _pbp_pubkey_t pbp_pubkey_t;
/*
@@ -145,25 +166,212 @@ typedef struct _pcp_rec_t pcp_rec_t;
#define PCP_RAW_PUBKEYSIZE sizeof(pcp_pubkey_t) - sizeof(UT_hash_handle)
/** Generate a new key structure.
void pcp_cleanhashes();
Owner and mail field must be filled by the caller.
Memory for the returned pointer will be allocated
by the function.
\return Returns pointer to new pcp_key_t structure.
*/
pcp_key_t *pcpkey_new ();
void pcp_keypairs(byte *msk, byte *mpk, byte *csk, byte *cpk, byte *esk, byte *epk);
/** Generate an ASCII art image of the public key.
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:
@code
c308455ed4cf0c140bf48bfb0d87c4999c66e823bbe74ff16e2a9adc8e770747
+----------------+
| .o.ooo. |
| o . o |
| . . = |
| . o + |
| . + |
| . |
| |
| |
+----------------+
@endcode
\param[in] k The public key structure.
\return Returns an allocated char pointer containing the ASCII art image.
The caller is responsible to free() it.
*/
char *pcppubkey_get_art(pcp_pubkey_t *k);
/** Generate an ASCII art image of the public key part of a secret key.
see pcppubkey_get_art() for details.
\param[in] k The secret key structure.
\return Returns an allocated char pointer containing the ASCII art image.
The caller is responsible to free() it.
*/
char *pcpkey_get_art(pcp_key_t *k);
pcp_key_t *pcpkey_encrypt(pcp_key_t *key, char *passphrase);
pcp_key_t *pcpkey_decrypt(pcp_key_t *key, char *passphrase);
pcp_pubkey_t *pcpkey_pub_from_secret(pcp_key_t *key);
char *pcp_getkeyid(pcp_key_t *k);
char *pcp_getpubkeyid(pcp_pubkey_t *k);
unsigned char *pcppubkey_getchecksum(pcp_pubkey_t *k);
unsigned char *pcpkey_getchecksum(pcp_key_t *k);
void pcp_inithashes();
/** Encrypt a secret key structure.
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.
\param[in,out] key The secret key structure.
\param[in] passphrase The passphrase used to encrypt the key.
\return Returns a pointer to the encrypted key structure or NULL
in case of an error. Use fatals_ifany() to catch them.
*/
pcp_key_t *pcpkey_encrypt(pcp_key_t *key, char *passphrase);
/** Decrypt a secret key structure.
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.
\param[in,out] key The secret key structure.
\param[in] passphrase The passphrase used to decrypt the key.
\return Returns a pointer to the decrypted key structure or NULL
in case of an error. Use fatals_ifany() to catch them.
*/
pcp_key_t *pcpkey_decrypt(pcp_key_t *key, char *passphrase);
/** Generate a public key structure from a given secret key structure.
This function extracts all required fields and fills a newly
allocated pcp_pubkey_t structure.
The caller is responsible to clear and free() it after use.
\param[in] key The secret key structure.
\return Returns a new pcp_pubkey_t structure.
*/
pcp_pubkey_t *pcpkey_pub_from_secret(pcp_key_t *key);
/** Calculate a key-id from public key fields.
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.
\param[in] k The secret key structure.
\return Returns a char pointer containing the key-id string.
*/
char *pcp_getkeyid(pcp_key_t *k);
/** Calculate a key-id from public key fields.
This does the same as pcp_getkeyid() but uses a pcp_pubkey_t
as input.
\param[in] k The public key structure.
\return Returns a char pointer containing the key-id string.
*/
char *pcp_getpubkeyid(pcp_pubkey_t *k);
/** Calculate a checksum of a public key.
This function calculates a 32 byte checksum of the
encryption public key part of the given pcp_pubkey_t
structure using crypto_hash_sha256.
The returned pointer will be allocated and it is the
responsibility of the caller to free() ist after use.
\param[in] k The public key structure.
\return Returns a pointer to an 32 byte unsigned char.
*/
unsigned char *pcppubkey_getchecksum(pcp_pubkey_t *k);
/** Calculate a checksum of a public key part of the given secret key.
See pcppubkey_getchecksum().
\param[in] k The secret key structure.
\return Returns a pointer to an 32 byte unsigned char.
*/
unsigned char *pcpkey_getchecksum(pcp_key_t *k);
/** Checks if a secret key structure is registered in the secret key hash.
Returns a pointer to a pcp_key_t structure if there
exists a secret key structure with the given id in the
secret key hash.
FIXME: needs to be moved to keyhash.h.
\param[in] id A null-terminated char pointer of 17 bytes containing a key-id.
\return Returns a pointer to a pcp_key_t struture or NULL if no key exists.
*/
pcp_key_t *pcpkey_exists(char *id);
/** Checks if a public key structure is registered in the public key hash.
Returns a pointer to a pcp_pubkey_t structure if there
exists a public key structure with the given id in the
public key hash.
FIXME: needs to be moved to keyhash.h.
\param[in] id A null-terminated char pointer of 17 bytes containing a key-id.
\return Returns a pointer to a pcp_pubkey_t struture or NULL if no key exists.
*/
pcp_pubkey_t *pcppubkey_exists(char *id);
pcp_key_t * key2be(pcp_key_t *k);
@@ -171,22 +379,45 @@ pcp_key_t *key2native(pcp_key_t *k);
pcp_pubkey_t * pubkey2be(pcp_pubkey_t *k);
pcp_pubkey_t *pubkey2native(pcp_pubkey_t *k);
/** Generate a nonce.
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.
\return Returns a pointer to a 24 byte unsigned char array.
*/
unsigned char * pcp_gennonce();
void pcpedit_key(char *keyid);
/* use scrypt() to create a key from a passphrase and a nonce */
/* use scrypt() to create a key from a passphrase and a nonce
FIXME: use pure scrypt() instead.
*/
unsigned char *pcp_derivekey(char *passphrase, unsigned char *nonce);
pcp_key_t *pcp_derive_pcpkey (pcp_key_t *ours, char *theirs);
/* FIXME: abandon and use Buffer instead */
void pcp_seckeyblob(void *blob, pcp_key_t *k);
void pcp_pubkeyblob(void *blob, pcp_pubkey_t *k);
void *pcp_keyblob(void *k, int type); /* allocates blob */
/** Make a sanity check of the given public key structure.
\param[in] key The public key structure.
\return Returns 1 if the sanity check succeeds, 0 otherwise.
Use fatals_ifany() to check why.
*/
int pcp_sanitycheck_pub(pcp_pubkey_t *key);
/** Make a sanity check of the given secret key structure.
\param[in] key The secret key structure.
\return Returns 1 if the sanity check succeeds, 0 otherwise.
Use fatals_ifany() to check why.
*/
int pcp_sanitycheck_key(pcp_key_t *key);
#endif /* _HAVE_PCP_KEYPAIR_H */
/**@}*/

250
include/pcp/mgmt.h
View File

@@ -43,8 +43,87 @@
/* key management api, export, import, yaml and stuff */
/**
* \defgroup PubKeyExport Key export functions
* @{
*/
/* RFC4880 alike public key export with some modifications:
/* various helper structs, used internally only */
struct _pcp_rfc_pubkey_header_t {
uint8_t version;
uint32_t ctime;
uint8_t cipher;
};
struct _pcp_rfc_pubkey_0x21_t {
byte sig_ed25519_pub[crypto_sign_PUBLICKEYBYTES];
byte ed25519_pub[crypto_sign_PUBLICKEYBYTES];
byte curve25519_pub[crypto_box_PUBLICKEYBYTES];
};
struct _pcp_rfc_pubkey_sigheader_0x21_t {
uint8_t version;
uint8_t type;
uint8_t pkcipher;
uint8_t hashcipher;
uint16_t numsubs;
};
struct _pcp_rfc_pubkey_sigsub_0x21_t {
uint32_t size;
uint8_t type;
};
typedef struct _pcp_rfc_pubkey_header_t rfc_pub_h;
typedef struct _pcp_rfc_pubkey_0x21_t rfc_pub_k;
typedef struct _pcp_rfc_pubkey_sigheader_0x21_t rfc_pub_sig_h;
typedef struct _pcp_rfc_pubkey_sigsub_0x21_t rfc_pub_sig_s;
struct _pcp_ks_bundle_t {
pcp_pubkey_t *p;
pcp_keysig_t *s;
};
typedef struct _pcp_ks_bundle_t pcp_ks_bundle_t;
#define EXP_PK_CIPHER 0x21
#define EXP_PK_CIPHER_NAME "CURVE25519-ED25519-POLY1305-SALSA20"
#define EXP_HASH_CIPHER 0x22
#define EXP_HASH_NAME "BLAKE2"
#define EXP_SIG_CIPHER 0x23
#define EXP_SIG_CIPHER_NAME "ED25519"
#define EXP_SIG_VERSION 0x01
#define EXP_SIG_TYPE 0x1F /* self signed */
/* sig sub notiation we support */
#define EXP_SIG_SUB_CTIME 2
#define EXP_SIG_SUB_SIGEXPIRE 3
#define EXP_SIG_SUB_KEYEXPIRE 9
#define EXP_SIG_SUB_NOTATION 20
#define EXP_SIG_SUB_KEYFLAGS 27
/* in armored mode, we're using the usual head+foot */
#define EXP_PK_HEADER "-----BEGIN ED25519-CURVE29915 PUBLIC KEY-----"
#define EXP_PK_FOOTER "------END ED25519-CURVE29915 PUBLIC KEY------"
#define EXP_SK_HEADER "-----BEGIN ED25519-CURVE29915 PRIVATE KEY-----"
#define EXP_SK_FOOTER "------END ED25519-CURVE29915 PRIVATE KEY------"
/* pubkey export formats */
#define EXP_FORMAT_NATIVE 1
#define EXP_FORMAT_PBP 2
#define EXP_FORMAT_YAML 3
#define EXP_FORMAT_C 4
#define EXP_FORMAT_PY 5
#define EXP_FORMAT_PERL 6
/** 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
@@ -119,107 +198,104 @@
We only support one key signature per key. However, it would be easily
possible to support foreign keysigs as well in the future.
-----------
Secret key are exported in proprietary format. We just encrypt the
whole structure symmetrically and prepend it with a nonce.
\param sk a secret key structure of type pcp_key_t. The secret keys
in there have to be already decrypted.
\return the function returns a Buffer object containing the binary
blob in the format described above.
*/
/* various helper structs, used internally only */
struct _pcp_rfc_pubkey_header_t {
uint8_t version;
uint32_t ctime;
uint8_t cipher;
};
struct _pcp_rfc_pubkey_0x21_t {
byte sig_ed25519_pub[crypto_sign_PUBLICKEYBYTES];
byte ed25519_pub[crypto_sign_PUBLICKEYBYTES];
byte curve25519_pub[crypto_box_PUBLICKEYBYTES];
};
struct _pcp_rfc_pubkey_sigheader_0x21_t {
uint8_t version;
uint8_t type;
uint8_t pkcipher;
uint8_t hashcipher;
uint16_t numsubs;
};
struct _pcp_rfc_pubkey_sigsub_0x21_t {
uint32_t size;
uint8_t type;
};
typedef struct _pcp_rfc_pubkey_header_t rfc_pub_h;
typedef struct _pcp_rfc_pubkey_0x21_t rfc_pub_k;
typedef struct _pcp_rfc_pubkey_sigheader_0x21_t rfc_pub_sig_h;
typedef struct _pcp_rfc_pubkey_sigsub_0x21_t rfc_pub_sig_s;
struct _pcp_ks_bundle_t {
pcp_pubkey_t *p;
pcp_keysig_t *s;
};
typedef struct _pcp_ks_bundle_t pcp_ks_bundle_t;
#define EXP_PK_CIPHER 0x21
#define EXP_PK_CIPHER_NAME "CURVE25519-ED25519-POLY1305-SALSA20"
#define EXP_HASH_CIPHER 0x22
#define EXP_HASH_NAME "BLAKE2"
#define EXP_SIG_CIPHER 0x23
#define EXP_SIG_CIPHER_NAME "ED25519"
#define EXP_SIG_VERSION 0x01
#define EXP_SIG_TYPE 0x1F /* self signed */
/* sig sub notiation we support */
#define EXP_SIG_SUB_CTIME 2
#define EXP_SIG_SUB_SIGEXPIRE 3
#define EXP_SIG_SUB_KEYEXPIRE 9
#define EXP_SIG_SUB_NOTATION 20
#define EXP_SIG_SUB_KEYFLAGS 27
/* in armored mode, we're using the usual head+foot */
#define EXP_PK_HEADER "-----BEGIN ED25519-CURVE29915 PUBLIC KEY-----"
#define EXP_PK_FOOTER "------END ED25519-CURVE29915 PUBLIC KEY------"
#define EXP_SK_HEADER "-----BEGIN ED25519-CURVE29915 PRIVATE KEY-----"
#define EXP_SK_FOOTER "------END ED25519-CURVE29915 PRIVATE KEY------"
/* pubkey export formats */
#define EXP_FORMAT_NATIVE 1
#define EXP_FORMAT_PBP 2
#define EXP_FORMAT_YAML 3
#define EXP_FORMAT_C 4
#define EXP_FORMAT_PY 5
#define EXP_FORMAT_PERL 6
/* export self signed public key from master secret */
Buffer *pcp_export_rfc_pub (pcp_key_t *sk);
/* export foreign public key
Buffer *pcp_export_rfc_pub_foreign (pcp_pubkey_t *pub); */
/* export public key in pbp format */
/** Export a public key in PBP format.
Export a public key in the format described at
https://github.com/stef/pbp/blob/master/doc/fileformats.txt
\param sk a secret key structure of type pcp_key_t. The secret keys
in there have to be already decrypted.
\return the function returns a Buffer object containing the binary
blob in the format described above.
*/
Buffer *pcp_export_pbp_pub(pcp_key_t *sk);
/* export public key in yaml format */
/** Export a public key in yaml format.
Export a public key in yaml format.
\param sk a secret key structure of type pcp_key_t. The secret keys
in there have to be already decrypted.
\return the function returns a Buffer object containing the binary
blob containing a YAML string.
*/
Buffer *pcp_export_yaml_pub(pcp_key_t *sk);
/* export public key in perl format */
/** Export a public key in perl code format.
Export a public key in perl code format.
\param sk a secret key structure of type pcp_key_t. The secret keys
in there have to be already decrypted.
\return the function returns a Buffer object containing the binary
blob containing a perl code string (a hash definition).
*/
Buffer *pcp_export_perl_pub(pcp_key_t *sk);
/* export public key in C format */
/** Export a public key in C code format.
Export a public key in C code format.
\param sk a secret key structure of type pcp_key_t. The secret keys
in there have to be already decrypted.
\return the function returns a Buffer object containing the binary
blob containing a C code string.
*/
Buffer *pcp_export_c_pub(pcp_key_t *sk);
/* export secret key */
/** Export secret key.
Export a secret key.
Secret key are exported in 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 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
\param sk a secret key structure of type pcp_key_t. The secret keys
in there have to be already decrypted.
\param passphrase the passphrase to be used to encrypt the export,
a null terminated char array.
\return the function returns a Buffer object containing the binary
blob in the format described above.
*/
Buffer *pcp_export_secret(pcp_key_t *sk, char *passphrase);
/* import public keys */
pcp_ks_bundle_t *pcp_import_pub(unsigned char *raw, size_t rawsize);
pcp_ks_bundle_t *pcp_import_pub_rfc(Buffer *blob);
pcp_ks_bundle_t *pcp_import_pub_pbp(Buffer *blob);
@@ -229,3 +305,5 @@ pcp_key_t *pcp_import_secret(unsigned char *raw, size_t rawsize, char *passphras
pcp_key_t *pcp_import_secret_native(Buffer *cipher, char *passphrase);
#endif // _HAVE_PCP_MGMT_H
/**@}*/

731
man/.doxygen Normal file
View File

@@ -0,0 +1,731 @@
# Doxyfile 1.2.6 -*-sh-*-
# This file describes the settings to be used by doxygen for a project
#
# All text after a hash (#) is considered a comment and will be ignored
# The format is:
# TAG = value [value, ...]
# For lists items can also be appended using:
# TAG += value [value, ...]
# Values that contain spaces should be placed between quotes (" ")
#---------------------------------------------------------------------------
# General configuration options
#---------------------------------------------------------------------------
# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
# by quotes) that should identify the project.
PROJECT_NAME = libpcp
# The PROJECT_NUMBER tag can be used to enter a project or revision number.
# This could be handy for archiving the generated documentation or
# if some version control system is used.
PROJECT_NUMBER = 0.2.1
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
# base path where the generated documentation will be put.
# If a relative path is entered, it will be relative to the location
# where doxygen was started. If left blank the current directory will be used.
OUTPUT_DIRECTORY = man
# The OUTPUT_LANGUAGE tag is used to specify the language in which all
# documentation generated by doxygen is written. Doxygen will use this
# information to generate all constant output in the proper language.
# The default language is English, other supported languages are:
# Dutch, French, Italian, Czech, Swedish, German, Finnish, Japanese,
# Korean, Hungarian, Norwegian, Spanish, Romanian, Russian, Croatian,
# Polish, Portuguese and Slovene.
OUTPUT_LANGUAGE = English
# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
# documentation are documented, even if no documentation was available.
# Private class members and static file members will be hidden unless
# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
EXTRACT_ALL = NO
# If the EXTRACT_PRIVATE tag is set to YES all private members of a class
# will be included in the documentation.
EXTRACT_PRIVATE = NO
# If the EXTRACT_STATIC tag is set to YES all static members of a file
# will be included in the documentation.
EXTRACT_STATIC = NO
# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all
# undocumented members of documented classes, files or namespaces.
# If set to NO (the default) these members will be included in the
# various overviews, but no documentation section is generated.
# This option has no effect if EXTRACT_ALL is enabled.
HIDE_UNDOC_MEMBERS = YES
# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all
# undocumented classes that are normally visible in the class hierarchy.
# If set to NO (the default) these class will be included in the various
# overviews. This option has no effect if EXTRACT_ALL is enabled.
HIDE_UNDOC_CLASSES = YES
# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will
# include brief member descriptions after the members that are listed in
# the file and class documentation (similar to JavaDoc).
# Set to NO to disable this.
BRIEF_MEMBER_DESC = YES
# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend
# the brief description of a member or function before the detailed description.
# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
# brief descriptions will be completely suppressed.
REPEAT_BRIEF = YES
# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
# Doxygen will generate a detailed section even if there is only a brief
# description.
ALWAYS_DETAILED_SEC = YES
# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full
# path before files name in the file list and in the header files. If set
# to NO the shortest path that makes the file name unique will be used.
FULL_PATH_NAMES = NO
# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag
# can be used to strip a user defined part of the path. Stripping is
# only done if one of the specified strings matches the left-hand part of
# the path. It is allowed to use relative paths in the argument list.
STRIP_FROM_PATH =
# The INTERNAL_DOCS tag determines if documentation
# that is typed after a \internal command is included. If the tag is set
# to NO (the default) then the documentation will be excluded.
# Set it to YES to include the internal documentation.
INTERNAL_DOCS = NO
# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will
# generate a class diagram (in Html and LaTeX) for classes with base or
# super classes. Setting the tag to NO turns the diagrams off.
CLASS_DIAGRAMS = YES
# If the SOURCE_BROWSER tag is set to YES then a list of source files will
# be generated. Documented entities will be cross-referenced with these sources.
SOURCE_BROWSER = YES
# Setting the INLINE_SOURCES tag to YES will include the body
# of functions and classes directly in the documentation.
INLINE_SOURCES = NO
# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct
# doxygen to hide any special comment blocks from generated source code
# fragments. Normal C and C++ comments will always remain visible.
STRIP_CODE_COMMENTS = YES
# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate
# file names in lower case letters. If set to YES upper case letters are also
# allowed. This is useful if you have classes or files whose names only differ
# in case and if your file system supports case sensitive file names. Windows
# users are adviced to set this option to NO.
CASE_SENSE_NAMES = YES
# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen
# will show members with their full class and namespace scopes in the
# documentation. If set to YES the scope will be hidden.
HIDE_SCOPE_NAMES = NO
# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen
# will generate a verbatim copy of the header file for each class for
# which an include is specified. Set to NO to disable this.
VERBATIM_HEADERS = YES
# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen
# will put list of the files that are included by a file in the documentation
# of that file.
SHOW_INCLUDE_FILES = YES
# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen
# will interpret the first line (until the first dot) of a JavaDoc-style
# comment as the brief description. If set to NO, the JavaDoc
# comments will behave just like the Qt-style comments (thus requiring an
# explict @brief command for a brief description.
JAVADOC_AUTOBRIEF = YES
# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented
# member inherits the documentation from any documented member that it
# reimplements.
INHERIT_DOCS = YES
# If the INLINE_INFO tag is set to YES (the default) then a tag [inline]
# is inserted in the documentation for inline members.
INLINE_INFO = YES
# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen
# will sort the (detailed) documentation of file and class members
# alphabetically by member name. If set to NO the members will appear in
# declaration order.
SORT_MEMBER_DOCS = YES
# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
# tag is set to YES, then doxygen will reuse the documentation of the first
# member in the group (if any) for the other members of the group. By default
# all members of a group must be documented explicitly.
DISTRIBUTE_GROUP_DOC = NO
# The TAB_SIZE tag can be used to set the number of spaces in a tab.
# Doxygen uses this value to replace tabs by spaces in code fragments.
TAB_SIZE = 8
# The ENABLE_SECTIONS tag can be used to enable conditional
# documentation sections, marked by \if sectionname ... \endif.
ENABLED_SECTIONS =
# The GENERATE_TODOLIST tag can be used to enable (YES) or
# disable (NO) the todo list. This list is created by putting \todo
# commands in the documentation.
GENERATE_TODOLIST = YES
# The GENERATE_TESTLIST tag can be used to enable (YES) or
# disable (NO) the test list. This list is created by putting \test
# commands in the documentation.
GENERATE_TESTLIST = YES
# The GENERATE_BUGLIST tag can be used to enable (YES) or
# disable (NO) the bug list. This list is created by putting \bug
# commands in the documentation.
GENERATE_BUGLIST = YES
# This tag can be used to specify a number of aliases that acts
# as commands in the documentation. An alias has the form "name=value".
# For example adding "sideeffect=\par Side Effects:\n" will allow you to
# put the command \sideeffect (or @sideeffect) in the documentation, which
# will result in a user defined paragraph with heading "Side Effects:".
# You can put \n's in the value part of an alias to insert newlines.
ALIASES =
# The MAX_INITIALIZER_LINES tag determines the maximum number of lines
# the initial value of a variable or define consist of for it to appear in
# the documentation. If the initializer consists of more lines than specified
# here it will be hidden. Use a value of 0 to hide initializers completely.
# The appearance of the initializer of individual variables and defines in the
# documentation can be controlled using \showinitializer or \hideinitializer
# command in the documentation regardless of this setting.
MAX_INITIALIZER_LINES = 30
# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
# only. Doxygen will then generate output that is more tailored for C.
# For instance some of the names that are used will be different. The list
# of all members will be omitted, etc.
OPTIMIZE_OUTPUT_FOR_C = NO
# Set the SHOW_USED_FILES tag to NO to disable the list of files generated
# at the bottom of the documentation of classes and structs. If set to YES the
# list will mention the files that were used to generate the documentation.
SHOW_USED_FILES = YES
#---------------------------------------------------------------------------
# configuration options related to warning and progress messages
#---------------------------------------------------------------------------
# The QUIET tag can be used to turn on/off the messages that are generated
# by doxygen. Possible values are YES and NO. If left blank NO is used.
QUIET = NO
# The WARNINGS tag can be used to turn on/off the warning messages that are
# generated by doxygen. Possible values are YES and NO. If left blank
# NO is used.
WARNINGS = YES
# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings
# for undocumented members. If EXTRACT_ALL is set to YES then this flag will
# automatically be disabled.
WARN_IF_UNDOCUMENTED = YES
# The WARN_FORMAT tag determines the format of the warning messages that
# doxygen can produce. The string should contain the $file, $line, and $text
# tags, which will be replaced by the file and line number from which the
# warning originated and the warning text.
WARN_FORMAT = "$file:$line: $text"
# The WARN_LOGFILE tag can be used to specify a file to which warning
# and error messages should be written. If left blank the output is written
# to stderr.
WARN_LOGFILE =
#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
# The INPUT tag can be used to specify the files and/or directories that contain
# documented source files. You may enter file names like "myfile.cpp" or
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
INPUT = include/pcp/
# If the value of the INPUT tag contains directories, you can use the
# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
# and *.h) to filter out the source-files in the directories. If left
# blank all files are included.
FILE_PATTERNS = *.h
# The RECURSIVE tag can be used to turn specify whether or not subdirectories
# should be searched for input files as well. Possible values are YES and NO.
# If left blank NO is used.
RECURSIVE = NO
# The EXCLUDE tag can be used to specify files and/or directories that should
# excluded from the INPUT source files. This way you can easily exclude a
# subdirectory from a directory tree whose root is specified with the INPUT tag.
EXCLUDE = include/pcp/base85.h include/pcp/config.h include/pcp/digital_crc32.h include/pcp/jenhash.h include/pcp/platform.h include/pcp/uthash.h include/pcp/zmq_z85.h
# If the value of the INPUT tag contains directories, you can use the
# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude
# certain files from those directories.
EXCLUDE_PATTERNS =
# The EXAMPLE_PATH tag can be used to specify one or more files or
# directories that contain example code fragments that are included (see
# the \include command).
EXAMPLE_PATH =
# If the value of the EXAMPLE_PATH tag contains directories, you can use the
# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
# and *.h) to filter out the source-files in the directories. If left
# blank all files are included.
EXAMPLE_PATTERNS =
# The IMAGE_PATH tag can be used to specify one or more files or
# directories that contain image that are included in the documentation (see
# the \image command).
IMAGE_PATH =
# The INPUT_FILTER tag can be used to specify a program that doxygen should
# invoke to filter for each input file. Doxygen will invoke the filter program
# by executing (via popen()) the command <filter> <input-file>, where <filter>
# is the value of the INPUT_FILTER tag, and <input-file> is the name of an
# input file. Doxygen will then use the output that the filter program writes
# to standard output.
INPUT_FILTER =
# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
# INPUT_FILTER) will be used to filter the input files when producing source
# files to browse.
FILTER_SOURCE_FILES = NO
#---------------------------------------------------------------------------
# configuration options related to the alphabetical class index
#---------------------------------------------------------------------------
# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index
# of all compounds will be generated. Enable this if the project
# contains a lot of classes, structs, unions or interfaces.
ALPHABETICAL_INDEX = NO
# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then
# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns
# in which this list will be split (can be a number in the range [1..20])
COLS_IN_ALPHA_INDEX = 5
# In case all classes in a project start with a common prefix, all
# classes will be put under the same header in the alphabetical index.
# The IGNORE_PREFIX tag can be used to specify one or more prefixes that
# should be ignored while generating the index headers.
IGNORE_PREFIX =
#---------------------------------------------------------------------------
# configuration options related to the HTML output
#---------------------------------------------------------------------------
# If the GENERATE_HTML tag is set to YES (the default) Doxygen will
# generate HTML output.
GENERATE_HTML = YES
# The HTML_OUTPUT tag is used to specify where the HTML docs will be put.
# If a relative path is entered the value of OUTPUT_DIRECTORY will be
# put in front of it. If left blank `html' will be used as the default path.
HTML_OUTPUT = html
# The HTML_HEADER tag can be used to specify a personal HTML header for
# each generated HTML page. If it is left blank doxygen will generate a
# standard header.
HTML_HEADER =
# The HTML_FOOTER tag can be used to specify a personal HTML footer for
# each generated HTML page. If it is left blank doxygen will generate a
# standard footer.
HTML_FOOTER =
# The HTML_STYLESHEET tag can be used to specify a user defined cascading
# style sheet that is used by each HTML page. It can be used to
# fine-tune the look of the HTML output. If the tag is left blank doxygen
# will generate a default style sheet
HTML_STYLESHEET =
# If the GENERATE_HTMLHELP tag is set to YES, additional index files
# will be generated that can be used as input for tools like the
# Microsoft HTML help workshop to generate a compressed HTML help file (.chm)
# of the generated HTML documentation.
GENERATE_HTMLHELP = NO
# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag
# controls if a separate .chi index file is generated (YES) or that
# it should be included in the master .chm file (NO).
GENERATE_CHI = NO
# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag
# controls whether a binary table of contents is generated (YES) or a
# normal table of contents (NO) in the .chm file.
BINARY_TOC = NO
# The TOC_EXPAND flag can be set YES to add extra items for group members
# to the contents of the Html help documentation and to the tree view.
TOC_EXPAND = NO
# The DISABLE_INDEX tag can be used to turn on/off the condensed index at
# top of each HTML page. The value NO (the default) enables the index and
# the value YES disables it.
DISABLE_INDEX = NO
# This tag can be used to set the number of enum values (range [1..20])
# that doxygen will group on one line in the generated HTML documentation.
ENUM_VALUES_PER_LINE = 4
# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be
# generated containing a tree-like index structure (just like the one that
# is generated for HTML Help). For this to work a browser that supports
# JavaScript and frames is required (for instance Netscape 4.0+
# or Internet explorer 4.0+).
GENERATE_TREEVIEW = NO
# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be
# used to set the initial width (in pixels) of the frame in which the tree
# is shown.
TREEVIEW_WIDTH = 250
#---------------------------------------------------------------------------
# configuration options related to the LaTeX output
#---------------------------------------------------------------------------
# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will
# generate Latex output.
GENERATE_LATEX = NO
# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put.
# If a relative path is entered the value of OUTPUT_DIRECTORY will be
# put in front of it. If left blank `latex' will be used as the default path.
LATEX_OUTPUT = latex
# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact
# LaTeX documents. This may be useful for small projects and may help to
# save some trees in general.
COMPACT_LATEX = NO
# The PAPER_TYPE tag can be used to set the paper type that is used
# by the printer. Possible values are: a4, a4wide, letter, legal and
# executive. If left blank a4wide will be used.
PAPER_TYPE = a4wide
# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX
# packages that should be included in the LaTeX output.
EXTRA_PACKAGES =
# The LATEX_HEADER tag can be used to specify a personal LaTeX header for
# the generated latex document. The header should contain everything until
# the first chapter. If it is left blank doxygen will generate a
# standard header. Notice: only use this tag if you know what you are doing!
LATEX_HEADER =
# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated
# is prepared for conversion to pdf (using ps2pdf). The pdf file will
# contain links (just like the HTML output) instead of page references
# This makes the output suitable for online browsing using a pdf viewer.
PDF_HYPERLINKS = NO
# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of
# plain latex in the generated Makefile. Set this option to YES to get a
# higher quality PDF documentation.
USE_PDFLATEX = NO
# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode.
# command to the generated LaTeX files. This will instruct LaTeX to keep
# running if errors occur, instead of asking the user for help.
# This option is also used when generating formulas in HTML.
LATEX_BATCHMODE = NO
#---------------------------------------------------------------------------
# configuration options related to the RTF output
#---------------------------------------------------------------------------
# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output
# The RTF output is optimised for Word 97 and may not look very pretty with
# other RTF readers or editors.
GENERATE_RTF = NO
# The RTF_OUTPUT tag is used to specify where the RTF docs will be put.
# If a relative path is entered the value of OUTPUT_DIRECTORY will be
# put in front of it. If left blank `rtf' will be used as the default path.
RTF_OUTPUT = rtf
# If the COMPACT_RTF tag is set to YES Doxygen generates more compact
# RTF documents. This may be useful for small projects and may help to
# save some trees in general.
COMPACT_RTF = NO
# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated
# will contain hyperlink fields. The RTF file will
# contain links (just like the HTML output) instead of page references.
# This makes the output suitable for online browsing using a WORD or other.
# programs which support those fields.
# Note: wordpad (write) and others do not support links.
RTF_HYPERLINKS = NO
# Load stylesheet definitions from file. Syntax is similar to doxygen's
# config file, i.e. a series of assigments. You only have to provide
# replacements, missing definitions are set to their default value.
RTF_STYLESHEET_FILE =
#---------------------------------------------------------------------------
# configuration options related to the man page output
#---------------------------------------------------------------------------
# If the GENERATE_MAN tag is set to YES (the default) Doxygen will
# generate man pages
GENERATE_MAN = NO
# The MAN_OUTPUT tag is used to specify where the man pages will be put.
# If a relative path is entered the value of OUTPUT_DIRECTORY will be
# put in front of it. If left blank `man' will be used as the default path.
MAN_OUTPUT = man
# The MAN_EXTENSION tag determines the extension that is added to
# the generated man pages (default is the subroutine's section .3)
MAN_EXTENSION = .3
#---------------------------------------------------------------------------
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------
# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will
# evaluate all C-preprocessor directives found in the sources and include
# files.
ENABLE_PREPROCESSING = YES
# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro
# names in the source code. If set to NO (the default) only conditional
# compilation will be performed. Macro expansion can be done in a controlled
# way by setting EXPAND_ONLY_PREDEF to YES.
MACRO_EXPANSION = NO
# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
# then the macro expansion is limited to the macros specified with the
# PREDEFINED and EXPAND_AS_PREDEFINED tags.
EXPAND_ONLY_PREDEF = NO
# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
# in the INCLUDE_PATH (see below) will be search if a #include is found.
SEARCH_INCLUDES = YES
# The INCLUDE_PATH tag can be used to specify one or more directories that
# contain include files that are not input files but should be processed by
# the preprocessor.
INCLUDE_PATH =
# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
# patterns (like *.h and *.hpp) to filter out the header-files in the
# directories. If left blank, the patterns specified with FILE_PATTERNS will
# be used.
INCLUDE_FILE_PATTERNS =
# The PREDEFINED tag can be used to specify one or more macro names that
# are defined before the preprocessor is started (similar to the -D option of
# gcc). The argument of the tag is a list of macros of the form: name
# or name=definition (no spaces). If the definition and the = are
# omitted =1 is assumed.
PREDEFINED =
# If the MACRO_EXPANSION and EXPAND_PREDEF_ONLY tags are set to YES then
# this tag can be used to specify a list of macro names that should be expanded.
# The macro definition that is found in the sources will be used.
# Use the PREDEFINED tag if you want to use a different macro definition.
EXPAND_AS_DEFINED =
#---------------------------------------------------------------------------
# Configuration::addtions related to external references
#---------------------------------------------------------------------------
# The TAGFILES tag can be used to specify one or more tagfiles.
TAGFILES =
# When a file name is specified after GENERATE_TAGFILE, doxygen will create
# a tag file that is based on the input files it reads.
GENERATE_TAGFILE =
# If the ALLEXTERNALS tag is set to YES all external classes will be listed
# in the class index. If set to NO only the inherited external classes
# will be listed.
ALLEXTERNALS = NO
# The PERL_PATH should be the absolute path and name of the perl script
# interpreter (i.e. the result of `which perl').
PERL_PATH = /usr/bin/perl
#---------------------------------------------------------------------------
# Configuration options related to the dot tool
#---------------------------------------------------------------------------
# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is
# available from the path. This tool is part of Graphviz, a graph visualization
# toolkit from AT&T and Lucent Bell Labs. The other options in this section
# have no effect if this option is set to NO (the default)
HAVE_DOT = NO
# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen
# will generate a graph for each documented class showing the direct and
# indirect inheritance relations. Setting this tag to YES will force the
# the CLASS_DIAGRAMS tag to NO.
CLASS_GRAPH = YES
# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen
# will generate a graph for each documented class showing the direct and
# indirect implementation dependencies (inheritance, containment, and
# class references variables) of the class with other documented classes.
COLLABORATION_GRAPH = YES
# If the ENABLE_PREPROCESSING, INCLUDE_GRAPH, and HAVE_DOT tags are set to
# YES then doxygen will generate a graph for each documented file showing
# the direct and indirect include dependencies of the file with other
# documented files.
INCLUDE_GRAPH = YES
# If the ENABLE_PREPROCESSING, INCLUDED_BY_GRAPH, and HAVE_DOT tags are set to
# YES then doxygen will generate a graph for each documented header file showing
# the documented files that directly or indirectly include this file
INCLUDED_BY_GRAPH = YES
# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen
# will graphical hierarchy of all classes instead of a textual one.
GRAPHICAL_HIERARCHY = YES
# The tag DOT_PATH can be used to specify the path where the dot tool can be
# found. If left blank, it is assumed the dot tool can be found on the path.
DOT_PATH =
# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will
# generate a legend page explaining the meaning of the various boxes and
# arrows in the dot generated graphs.
GENERATE_LEGEND = YES
# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will
# remove the intermedate dot files that are used to generate
# the various graphs.
DOT_CLEANUP = YES
#---------------------------------------------------------------------------
# Configuration::addtions related to the search engine
#---------------------------------------------------------------------------
# The SEARCHENGINE tag specifies whether or not a search engine should be
# used. If set to NO the values of all tags below this one will be ignored.
SEARCHENGINE = NO