From 3fe7a5b6a18b6841ae51f294dc58fe9c8df6d375 Mon Sep 17 00:00:00 2001 From: Dennis Brentjes Date: Wed, 28 Sep 2016 13:18:18 +0200 Subject: Finally made a initial doxygen documentation pass over all files. --- libcmix-crypto/api.h | 34 ++++++++++++++++++++++++++++---- libcmix-crypto/curve25519/curve25519.h | 29 ++++++++++++++++++++++++++- libcmix-crypto/keypair.h | 18 +++++++++++++---- libcmix-crypto/message.h | 36 ++++++++++++++++++++++++++++++---- libcmix-crypto/sharedkey.h | 13 ++++++++++-- 5 files changed, 115 insertions(+), 15 deletions(-) (limited to 'libcmix-crypto') diff --git a/libcmix-crypto/api.h b/libcmix-crypto/api.h index a798876..09b474b 100644 --- a/libcmix-crypto/api.h +++ b/libcmix-crypto/api.h @@ -1,5 +1,9 @@ #pragma once +/*! + * \file + */ + #ifdef __cplusplus extern "C" { #endif @@ -9,16 +13,38 @@ extern "C" { #include "keypair.h" #include "sharedkey.h" +/*! + * \brief Defines how a KeyPair create function should look like. + * Used to store a pointer to function to a implementation. + */ typedef struct KeyPair (*KeyPairCreator)(); + +/*! + * \brief Defines how a KeyPair deleter function should look like. + * Used to store a pointer to function to a implementation. + */ typedef void (*KeyPairDeleter)(struct KeyPair); + +/*! + * \brief Defines how a Derived Shared Key function should look like. + * Used to store a pointer to function to a implementation. + */ typedef struct SharedKey (*SharedKeyDeriver)(struct KeyPair, unsigned char*, bool); + +/*! + * \brief Defines how a Derived Shared Key deleter function should look like. + * Used to store a pointer to function to a implementation. + */ typedef void (*SharedKeyDeleter)(struct SharedKey); +/*! + * \brief The Api struct stores pointers to functions of a specific implementation. Like a Curve25519 specific one. + */ struct Api { - KeyPairCreator create_key_pair; - KeyPairDeleter free_key_pair; - SharedKeyDeriver derive_shared_key; - SharedKeyDeleter free_shared_key; + KeyPairCreator create_key_pair; ///< Pointer to keypair creation function + KeyPairDeleter free_key_pair; ///< Pointer to keypair deletor function + SharedKeyDeriver derive_shared_key; ///< Pointer to shared key derivation function + SharedKeyDeleter free_shared_key; ///< Pointer to shared key deleter function }; #ifdef __cplusplus diff --git a/libcmix-crypto/curve25519/curve25519.h b/libcmix-crypto/curve25519/curve25519.h index 19c68e6..8e2ad4e 100644 --- a/libcmix-crypto/curve25519/curve25519.h +++ b/libcmix-crypto/curve25519/curve25519.h @@ -1,17 +1,44 @@ #pragma once +#include "api.h" + #ifdef __cplusplus extern "C" { #endif -#include "api.h" +/*! + * \file + */ +/*! + * \brief curve25519_create_keypair + * \return A curve25519 keypair. + */ extern struct KeyPair curve25519_create_keypair(); +/*! + * \brief curve25519_keypair_deleter + * \param p The keypair to free. + */ extern void curve25519_keypair_deleter(struct KeyPair p); +/*! + * \brief curve25519_derive_shared_key + * \param pair Our keypair. + * \param pub_key The public key of the other party. + * \param swap_pub_order Should we swap the order in which we feed the public keys to the hash function. + * \return A Shared key + */ extern struct SharedKey curve25519_derive_shared_key(struct KeyPair pair, unsigned char* pub_key, bool swap_pub_order); +/*! + * \brief curve25519_shared_key_deleter + * \param s the Shared key to free. + */ extern void curve25519_shared_key_deleter(struct SharedKey s); +/*! + * \brief get_curve25519_implementation + * \return An Api struct filled with a curve25519 implementation. + */ struct Api get_curve25519_implementation(); #ifdef __cplusplus diff --git a/libcmix-crypto/keypair.h b/libcmix-crypto/keypair.h index 9587db3..838291d 100644 --- a/libcmix-crypto/keypair.h +++ b/libcmix-crypto/keypair.h @@ -1,16 +1,26 @@ #pragma once +/*! + * \file + */ + #ifdef __cplusplus extern "C" { #endif #include +/*! + * \brief The KeyPair struct contains the private and public key, and the private and public key lengths. + * + * Is used as a generic storage container for multiple implementations. So the implementations are + * responsible for memory meanagement. See the Api struct for examples of this. + */ struct KeyPair { - unsigned char* sec; - unsigned char* pub; - unsigned int sec_len; - unsigned int pub_len; + unsigned char* sec; ///< Private key + unsigned char* pub; ///< Public key + unsigned int sec_len; ///< Private key length + unsigned int pub_len; ///< Public key length }; diff --git a/libcmix-crypto/message.h b/libcmix-crypto/message.h index 7222d00..b1c3b87 100644 --- a/libcmix-crypto/message.h +++ b/libcmix-crypto/message.h @@ -1,5 +1,9 @@ #pragma once +/** + * \file + */ + #ifdef __cplusplus extern "C" { #endif @@ -7,16 +11,33 @@ extern "C" { #include #include +/*! + * Defines how a cMix Buffer allocater should look like. + */ typedef char*(*CmixBufferAllocator)(size_t); +/*! + * Defines how a cMix Buffer deallocater should look like. + */ typedef void(*CmixBufferDeallocator)(void*); +/*! + * Defines how the function looks like that returns the length of one message in this buffer implementation. + */ typedef size_t(*CmixBufferMessageLength)(); +/*! + * \brief The CmixBufferImpl struct + */ struct CmixBufferImpl { - CmixBufferAllocator allocate_cmix_buffer; - CmixBufferDeallocator deallocate_cmix_buffer; - CmixBufferMessageLength message_length; + CmixBufferAllocator allocate_cmix_buffer; ///< pointer to function to implementation specific allocater. + CmixBufferDeallocator deallocate_cmix_buffer; ///< pointer to function to implementation specific deallocater. + CmixBufferMessageLength message_length; ///< pointer to function to implementation specific function returning message length. }; +/*! + * \def DEFINE_CIPHER(NAME, MESSAGE_SIZE) + * Generates some cipher specific boilerplate for manipulating the message buffer. + */ + #define DEFINE_CIPHER(NAME, MESSAGE_SIZE)\ typedef char NAME ## Message[MESSAGE_SIZE];\ \ @@ -40,8 +61,15 @@ struct CmixBufferImpl get_cmix_ ## NAME ## _buffer_implementation() {\ };\ } +/*! + * #DEFINE_CIPHER(Null, 0) + */ DEFINE_CIPHER(Null, 0) -DEFINE_CIPHER(Curve25519, 20); + +/*! + * #DEFINE_CIPHER(Curve25519, 31) + */ +DEFINE_CIPHER(Curve25519, 31) #undef DEFINE_CIPHER diff --git a/libcmix-crypto/sharedkey.h b/libcmix-crypto/sharedkey.h index 9c959fe..c37ae41 100644 --- a/libcmix-crypto/sharedkey.h +++ b/libcmix-crypto/sharedkey.h @@ -1,12 +1,21 @@ #pragma once +/*! + * \file + */ + #ifdef __cplusplus extern "C" { #endif +/*! + * \brief The SharedKey struct. + * + * Stored the derived shared secret after for instance Diffie-Hellman. + */ struct SharedKey { - unsigned char* shared; - unsigned int shared_len; + unsigned char* shared; ///< The Shared key. + unsigned int shared_len; ///< The shared key length. }; #ifdef __cplusplus -- cgit v1.2.3-70-g09d2