From 08bc0bc8bf2984a2862cf10fab15544fd0b8c10f Mon Sep 17 00:00:00 2001 From: "git@daemon.de" Date: Thu, 20 Feb 2014 15:36:49 +0100 Subject: [PATCH] updated api docs. --- include/pcp/crypto.h | 1 - include/pcp/defines.h | 33 +++++-- include/pcp/ed.h | 159 +++++++++++++++++++++++++++---- include/pcp/key.h | 9 ++ include/pcp/keyhash.h | 94 +++++++++++++++++- include/pcp/mac.h | 64 ++++++++----- include/pcp/util.h | 65 +++++++++++++ include/pcp/vault.h | 217 +++++++++++++++++++++++++++++++++++++----- include/pcp/z85.h | 94 ++++++++++++++++-- src/keyprint.h | 3 - tests/sample.c | 6 +- 11 files changed, 654 insertions(+), 91 deletions(-) diff --git a/include/pcp/crypto.h b/include/pcp/crypto.h index 36e35e9..50aa8b8 100644 --- a/include/pcp/crypto.h +++ b/include/pcp/crypto.h @@ -170,7 +170,6 @@ unsigned char *pcp_box_encrypt(pcp_key_t *secret, pcp_pubkey_t *pub, \return 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. */ -unsigne unsigned char *pcp_box_decrypt(pcp_key_t *secret, pcp_pubkey_t *pub, unsigned char *cipher, size_t ciphersize, size_t *dsize); diff --git a/include/pcp/defines.h b/include/pcp/defines.h index d61f200..4d4f04c 100644 --- a/include/pcp/defines.h +++ b/include/pcp/defines.h @@ -29,11 +29,12 @@ \section intro_sec Introduction This is the API documentation of libpcp, the library behind - Pretty Curved Privacy (pcp). The library can be used independently + Pretty Curved Privacy (pcp). + The library can be used independently of pcp to manage keys and to encrypt or sign files or buffers. - For most actual crypto related things, libpcp uses libsodium, - the portable NaCL library. + For most actual crypto related things, libpcp uses + libsodium, the portable NaCL library. \section sample_sec Sample usage @@ -56,7 +57,7 @@ typedef unsigned char byte; /* Single unsigned byte = 8 bits */ typedef unsigned short dbyte; /* Double byte = 16 bits */ typedef unsigned int qbyte; /* Quad byte = 32 bits */ -/* key stuff */ +/* key stuff, deprecated. */ #define PCP_KEY_HEADER "----- BEGIN PCP SECRET KEY -----" #define PCP_KEY_FOOTER "------ END PCP SECRET KEY ------" @@ -79,11 +80,25 @@ typedef unsigned int qbyte; /* Quad byte = 32 bits */ #define PCP_KEY_VERSION 6 #define PCP_KEY_PRIMITIVE "CURVE25519-ED25519-SALSA20-POLY1305" -#define PCP_KEY_TYPE_MAINSECRET 1 -#define PCP_KEY_TYPE_SECRET 2 -#define PCP_KEY_TYPE_PUBLIC 3 -#define PCP_KEYSIG_NATIVE 4 -#define PCP_KEYSIG_PBP 5 +/** + \addtogroup KEYS + @{ +*/ + +/** \enum _PCP_KEY_TYPES + + Internal key types. + */ +typedef enum _PCP_KEY_TYPES { + PCP_KEY_TYPE_MAINSECRET = 1, /**< 1 - Primary secret */ + PCP_KEY_TYPE_SECRET = 2, /**< 2 - Other secret */ + PCP_KEY_TYPE_PUBLIC = 3, /**< 3 - Public */ + PCP_KEYSIG_NATIVE = 4, /**< 4 - PCP native key signature */ + PCP_KEYSIG_PBP = 5 /**< 5 - PBP key signature */ +} PCP_KEY_TYPES; + +/** @} + */ /* save typing, dammit */ #define PCP_ENCRYPT_MAC crypto_secretbox_ZEROBYTES + crypto_secretbox_NONCEBYTES diff --git a/include/pcp/ed.h b/include/pcp/ed.h index 695fa1f..8c9371c 100644 --- a/include/pcp/ed.h +++ b/include/pcp/ed.h @@ -1,7 +1,7 @@ /* This file is part of Pretty Curved Privacy (pcp1). - Copyright (C) 2013 T.Linden. + Copyright (C) 2013-2014 T.v.Dein. This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -16,16 +16,19 @@ You should have received a copy of the GNU General Public License along with this program. If not, see . - You can contact me by mail: . -*/ - -/* - ED25519 signatures. Currently unbuffered + You can contact me by mail: . */ #ifndef _HAVE_PCP_ED_H #define _HAVE_PCP_ED_H +/** \defgroup ED SIGNING + @{ + + ED25519 signature functions. + +*/ + #include #include #include @@ -39,30 +42,150 @@ #include "util.h" #include "pcpstream.h" -/* sign a message of messagesize using s->edsecret, if it works - return message+signature (size: messagesize + crypto_sign_BYTES), - returns NULL otherwise */ +/** Sign a raw message. + + Sign a message of messagesize using s->edsecret. + This is just a convenience wrapper around crypto_sign(). + + \param[in] message The message to sign. + + \param[in] messagesize Size of the message. + + \param[in] s Pointer to secret key structure. + + \return Returns message+signature with size of messagesize + crypto_sign_BYTES, + or NULL in case of an error. +*/ unsigned char *pcp_ed_sign(unsigned char *message, size_t messagesize, pcp_key_t *s); -/* the same, but use the mastersecret instead, usually for keysigning */ -unsigned char *pcp_ed_sign_key(unsigned char *message, size_t messagesize, pcp_key_t *s); +/** Sign a raw message using s->mastersecret. -/* verify a signature of siglen size using p->edpub, if the signature verifies - return the raw message with the signature removed (size: siglen - crypto_sign_BYTES), - returns NULL otherwise */ + The same as pcp_ed_sign() but uses the mastersecret for signing. + Usually used for key signing only. + + \param[in] message The message to sign. + + \param[in] messagesize Size of the message. + + \param[in] s Pointer to secret key structure. + + \return Returns message+signature with size of messagesize + crypto_sign_BYTES, + or NULL in case of an error. + +*/unsigned char *pcp_ed_sign_key(unsigned char *message, size_t messagesize, pcp_key_t *s); + +/** Verify a signature. + + Verify a signature of size siglen using p->edpub. + + The signature must contain the message+nacl signature (with size crypto_sign_BYTES). + + \param[in] signature Message+signature. + + \param[in] siglen Size of message+signature. + + \param[in] p Pointer to public key structure. + + \return 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(). +*/ unsigned char *pcp_ed_verify(unsigned char *signature, size_t siglen, pcp_pubkey_t *p); -/* the same, but use the mastersecret instead, usually for keysigning */ +/** Verify a signature using the mastersecret. + + Verify a signature of size siglen using p->masterpub. + + The signature must contain the message+nacl signature (with size crypto_sign_BYTES). + + \param[in] signature Message+signature. + + \param[in] siglen Size of message+signature. + + \param[in] p Pointer to public key structure. + + \return 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(). +*/ unsigned char *pcp_ed_verify_key(unsigned char *signature, size_t siglen, pcp_pubkey_t *p); -/* same as pcp_ed_sign() but work on i/o directly, we're making a hash - of the input 32k-wise, copy in=>out, sign the hash and append the - sig only to the output */ +/** Sign a stream in 32k block mode. + + This function reads blockwise from the stream \a in and generates a hash + of the contents of the stream. It outputs the stream to \a out, also blockwise + and appends the signature afterwards, which consists of the hash+nacl-signature. + + \param[in] in Stream to read from. + + \param[out] out Stream to write to. + + \param[in] s Pointer to secret key. + + \param[in] z85 Flag which indicates if to create an armored signature or not. 1=armored, 0=raw. + + \return Returns the number of bytes written to the output stream. + +*/ size_t pcp_ed_sign_buffered(Pcpstream *in, Pcpstream *out, pcp_key_t *s, int z85); + +/** Verify a signature from a stream in 32k block mode. + + This function reads blockwise from the stream \a 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 \a 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. + + \param[in] in Stream to read from. + + \param[in] p Pointer to public key structure. + + \return Returns a pointer to a public key which were used to verify the signature or NULL if + an error occurred. Check fatals_if_any(). +*/ pcp_pubkey_t *pcp_ed_verify_buffered(Pcpstream *in, pcp_pubkey_t *p); +/** Generate a detached signature from a stream in 32k block mode. + + This function reads blockwise from the stream \a 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 \a out. + + \param[in] in Stream to read from. + + \param[out] out Stream to write to. + + \param[in] s Pointer to secret key. + + \return Returns the size of the detached signature written or 0 in case of errors. Check fatals_if_any(). + + */ size_t pcp_ed_detachsign_buffered(Pcpstream *in, Pcpstream *out, pcp_key_t *s); + +/** Verify a detached signature from a stream in 32k block mode. + + This function reads blockwise from the stream \a in and generates a hash + of the contents of the stream. It then reads the signature from the stream + \a sigfd and verifies the signature from it using p->edpub and compares + the signature hash with the hash it calculated + from the signed content. + + \param[in] in Stream to read from. + + \param[in] sigfd Stream containing the detached signature. + + \param[in] p Pointer to public key structure. + + \return Returns a pointer to a public key which were used to verify the signature or NULL if + an error occurred. Check fatals_if_any(). + + */ pcp_pubkey_t *pcp_ed_detachverify_buffered(Pcpstream *in, Pcpstream *sigfd, pcp_pubkey_t *p); #endif /* _HAVE_PCP_ED_H */ + +/**@}*/ diff --git a/include/pcp/key.h b/include/pcp/key.h index ea5e0b7..696f605 100644 --- a/include/pcp/key.h +++ b/include/pcp/key.h @@ -428,7 +428,16 @@ int pcp_sanitycheck_pub(pcp_pubkey_t *key); */ int pcp_sanitycheck_key(pcp_key_t *key); +/** Dump a secret key structure to stderr. + + \param[in] k Secret key to dump. +*/ void pcp_dumpkey(pcp_key_t *k); + +/** Dump a public key structure to stderr. + + \param[in] k Public key to dump. +*/ void pcp_dumppubkey(pcp_pubkey_t *k); diff --git a/include/pcp/keyhash.h b/include/pcp/keyhash.h index ff8e07d..6224087 100644 --- a/include/pcp/keyhash.h +++ b/include/pcp/keyhash.h @@ -22,37 +22,125 @@ #ifndef _HAVE_KEYHASH_H #define _HAVE_KEYHASH_H +/** \defgroup KEYHASH KEYHASH + @{ + + Uthashes of secret and public key structures. + + 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. +*/ + #include "uthash.h" #include "key.h" /* storage of keys in a global hash */ + +/** Global hash for secret keys. */ extern pcp_key_t *pcpkey_hash; + +/** Global hash for public keys. */ extern pcp_pubkey_t *pcppubkey_hash; + extern pcp_key_t *__k; extern pcp_pubkey_t *__p; /* wrapper for HASH_ITER */ +/** Iterate over the list of secret keys. + + Sample use: + + @code + pcp_key_t k = NULL; + pcphash_iterate(k) { + pcp_dumpkey(k); + } + @endcode + + Also, don't free() the keyhash or the temporary key pointer + yourself. Use pcphash_clean() instead when done. +*/ #define pcphash_iterate(key) \ __k = NULL; \ HASH_ITER(hh, pcpkey_hash, key, __k) + +/** Iterate over the list of public keys. + + Sample use: + + @code + pcp_pubkey_t k = NULL; + pcphash_iteratepub(k) { + pcp_dumppubkey(k); + } + @endcode + + Also, don't free() the keyhash or the temporary key pointer + yourself. Use pcphash_clean() instead when done. +*/ #define pcphash_iteratepub(key) \ __p = NULL; \ HASH_ITER(hh, pcppubkey_hash, key, __p) - +/** Initialize the global hashes. */ void pcphash_init(); + +/** Delete an entry from a hash. + + \param[in] key A pointer to the key structure to delete. + + \param[in] type An integer specifying the key type to delete. \see _PCP_KEY_TYPES. + + */ void pcphash_del(void *key, int type); + +/** Frees the memory allocated by the hashes. + + Clears and frees memory of all keys in the hash lists + and the hashes themselfes. + + */ void pcphash_clean(); +/** Check if a secret key with a given key-id exists in the hash. + + \param[in] id A string with the key-id (max 17 chars incl 0). + + \return Returns a pointer to the matching key or NULL if the id doesn't match. +*/ pcp_key_t *pcphash_keyexists(char *id); + +/** Check if a publickey with a given key-id exists in the hash. + + \param[in] id A string with the key-id (max 17 chars incl 0). + + \return Returns a pointer to the matching key or NULL if the id doesn't match. +*/ pcp_pubkey_t *pcphash_pubkeyexists(char *id); +/** Add a key structure to the hash list. + + \param[in] key A pointer to the key structure to delete. + + \param[in] type An integer specifying the key type to delete. \see _PCP_KEY_TYPES. + */ void pcphash_add(void *key, int type); + +/** Returns the number of secret keys in the hash. + + \return Number of keys. +*/ int pcphash_count(); + +/** Returns the number of public keys in the hash. + + \return Number of keys. +*/ int pcphash_countpub(); -/* the same, for keysigs */ +/** Global hash for key signatures. */ extern pcp_keysig_t *pcpkeysig_hash; extern pcp_keysig_t *__s; @@ -63,3 +151,5 @@ extern pcp_keysig_t *__s; pcp_keysig_t *pcphash_keysigexists(char *id); #endif /* _HAVE_KEYHASH_H */ + +/**@}*/ diff --git a/include/pcp/mac.h b/include/pcp/mac.h index 429ef0c..8e000b0 100644 --- a/include/pcp/mac.h +++ b/include/pcp/mac.h @@ -23,6 +23,10 @@ #ifndef _HAVE_PCP_MAC #define _HAVE_PCP_MAC +/** + * \addtogroup CRYPTO + * @{ + */ #include #include #include @@ -34,35 +38,47 @@ /* how many times do we hash the passphrase */ #define HCYCLES 128000 -/* encrypt some arbitrary cleartext using */ -/* a curve25519 secret key and a given nonce. */ -/* */ -/* expects a pointer to the target binary */ -/* stream containing the encrypted data, */ -/* the cleartext string, its size, the nonce */ -/* (24 bytes) and the secret key (32 bytes). */ -/* */ -/* allocates memory for the returned cipher */ -/* and it is up to the user to free it after use. */ -/* */ -/* returns the size of the returned cipherstream. */ -/* in case of an error, the cipher will be set */ -/* to NULL. */ +/** Symmetrically encrypt a message. + + This function encrypts a message symmetrically + using crypto_secretbox() using the given Curve25519 raw + secret key and the nonce. + + It allocates apropriate memory for the result, + which will be stored in \a cipher. + + \param[out] cipher Encrypted result. + \param[in] cleartext Clear message. + \param[in] clearsize Size of message. + \param[in] nonce A random nonce (24 Bytes). + \param[in] key A Curve25519 key (32 Bytes). + + \return Returns the size of \a cipher. + */ size_t pcp_sodium_mac(unsigned char **cipher, unsigned char *cleartext, size_t clearsize, unsigned char *nonce, unsigned char *key); -/* does the opposite of pcp_sodium_mac and decrypts */ -/* a given encrypted binary stream using a nonce and */ -/* a secret key (sizes: see above). */ -/* */ -/* allocates memory for the returned cleartext and */ -/* it is up to the user to free it after use. */ -/* */ -/* returns 0 if decryption and verification were */ -/* successful, otherwise -1. */ +/** Decrypt a symmetrically encrypted message. + + This function decrypts a symmetrically encrypted message + using crypto_secretbox_open() using the given Curve25519 raw + secret key and the nonce. + + It allocates apropriate memory for the result, + which will be stored in \a cleartext. + + \param[out] cleartext The decrypted result. + \param[in] message The encrypted message. + \param[in] messagesize Size of message. + \param[in] nonce A random nonce (24 Bytes). + \param[in] key A Curve25519 key (32 Bytes). + + \return Returns 0 in case of success of -1 in case of an error. Check fatals_if_any(). + + */ int pcp_sodium_verify_mac(unsigned char **cleartext, unsigned char* message, size_t messagesize, @@ -73,3 +89,5 @@ int pcp_sodium_verify_mac(unsigned char **cleartext, #endif /* _HAVE_PCP_MAC */ + +/**@}*/ diff --git a/include/pcp/util.h b/include/pcp/util.h index db580f9..b9ad053 100644 --- a/include/pcp/util.h +++ b/include/pcp/util.h @@ -25,15 +25,80 @@ #ifndef _HAVE_PCP_UTIL_H #define _HAVE_PCP_UTIL_H +/** \defgroup UTILs UTILS + @{ + + Various useful helper functions. +*/ + #include #include #include #include #include + + + +/** Convert a char array to lowercase. + + The supplied char array will be directly modified. Use + a copy if you want to retain the original. + + \param[in,out] in The char array to convert. + + \return Returns the pointer to the char array. + + */ char *_lc(char *in); + +/** Find the offset of some offset marker in some arbitrary data. + + Sample input: + @code + ABABABABnacl-98a7sd98a7das98d7 + @endcode + + If you look for the offset of "nacl" within that data, the + function will return 9, which is the position within the data + where the marker starts. + + \param[in] bin Aribrary data where to look for the marker. + + \param[in] binlen The size of the data. + + \param[in] sigstart The offset marker. + + \param[in] hlen Size of the offset marker. + + \return Returns the offset or -1 of the offset were not found. + + */ size_t _findoffset(unsigned char *bin, size_t binlen, char *sigstart, size_t hlen); + +/** XOR an input buffer with another buffer. + + Both buffers have to have the same size. The input + buffer will bei modified directly. + + \param[in] iv The buffer to XOR with. + + \param[in,out] buf The buffer which will be XORed with 'iv'. + + \param[in] xlen The size of the buffers (they must have the same size). + */ void _xorbuf(unsigned char *iv, unsigned char *buf, size_t xlen); + +/** Dump binary data as hex to stderr. + + \param[in] n Description, string. + + \param[in] d Data to print. + + \param[in] s Size of d. + */ void _dump(char *n, unsigned char *d, size_t s); #endif /* _HAVE_PCP_UTIL_H */ + +/**@}*/ diff --git a/include/pcp/vault.h b/include/pcp/vault.h index 29cb0b6..fef5cc6 100644 --- a/include/pcp/vault.h +++ b/include/pcp/vault.h @@ -1,7 +1,7 @@ /* This file is part of Pretty Curved Privacy (pcp1). - Copyright (C) 2013 T.Linden. + Copyright (C) 2013-2014 T.v.Dein. This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -16,13 +16,66 @@ You should have received a copy of the GNU General Public License along with this program. If not, see . - You can contact me by mail: . + You can contact me by mail: . */ #ifndef _HAVE_PCP_VAULT #define _HAVE_PCP_VAULT +/** \defgroup VAULT VAULT + @{ + + The vault file is used to store keys and key-signatures on disk. + It works like a keyring. + + \section vformat Vault File Format + + The vault file contains all public and secret keys. It's a portable + binary file. + + The file starts with a header: + + @code + +-------------------------------------------+ + | Field Size Description | + +-------------------------------------------+ + | File ID | 1 | Vault Identifier 0xC4 | + +-------------------------------------------+ + | Version | 4 | Big endian, version | + +-------------------------------------------+ + | Checksum | 32 | SHA256 Checksum | + +-------------------------------------------+ + @endcode + + The checksum is a checksum of all keys. + + The header is followed by the keys. Each key is preceded by an + item header which looks like this: + + @code + +--------------------------------------------+ + | 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 | + +--------------------------------------------+ + @endcode + + Type can be one of: + + - PCP_KEY_TYPE_MAINSECRET 0x01 + - PCP_KEY_TYPE_SECRET 0x02 + - PCP_KEY_TYPE_PUBLIC 0x03 + + The item header is followed by the actual key contents. +*/ + #include #include #include @@ -37,51 +90,167 @@ #include "buffer.h" #include "keysig.h" +/** \struct _vault_t + This structure represents a vault. */ struct _vault_t { - char *filename; - FILE *fd; - uint8_t unsafed; - uint8_t isnew; - uint32_t size; - time_t modified; - mode_t mode; - uint32_t version; - byte checksum[32]; -}; - -struct _vault_header_t { - uint8_t fileid; - uint32_t version; - byte checksum[32]; -}; - -struct _vault_item_header_t { - uint8_t type; - uint32_t size; - uint32_t version; - byte checksum[32]; + char *filename; /**< The filename of the vault (full path) */ + FILE *fd; /**< Filehandle if opened */ + uint8_t unsafed; /**< Flag to tell if the file needs to be written */ + uint8_t isnew; /**< Flag to tell if the vault has been newly created */ + uint32_t size; /**< Filesize */ + time_t modified; /**< mtime */ + mode_t mode; /**< File mode */ + uint32_t version; /**< Vault version */ + byte checksum[32]; /**< SHA256 checksum over the whole vault */ }; +/** Name of the struct */ typedef struct _vault_t vault_t; + +/** \struct _vault_header_t + Defines the vault header. */ +struct _vault_header_t { + uint8_t fileid; /**< File id, proprietary. Marks the vault as a vault */ + uint32_t version; /**< File version */ + byte checksum[32]; /**< SHA256 checksum over the whole vault */ +}; + +/** Name of the struct */ typedef struct _vault_header_t vault_header_t; + +/** \struct _vault_item_header_t + An item header. */ +struct _vault_item_header_t { + uint8_t type; /**< Item type (secret key, public, key, keysig, \see _PCP_KEY_TYPES */ + uint32_t size; /**< Size of the item */ + uint32_t version; /**< Version of the item */ + byte checksum[32]; /**< SHA256 checksum of the item */ +}; + +/** Name of the struct */ typedef struct _vault_item_header_t vault_item_header_t; +/** Open a vault file. + If the file doesn't exist, it will be created. + + \param[in] filename The filename of the vault file. + + \return Returns a vault object. + */ vault_t *pcpvault_init(char *filename); + + +/* Creates a new vault file. Called internally only. + If is_tmp If set to 1, create a temporary vault file. + */ vault_t *pcpvault_new(char *filename, int is_tmp); + + +/* Writes the initial vault header to the vault. + Called internally only. */ int pcpvault_create(vault_t *vault); + + +/** Add an item to the vault. + + Adds \a item with the size \a itemsize and type \a type + to the vault. Generates the item header and the checksum + of the item. + + This function writes directly into the vault file. Use + with care. To be safe, use pcpvault_addkey() instead. + + \param[out] vault The vault object. + \param[in] item The item to write. + \param[in] itemsize Size of the item. + \param[in] type Type of the item. \see _PCP_KEY_TYPES. + + \return Returns the number of bytes written or 0 in case of + an error. Check fatals_if_any(). + */ int pcpvault_additem(vault_t *vault, void *item, size_t itemsize, uint8_t type); + + +/** Add a key to the vault. + + 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. + + \param[out] vault The vault object. + \param[in] item The item to write (a key or keysig) + \param[in] type Type of the item. \see _PCP_KEY_TYPES. + + \return Returns 0 on success or 1 in case of errors. Check fatals_if_any(). + */ int pcpvault_addkey(vault_t *vault, void *item, uint8_t type); + + +/** Close a vault file. + + 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. + + \param[out] vault The vault object. + + \return Returns 0. Check fatals_if_any() anyway. + + */ int pcpvault_close(vault_t *vault); + + +/** Reads in the vault contents. + + This function reads the open vault contents and puts + them into the apropriate hashes. \see KEYHASH. + + Currently only known types can be read. If your're saving + unknown types to the vault, an error will occur. \see _PCP_KEY_TYPES. + + 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. + + \param[out] vault The vault object. + + \return Returns 0 on success or -1 in case of errors. Check fatals_if_any(). + */ int pcpvault_fetchall(vault_t *vault); + + +/* Write everything back to disk. */ int pcpvault_writeall(vault_t *vault); + +/* copy a vault to another file */ int pcpvault_copy(vault_t *tmp, vault_t *vault); + +/* delete a vault file */ void pcpvault_unlink(vault_t *tmp); + +/* calculate the vault checksum */ unsigned char *pcpvault_create_checksum(vault_t *vault); + +/* write the new checksum to the header of the current vault */ void pcpvault_update_checksum(vault_t *vault); +/* bigendian converters */ vault_header_t * vh2be(vault_header_t *h); vault_header_t * vh2native(vault_header_t *h); vault_item_header_t * ih2be(vault_item_header_t *h); vault_item_header_t * ih2native(vault_item_header_t *h); #endif /* _HAVE_PCP_VAULT */ + +/**@}*/ diff --git a/include/pcp/z85.h b/include/pcp/z85.h index f3d514b..ca28c75 100644 --- a/include/pcp/z85.h +++ b/include/pcp/z85.h @@ -1,7 +1,7 @@ /* This file is part of Pretty Curved Privacy (pcp1). - Copyright (C) 2013 T.Linden. + Copyright (C) 2013-2014 T.v.Dein. This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -16,36 +16,114 @@ You should have received a copy of the GNU General Public License along with this program. If not, see . - You can contact me by mail: . + You can contact me by mail: . */ /* from https://github.com/tlinden/curve-keygen/ */ #ifndef _HAVE_PCP_Z85_H -#include +/** + * \defgroup Z85 Z85 + * @{ + Z85 Encoding functions. + +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. + + */ +#include #include "defines.h" #include "zmq_z85.h" #include "mem.h" #include "buffer.h" -/* convert a binary stream to one which gets accepted by zmq_z85_encode */ -/* we pad it with zeroes and put the number of zerores in front of it */ +/** 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. + + \param[in] src Unpadded data. + \param[in] srclen Size of unpadded data. + \param[in] dstlen Returned size of padded data (pointer to int). + + \return Returns a pointer to the padded data. + */ unsigned char *pcp_padfour(unsigned char *src, size_t srclen, size_t *dstlen); -/* the reverse of the above */ + +/** 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. + + \param[in] src Padded data. + \param[in] srclen Size of padded data. + + \return Returns the unpadded size of the data. + */ size_t pcp_unpadfour(unsigned char *src, size_t srclen); -/* wrapper around zmq Z85 encoding function */ +/** Decode data from Z85 encoding. + + The input \a z85block may contain newlines which will be removed. + + \param[in] z85block The Z85 encoded string. + \param[in] dstlen Returned size of decoded data (pointer to int). + + \return Returns a newly allocated pointer to the decoded data. If decoding failed, + returns NULL. Check fatals_if_any(). + +*/ unsigned char *pcp_z85_decode(char *z85block, size_t *dstlen); -/* the reverse of the above */ + +/** Encode data to Z85 encoding. + + Beside Z85 encoding it also adds a newline everiy 72 characters. + + \param[in] raw Pointer to raw data. + \param[in] srclen Size of the data. + \param[in] dstlen Returned size of encoded data (pointer to int). + + \return Returns a string (char array) containing the Z85 encoded data. +*/ char *pcp_z85_encode(unsigned char *raw, size_t srclen, size_t *dstlen); +/** Read a Z85 encoded file. + + Reads a file and returns the raw Z85 encoded string. + It ignores newlines, comments and Headerstrings. + + \param[in] infile FILE stream to read from. + + \return Raw Z85 encoded string with comments, headers and newlines removed. + */ char *pcp_readz85file(FILE *infile); + +/** Read a Z85 encoded string. + + Parses the given input string and returns the raw Z85 encoded string. + It ignores newlines, comments and Headerstrings. + + \param[in] input Z85 encoded string. + \param[in] bufsize Size of the string. + + \return Raw Z85 encoded string with comments, headers and newlines removed. + + */ char *pcp_readz85string(unsigned char *input, size_t bufsize); size_t _buffer_is_binary(unsigned char *buf, size_t len); #endif /* _HAVE_PCP_Z85_H */ + +/**@}*/ diff --git a/src/keyprint.h b/src/keyprint.h index 9ca188f..b0d2672 100644 --- a/src/keyprint.h +++ b/src/keyprint.h @@ -31,9 +31,6 @@ #include "keyhash.h" #include "base85.h" -void pcp_dumpkey(pcp_key_t *k); -void pcp_dumppubkey(pcp_pubkey_t *k); - void pcpkey_print(pcp_key_t *key, FILE *out); void pcppubkey_print(pcp_pubkey_t *key, FILE *out); diff --git a/tests/sample.c b/tests/sample.c index d51ca37..df0c1c0 100644 --- a/tests/sample.c +++ b/tests/sample.c @@ -25,7 +25,7 @@ int main() { /* prepare the pubkey recipient list (only 1 recipient: Bob) */ pubhash = NULL; - strncpy(bobpub->id, pcp_getkeyid(bobpub), 17); + strncpy(bobpub->id, pcp_getpubkeyid(bobpub), 17); HASH_ADD_STR( pubhash, id, bobpub); /* actually encrypt the message, don't sign it @@ -33,7 +33,7 @@ int main() { pcp_encrypt_stream(clear_in, crypt_out, alice, pubhash, 0); /* now, print the encrypted result */ - fprintf(stderr, "Alice encrypted %d bytes for Bob:\n", strlen(message)); + fprintf(stderr, "Alice encrypted %ld bytes for Bob:\n", strlen(message)); buffer_dump(ps_buffer(crypt_out)); /* ---- encryption don, now decrypt ---- */ @@ -52,7 +52,7 @@ int main() { fatals_ifany(); else { /* and finally print out the decrypted message */ - fprintf(stderr, "Bob decrypted %d bytes from Alice:\n", buffer_size(ps_buffer(crypt_out))); + fprintf(stderr, "Bob decrypted %ld bytes from Alice:\n", buffer_size(ps_buffer(crypt_out))); printf("Decrypted message: %s\n", buffer_get_str(ps_buffer(clear_out))); }