diff options
| -rw-r--r-- | doc/fmts.md | 29 | ||||
| -rw-r--r-- | src/bitfield.h | 42 | ||||
| -rw-r--r-- | src/bne.h | 40 | ||||
| -rwxr-xr-x | src/build-utils.sh | 24 | ||||
| -rw-r--r-- | src/config.h | 46 | ||||
| -rw-r--r-- | src/cred_dict.h | 55 | ||||
| -rw-r--r-- | src/data.h | 51 | ||||
| -rw-r--r-- | src/dvault.h | 132 |
8 files changed, 312 insertions, 107 deletions
diff --git a/doc/fmts.md b/doc/fmts.md index cfb875c..cac8061 100644 --- a/doc/fmts.md +++ b/doc/fmts.md @@ -36,11 +36,10 @@ Where | offset_n | 16-bit unsigned integer offset to start of a data entry | | data_entries | series of data entries | -**mask key** is 256-octet long mask key for masking *data* as a whole. It is -randomly generated for each build(i.e. each time proone-mkdvault is invoked). -**offset_***n* is an offset to the start of the *n*th data entry. -**data_entries** is a series of data entries. The format of a data entry is -described blow. +**mask key** is 256-octet long mask key for masking. It is randomly generated +for each build(i.e. each time proone-mkdvault is invoked). **offset_***n* is an +offset to the start of the *n*th data entry. **data_entries** is a series of +data entries. The format of a data entry is described blow. ``` 0 1 2 3 @@ -67,8 +66,8 @@ the data type of the entry data. The definition of the values is described blow. | CSTR | 0x00 | 8-bit narrow character string (UTF-8) | | BIN | 0x02 | binary data in octet units | -Entry data is masked so that it can be accessed and unmasked randomly and -possibly in parallel. +All the fields excluding *salt* are kept masked. Entry data is masked so that it +can be accessed and unmasked randomly and possibly in parallel. ```c for (size_t i = 0; i < size; i += 1) { @@ -83,14 +82,14 @@ Where * mask: the mask key - the 256-elements-long array of 8-bit unsigned integers * salt: the 8-bit unsigned integer salt value -As evident from the algorithm shown above, the salt value simply acts as a -offset to the start of the mask key for the entry. In order to unmask an entry, -the *data_size* field must be unmasked first to determine the length of the -data. Once the length of the data is unmasked, the data part of the masked entry -data can be unmasked using the same algorithm again. When the unmasked data -entry is referenced and no longer needed, the entirety of the data must be -masked back to the original form so that the data entries are kept obsecure in -memory. This should be done immediately by calling `prne_dvault_reset()`. +The salt value simply acts as a offset to the start of the mask key for the +entry. In order to unmask an entry, the *data_size* field must be unmasked first +to determine the length of the data. Once the length of the data is unmasked, +the data part of the masked entry data can be unmasked using the same algorithm. +When the unmasked data entry is referenced and no longer needed, the entirety of +the data must be masked back to the original form so that the data entries are +kept obsecure in memory. This should be done immediately by calling +`prne_dvault_reset()`. Note that the total length of entries can be up to **around** 65,535 octets because offsets are represented in 16-bit unsigned integer values. Since DVault diff --git a/src/bitfield.h b/src/bitfield.h index d1c3dd7..71d0062 100644 --- a/src/bitfield.h +++ b/src/bitfield.h @@ -1,7 +1,8 @@ /** \file The bit field implementation * - * The bit field is a convenience set of functions for representing bits in - * byte arrays. It is much like \c std::bitset but with \c data() equivalent. + * \note The bit field is a convenience set of functions for representing bits + * in byte arrays. It is much like \c std::bitset but with \c data() + * equivalent. */ /* * Copyright (c) 2019-2021 David Timber <mieabby@gmail.com> @@ -33,9 +34,9 @@ /** * \brief Calculate the number of bytes required to store bits - * \param nb_bits (integer value)the number of bits to store. - * Must be zero or greater - * \return the number of bytes required + * \param nb_bits The number of bits to store. + * Must be an integer zero or greater + * \return The number of bytes required */ #define prne_bf_get_size(nb_bits)\ ((nb_bits) % 8 == 0 ? (nb_bits) / 8 : (nb_bits) / 8 + 1) @@ -43,9 +44,9 @@ /** * \brief Function type, to be applied to each bit in the field. See * \see prne_bf_foreach() - * \param ctx the custom context object to be used in the function - * \param bit the index of the bit - * \param v the value of the bit. \c True if set. \c False if unset + * \param ctx The custom context object to be used in the function + * \param bit The index of the bit + * \param v The value of the bit. \c True if set. \c False if unset */ typedef void(*prne_bf_foreach_ft)( void *ctx, @@ -54,19 +55,20 @@ typedef void(*prne_bf_foreach_ft)( /** * \brief Set the bit in the bit field. - * \param bf the bit field to manipulate - * \param bit the index of the bit to manipulate - * \param v the new value of the bit. \c True to set, \c false to unset + * \param bf The bit field to manipulate + * \param bit The index of the bit to manipulate + * \param v The new value of the bit. \c True to set, \c false to unset */ void prne_bf_set (uint8_t *bf, const unsigned int bit, const bool v); /** * \brief Extract the value of the bit in the bit field. - * \param bf the bit field - * \param size the size of the bit field in bytes - * \param bit the index of the bit + * \param bf The bit field + * \param size The size of the bit field in bytes + * \param bit The index of the bit * \note \p size is used to determine if \p bit is out of bounds. The function * regards the bits outside the bounds of the bit field unset(false). - * \return \c True if the bit is set. + * \retval True if the bit is set. + * \retval False if the bit is unset. */ bool prne_bf_test ( const uint8_t *bf, @@ -74,11 +76,11 @@ bool prne_bf_test ( const unsigned int bit); /** * \brief Iterate through the bit field, invoking \p f for each bit. - * \param ctx the custom context to be passed to \p f - * \param bf the bit field - * \param size the size of the bit field in bytes - * \param f the function to be invoked for each bit in the bit field - * \note the number of times \p f is called is always a multiple of 8 regardless + * \param ctx The custom context to be passed to \p f + * \param bf The bit field + * \param size The size of the bit field in bytes + * \param f The function to be invoked for each bit in the bit field + * \note The number of times \p f is called is always a multiple of 8 regardless * of the actual number of bits in the field. */ void prne_bf_foreach ( @@ -113,7 +113,7 @@ struct prne_bne_param { * \brief The destination file name of the Proone executable (required) * \param ctx \c cb_ctx * \return A pointer to a null-terminated string. - * \return Return null to indicate an unsuccessful operation. \c errno + * \retval Null to indicate an unsuccessful operation. \c errno * should be set to an appropriate value. * * \note The returned memory must be writable and freeable with @@ -129,10 +129,10 @@ struct prne_bne_param { * \brief The name of the upload lock file (optional) * \param ctx \c cb_ctx * \return A pointer to a null-terminated string. - * \return Set \c errno to an appropriate value and return null to - * indicate an unsuccessful operation. - * \return Set \c errno to zero and return null to disable the use of - * lock file. + * \retval Null to indicate an unsuccessful operation with \c errno set + * to an appropriate value. + * \retval Null to disable the use of the lock file with \c errno set to + * zero. * * \note The returned memory must be writable and freeable with * \c prne_free() The worker scrubs the string and frees it immediately @@ -151,9 +151,9 @@ struct prne_bne_param { /** * \brief Enter data dictionary callback (optional) * \param ctx \c cb_ctx - * \return False if unable to enter the data dictionary. \c errno must - * be set to an appropriate value. - * \return True otherwise. + * \retval False if unable to enter the data dictionary with \c errno + * set to an appropriate value. + * \retval True otherwise. * * \note \c exit_dd() is guaranteed to be invoked if returned true. * \note The function must always return true if \c cred_dict does not @@ -182,7 +182,7 @@ struct prne_bne_param { * \brief Process uptime enquiry callback (optional) * \param ctx \c cb_ctx * \return The elapsed real time of the parent process in seconds. - * \return \c UINT64_MAX to disable the uptime check for M2M binary + * \retval \c UINT64_MAX to disable the uptime check for M2M binary * upgrade of the local instance or if process uptime information is * unavailable. * \see \c BNE_M2M_UPBIN_INT @@ -197,10 +197,10 @@ struct prne_bne_param { * \brief Proone version comparator callback (optional) * \param ctx \c cb_ctx * \param uuid The version uuid of the remote instance. - * \return A negative integer if \p uuid is newer than that of the local + * \retval A negative integer if \p uuid is newer than that of the local * instance. - * \return Zero if \p uuid is identical to that of the local instance. - * \return A positive integer if \p uuid is older than that of the local + * \retval Zero if \p uuid is identical to that of the local instance. + * \retval A positive integer if \p uuid is older than that of the local * instance. * * \note Always returning zero effectively disables M2M binary upgrade. @@ -224,8 +224,7 @@ struct prne_bne_param { * \c prne_free() * \return An open and valid file descriptor upon successful creation of * temporary file. - * \return A negative integer otherwise. \c errno must be set to an - * appropriate value. + * \retval A negative integer with \c errno set to an appropriate value. * * \note * This is the callback function that the worker uses to create @@ -249,9 +248,10 @@ struct prne_bne_param { * \param path The path to the new executable. * \param cmd The command line arguments without the first element, * which is the path to the executable. - * \return True if the new executable is accepted and no error has - * occurred during the process. False otherwise. \c errno may be set to - * explain why the executable has not been accepted. + * \retval True if the new executable is accepted and no error has + * occurred during the process. + * \retval False otherwise with \c errno set to explain why the + * executable has not been accepted. * * \note * This function is called by the worker upon the successful download of @@ -323,15 +323,17 @@ struct prne_bne_result { */ void prne_init_bne_param (prne_bne_param_t *p); /** - * \brief Free the resources allocated for the BNE worker parameter object. + * \brief Free the resources allocated for the BNE worker parameter object * \param p The pointer to the object that has been initialised using * \c prne_init_bne_param() */ void prne_free_bne_param (prne_bne_param_t *p); /** - * \brief Convert the enum value to a string describing the enum value + * \brief Convert the enum value to a descriptive string * \return A pointer to the string from the read-only static string pool. + * \retval Null if \p v is out of bounds of the valid range with \c errno set to + * \c EINVAL */ const char *prne_bne_vector_tostr (const prne_bne_vector_t v); diff --git a/src/build-utils.sh b/src/build-utils.sh index 2ae926b..22b5208 100755 --- a/src/build-utils.sh +++ b/src/build-utils.sh @@ -1,4 +1,11 @@ #!/bin/bash +## \file +# \brief Convenience shell functions for fabrication of Proone executables +# \param 1 The subcommand. One of align-size, align-file, append-uint32 or +# append-uint16 +# \param 2 or greator: arguments to the subcommand. +# \note These shell functions are used in the Automake recipe to facilitate +# extra unconventional steps to build Proone executables. # Copyright (c) 2019-2021 David Timber <mieabby@gmail.com> # @@ -20,6 +27,11 @@ # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE # SOFTWARE. +## +# \brief Align size x to y +# \param 1 The alignment. +# \param 2 The size to align. +# \return The aligned size. cmd_align-size () { local aligned @@ -40,6 +52,10 @@ cmd_align-size () { return 0 } +## +# \brief Align the size of the file using truncate +# \param 1 The alignment. +# \param 2 The path to the file to align. cmd_align-file () { if [ $# -lt 2 ]; then echo "Usage: $0 <alignment> <file>" >&2 @@ -49,6 +65,10 @@ cmd_align-file () { truncate -s $("$SELF" align-size "$1" $(stat -c "%s" $2)) "$2" } +## +# \brief Append a 32-bit unsigned integer to the file, MSB first +# \param 1 The integer value to append +# \param 2 The file to append the integer to cmd_append-uint32 () { local a b c d @@ -68,6 +88,10 @@ cmd_append-uint32 () { printf "\\x$a\\x$b\\x$c\\x$d" >> "$2" } +## +# \brief Append a 16-bit unsigned integer to the file, MSB first +# \param 1 The integer value to append +# \param 2 The file to append the integer to cmd_append-uint16 () { local a b diff --git a/src/config.h b/src/config.h index 92932de..1b2a746 100644 --- a/src/config.h +++ b/src/config.h @@ -1,3 +1,10 @@ +/** \file + * \brief The general project configuration + * \note This header defines "static" macros, which include system config + * detection mechanism, option values for external libraries used across the + * project and project meta data such as version info. + * + */ /* * Copyright (c) 2019-2021 David Timber <mieabby@gmail.com> * @@ -32,6 +39,10 @@ #include <zlib.h> +/** \def PRNE_HOST_WORDSIZE + * \brief Th system "word size". 32 if the system is a 32-bit machine. 64 if the + * system is a 64-bit machine. + */ #if INTPTR_MAX == INT32_MAX #define PRNE_HOST_WORDSIZE 32 #elif INTPTR_MAX == INT64_MAX @@ -40,29 +51,51 @@ #error "FIXME!" #endif +// The program version #define PRNE_PROG_VER {\ 0x11, 0xf7, 0x6b, 0x87, 0x62, 0x1a, 0x47, 0x9c,\ 0xa2, 0x18, 0x5c, 0x55, 0x40, 0x33, 0x7c, 0x9f\ } +/** + * \brief The shared global file name salt value + * \note This is the protocol uuid used as the salt value for calculating the + * hashed name of the shm file. + * \see prne_shared_global + */ #define PRNE_SHG_SALT {\ 0x31, 0xe4, 0xf1, 0x7c, 0xdb, 0x76, 0x43, 0x32,\ 0xaf, 0x48, 0xfd, 0x9f, 0xb8, 0x45, 0x3f, 0x8f\ } +/** + * \brief The version matrix + * \note The version matrix is a array of previous known version uuids of + * Proone. The byte size of the array must be a multiple of 16. + * \note If there's no previous version, the array must contain one or more + * placeholder versions because the ISO-C does not allow empty initialiser + * lists. The placeholder versions may be used to reserve uuids for future + * versions. + */ #define PRNE_VER_MAT {\ /* 76f2f748-3b6f-420c-abd7-e9929a0b67d6: placeholder version 1 */\ - /* Remove it when you add the first old version */\ + /* Remove/replace it when you add the first old version */\ 0x76, 0xf2, 0xf7, 0x48, 0x3b, 0x6f, 0x42, 0x0c,\ 0xab, 0xd7, 0xe9, 0x92, 0x9a, 0x0b, 0x67, 0xd6,\ /* ce6fe199-5595-49a1-96c6-261d1cce9e32: placeholder version 2 */\ - /* Remove it when you add the first old version */\ + /* Remove/replace it when you add the first old version */\ 0xce, 0x6f, 0xe1, 0x99, 0x55, 0x95, 0x49, 0xa1,\ 0x96, 0xc6, 0x26, 0x1d, 0x1c, 0xce, 0x9e, 0x32\ } +// The common zlib compression level #define PRNE_PACK_Z_LEVEL Z_DEFAULT_COMPRESSION -// PRNE_HOST_ARCH +/** \def PRNE_HOST_ARCH + * \brief The system CPU architecture + * \note Compiler-specific macros are used. Expand this macro to support other + * compilers. + * \see prne_arch_t + */ #ifdef __GNUC__ #if defined(__i386__) #define PRNE_HOST_ARCH PRNE_ARCH_I686 @@ -103,7 +136,12 @@ #error "FIXME!" #endif -// PRNE_HOST_OS +/** \def PRNE_HOST_OS + * \brief The system operating system + * \note Compiler-specific macros are used. Expand this macro to support other + * compilers. + * \see prne_os_t + */ #ifdef __GNUC__ #if defined(__linux__) #define PRNE_HOST_OS PRNE_OS_LINUX diff --git a/src/cred_dict.h b/src/cred_dict.h index b07bb4a..2528a5d 100644 --- a/src/cred_dict.h +++ b/src/cred_dict.h @@ -1,3 +1,6 @@ +/** \file + * \brief The credential dictionary implementation + */ /* * Copyright (c) 2019-2021 David Timber <mieabby@gmail.com> * @@ -24,37 +27,73 @@ #include <stddef.h> #include <stdbool.h> - +/* Alias declaration */ typedef struct prne_cred_dict_entry prne_cred_dict_entry_t; typedef struct prne_cred_dict_raw_entry prne_cred_dict_raw_entry_t; typedef struct prne_cred_dict prne_cred_dict_t; +// The index entry object struct prne_cred_dict_entry { - uint16_t id; - uint16_t pw; - uint8_t weight; + uint16_t id; // Index of start of the user name + uint16_t pw; // Index of start of the password + uint8_t weight; // The weight value }; +// The raw entry entry object used to build the dictionary struct prne_cred_dict_raw_entry { - char *id; - char *pw; - uint8_t weight; + char *id; // Pointer to the user name string + char *pw; // Pointer to the password string + uint8_t weight; // Weight value }; +// The dictionary object struct prne_cred_dict { - const char *m; + const char *m; // Pointer to the string pool prne_cred_dict_entry_t *arr; size_t cnt; }; +/** + * \brief Initialise the credential dictionary object + * \note Initialises the members of \p p to initial values. Prepares \p p so + * that it can be freed using \c prne_free_cred_dict() + */ void prne_init_cred_dict (prne_cred_dict_t *p); +/** + * \brief Free the resources allocated for the credential dictionary object. + * \param p The pointer to the object that has been initialised using + * \c prne_init_cred_dict() + */ void prne_free_cred_dict (prne_cred_dict_t *p); +/** + * \brief Build a credential dictionary + * \param arr The raw entries. + * \param cnt The number of entries in \p arr + * \param[out] out_m The serialised credential dictionary deserialisable with + * \c prne_dser_cred_dict(). The returned memory is freeable with + * \c prne_free(). + * \param[out] out_l The length of \p out_m in bytes. + * \retval True if successful. + * \retval False on error with \c errno set to an appropriate value. + * \note The size of the binary credential dictionary is limited to 2^16 bytes + * as indices are 16-bit integers. \c E2BIG is used to indicate this error. + */ bool prne_build_cred_dict ( const prne_cred_dict_raw_entry_t *arr, const size_t cnt, uint8_t **out_m, size_t *out_l); +/** + * \brief Deserialise the credential dictionary + * \param[out] dict The output object. Must be initiaised with + * \c prne_init_cred_dict() beforehand. + * \param buf The pointer to the memory containing the serialised credential + * dictionary. + * \param len The readable length of \p buf in bytes. + * \retval True on successful parsing and allocation of \p dict members. + * \retval False otherwise with \c errno set to an appropriate value. + */ bool prne_dser_cred_dict ( prne_cred_dict_t *dict, const uint8_t *buf, @@ -1,3 +1,8 @@ +/** \file + * \brief The data vault entry key definitions + * \note This header defines \c prne_data_key_t. The enum is defined in the + * separate header for ease of use with VCS. + */ /* * Copyright (c) 2019-2021 David Timber <mieabby@gmail.com> * @@ -23,29 +28,35 @@ #include "util_ct.h" +/** + * \brief The data vault entry key enum + * \note Suitable storage type: int8_t + */ typedef enum { - PRNE_DATA_KEY_NONE = -1, + PRNE_DATA_KEY_NONE = -1, // Null value - PRNE_DATA_KEY_PROG_VER, - PRNE_DATA_KEY_SHG_SALT, - PRNE_DATA_KEY_X509_CA_CRT, - PRNE_DATA_KEY_X509_DH, - PRNE_DATA_KEY_X509_S_CRT, - PRNE_DATA_KEY_X509_S_KEY, - PRNE_DATA_KEY_X509_C_CRT, - PRNE_DATA_KEY_X509_C_KEY, - PRNE_DATA_KEY_RESOLV_NS_IPV4, - PRNE_DATA_KEY_RESOLV_NS_IPV6, - PRNE_DATA_KEY_CNC_TXT_REC, + PRNE_DATA_KEY_PROG_VER, // The 16-byte program version uuid + PRNE_DATA_KEY_SHG_SALT, // The 16-byte shared global salt value + PRNE_DATA_KEY_X509_CA_CRT, // The heartbeat PKI CA certificate chain + PRNE_DATA_KEY_X509_DH, // The heartbeat PKI DH param + PRNE_DATA_KEY_X509_S_CRT, // The heartbeat PKI server certificate + PRNE_DATA_KEY_X509_S_KEY, // The heartbeat PKI server private key + PRNE_DATA_KEY_X509_C_CRT, // The heartbeat PKI client certificate + PRNE_DATA_KEY_X509_C_KEY, // The heartbeat PKI client private key + PRNE_DATA_KEY_RESOLV_NS_IPV4, // The resolv IPv4 DNS name server pool + PRNE_DATA_KEY_RESOLV_NS_IPV6, // The resolv IPv6 DNS name server pool + PRNE_DATA_KEY_CNC_TXT_REC, // The name of the heartbeat CNC TXT record + // The destination ports of the SYN packets crafted by the recon worker PRNE_DATA_KEY_RCN_PORTS, - PRNE_DATA_KEY_RCN_T_IPV4, - PRNE_DATA_KEY_RCN_BL_IPV4, - PRNE_DATA_KEY_RCN_T_IPV6, - PRNE_DATA_KEY_RCN_BL_IPV6, - PRNE_DATA_KEY_CRED_DICT, + PRNE_DATA_KEY_RCN_T_IPV4, // The target recon IPv4 networks + PRNE_DATA_KEY_RCN_BL_IPV4, // The blacklist recon IPv4 networks + PRNE_DATA_KEY_RCN_T_IPV6, // The target recon IPv6 networks + PRNE_DATA_KEY_RCN_BL_IPV6, // The blacklist recon IPv6 networks + PRNE_DATA_KEY_CRED_DICT, // The serialised credential dictionary + // The name of the Proone executable. Used by the BNE worker. PRNE_DATA_KEY_EXEC_NAME, - PRNE_DATA_KEY_VER_MAT, - PRNE_DATA_KEY_BNE_LOCK_NAME, + PRNE_DATA_KEY_VER_MAT, // The version matrix + PRNE_DATA_KEY_BNE_LOCK_NAME, // The name of the BNE lock file - NB_PRNE_DATA_KEY + NB_PRNE_DATA_KEY // Meta value: the number of enums excluding the null value } prne_data_key_t; diff --git a/src/dvault.h b/src/dvault.h index 3c1872e..0f52518 100644 --- a/src/dvault.h +++ b/src/dvault.h @@ -1,3 +1,6 @@ +/** \file + * \brief The data vault implementation + */ /* * Copyright (c) 2019-2021 David Timber <mieabby@gmail.com> * @@ -27,36 +30,69 @@ #include <stdbool.h> #include <stdint.h> - +/* Alias declarations */ typedef struct prne_dvault_mask_result prne_dvault_mask_result_t; typedef struct prne_dvault prne_dvault_t; +/** + * \brief The data type for the entry + * \note Suitable storage type: int8_t + */ typedef enum { - PRNE_DATA_TYPE_NONE = -1, + PRNE_DATA_TYPE_NONE = -1, // Null value + // Null-terminated narrow character string, usually in UTF-8 encoding PRNE_DATA_TYPE_CSTR, - PRNE_DATA_TYPE_BIN, + PRNE_DATA_TYPE_BIN, // Binary data - NB_PRNE_DATA_TYPE + NB_PRNE_DATA_TYPE // Meta value: the number of enums } prne_data_type_t; PRNE_LIMIT_ENUM(prne_data_type_t, NB_PRNE_DATA_TYPE, 0xFF); +// The masking operation result code typedef enum { - PRNE_DVAULT_MASK_OK, - PRNE_DVAULT_MASK_MEM_ERR, - PRNE_DVAULT_MASK_TOO_LARGE, - PRNE_DVAULT_MASK_INVALID_TYPE + PRNE_DVAULT_MASK_OK, // Success + PRNE_DVAULT_MASK_MEM_ERR, // Memory allocation error + PRNE_DVAULT_MASK_TOO_LARGE, // Entry data too large + PRNE_DVAULT_MASK_INVALID_TYPE // Invalid prne_data_type_t } prne_dvault_mask_result_code_t; +// The masking operation result object struct prne_dvault_mask_result { - size_t size; - uint8_t *data; + size_t size; // The length of data in bytes + uint8_t *data; // The masked data + /* The result code. + * size and data are valid only if the result code is PRNE_DVAULT_MASK_OK. + */ prne_dvault_mask_result_code_t result; }; +/** + * \brief Convert the enum value to a descriptive string + * \return A pointer to the string from the read-only static string pool. + * \retval Null if \p t is out of bounds of the valid range with \c errno set to + * \c EINVAL + */ const char *prne_data_type_tostr (const prne_data_type_t t); +/** + * \brief The inverse function of \c prne_data_type_tostr() + * \retval PRNE_DATA_TYPE_NONE if \p str does not match any enum. \c errno set + * to \c EINVAL + * \return The parsed enum + */ prne_data_type_t prne_data_type_fstr (const char *str); +/** + * \brief Mask or unmask memory using parameters + * \param size The length of \p m, in bytes, to invert. + * \param m The memory to invert + * \param salt The salt offset + * \param salt_ofs The offset in addition to \p salt + * \param mask The pointer to the 256-byte mask key + * \note This is a primitve function that "inverts" a portion of memory to mask + * the original data or to unmask the masked data. + * \note The final offset is \p salt plus \p salt_ofs. + */ void prne_dvault_invert_mem ( const size_t size, void *m, @@ -64,30 +100,84 @@ void prne_dvault_invert_mem ( const size_t salt_ofs, const uint8_t *mask); +/** + * \brief Initialise the data vault masking operation result object + * \note Initialises the members of \p r to initial values. Prepares \p r so + * that it can be freed using \c prne_free_dvault_mask_result() + */ void prne_init_dvault_mask_result (prne_dvault_mask_result_t *r); +/** + * \brief Free the resources allocated for the the data vault masking operation + * result object + * \param p The pointer to the object that has been initialised using + * \c prne_init_dvault_mask_result() + */ void prne_free_dvault_mask_result (prne_dvault_mask_result_t *r); +/** + * \brief Mask the source data + * \param type The data type of the source data. + * \param salt The randomly generated salt value. + * \param mask The 256-byte mask key. + * \param data_size The length of \p data in bytes. + * \param data The source data. + * \return An instance of the data vault masking operation object, with memory + * allocated to return the masked data. The instance must always be freed using + * \c prne_free_dvault_mask_result() regardless of the result code. + */ prne_dvault_mask_result_t prne_dvault_mask ( const prne_data_type_t type, const uint8_t salt, const uint8_t *mask, const size_t data_size, const uint8_t *data); +/** + * \brief Convert the enum value to a descriptive string + * \return A pointer to the string from the read-only static string pool. + * \retval Null if \p code is out of bounds of the valid range with \c errno set + * to \c EINVAL + */ const char *prne_dvault_mask_result_tostr ( const prne_dvault_mask_result_code_t code); -/* prne_init_dvault(const void *m) -* -* ARGS: -* m: pointer to start of readable and writable a dvault made by -* proone-mkdvault. This region of memory must be writable. -*/ +/** + * \brief Initialise the internal global variables with the data vault binary + * \param m The pointer to the binary data dump. The memory must be readable and + * writeable. The data dump is produced by proone-mkdvault + * \note The function cannot be called again without calling + * \c prne_deinit_dvault() beforehand. + * \warning The behaviour is undefined if the data at \p m is not valid. + */ void prne_init_dvault (const void *m); -/* prne_deinit_dvault (const void *m) -* -* Calls prne_dvault_reset(). Revert changes to the data vault memory. -*/ +/** + * \brief Deinitialise the internal global variables and resources allocated for + * the data vault + * \note \c prne_init_dvault() can be called when the function returns. + */ void prne_deinit_dvault (void); -// len: strlen() +/** + * \brief Unmask and get the pointer to the string from the entry + * \param key The key to the entry. + * \param[out] len (optional)The length of the string, excluding the null + * terminator. + * \return The pointer to the unmasked string from the entry. + * \warning The behaviour is undefined if the data entry at \p key is not of + * string or \p key is out of bounds. + */ const char *prne_dvault_get_cstr (const prne_data_key_t key, size_t *len); +/** + * \brief Unmask and get the pointer to the binary data from the entry + * \param key The key to the entry. + * \param[out] len (optional)The length of the data in bytes. + * \return The pointer to the unmasked binary data from the entry. + * \warning The behaviour is undefined if the data entry at \p key is not of + * binary data or \p key is out of bounds. + */ const uint8_t *prne_dvault_get_bin (const prne_data_key_t key, size_t *len); +/** + * \brief Mask all the data currently unmmasked + * \note This function has to be called soon after the unmasked data entry is + * no longer required. + * \warning The behaviour is undefined if the data vault is not initialised with + * \c prne_init_dvault() + */ void prne_dvault_reset (void); |