From 8e89151ab5dbc6e2592d361ca4e55ab057d708de Mon Sep 17 00:00:00 2001 From: Xavrax Date: Mon, 11 Sep 2023 12:58:12 +0200 Subject: [PATCH] 1st version of API --- core/pubnub_crypto.h | 154 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 122 insertions(+), 32 deletions(-) diff --git a/core/pubnub_crypto.h b/core/pubnub_crypto.h index e4c2643b..bfe78b26 100644 --- a/core/pubnub_crypto.h +++ b/core/pubnub_crypto.h @@ -18,13 +18,49 @@ */ -/** Cryptor algorithm type. +/** + Encrypted data structure. + */ +struct pubnub_encrypted_data { + /** Encrypted data. */ + struct pubnub_char_mem_block data; + + /** Metadata. + + Cryptor may provide here any information which will be usefull when data + should be decrypted. + + For example `metadata` may contain: + - initialization vector + - cipher key Identifier + - encrypted *data* length + */ + struct pubnub_char_mem_block metadata; +}; + + +/** Cryptor header version 1. + + This is the struct containing the information about the + cryptor header version 1. It contains the identifier of the + algorithm and the encrypted data length. + */ +struct pubnub_cryptor_header_v1 { + /** Cryptor algorithm identifier. */ + uint8_t identifier[4]; + + /** Encrypted data length. */ + uint32_t data_length; +}; + + +/** Crypto algorithm type. This is the struct containing the information about the cryptor algorithm type. It contains the identifier of the algorithm and the function pointers to the algorithm implementation. */ -typedef struct pubnub_cryptor_t { +typedef struct pubnub_crypto_algorithm_t { /** Identifier of the algorithm. Identifier will be encoded into crypto data header and passed along @@ -40,12 +76,12 @@ typedef struct pubnub_cryptor_t { @param cryptor Pointer to the cryptor structure. @param msg Memory block (pointer and size) of the data to encrypt. @param base64_str String (allocated by the user) to write encrypted and - base64 encoded string. + base64 encoded string. @param n The size of the string. @return 0: OK, -1: error */ - int (*encrypt)(struct pubnub_cryptor_t const *cryptor, pubnub_bymebl_t msg, char *base64_str, size_t n); + int (*encrypt)(struct pubnub_crypto_algorithm_t const *cryptor, struct pubnub_encrypted_data msg, char *base64_str, size_t n); // TODO: return type - int or enum? /** Function pointer to the decrypt function. @@ -56,42 +92,96 @@ typedef struct pubnub_cryptor_t { @return 0: OK, -1: error */ - int (*decrypt)(struct pubnub_cryptor_t const *cryptor, char const *base64_str, size_t n, pubnub_bymebl_t *data); -} pubnub_cryptor; + int (*decrypt)(struct pubnub_crypto_algorithm_t const *cryptor, char const *base64_str, size_t n, struct pubnub_encrypted_data *data); -/** - Encrypted data structure. - */ -struct pubnub_encrypted_data { - /** Encrypted data. */ - struct pubnub_char_mem_block data; + /** Pointer to the user data needed for the algorithm. */ + void *user_data; - /** Metadata. - - Cryptor may provide here any information which will be usefull when data - should be decrypted. +} pubnub_crypto_algorithm_t; - For example `metadata` may contain: - - initialization vector - - cipher key Identifier - - encrypted *data* length - */ - struct pubnub_char_mem_block metadata; -}; -/** Cryptor header version 1. +/** Crypto algorithm wrapper This is the struct containing the information about the - cryptor header version 1. It contains the identifier of the - algorithm and the encrypted data length. + abstract cryptor algorithm. It wraps the algorithm implementation + and provides the interface to the Pubnub client library. */ -struct pubnub_cryptor_header_v1 { - /** Cryptor algorithm identifier. */ - uint8_t identifier[4]; +typedef struct pubnub_cryptor_t { + /** Cryptor algorithm for data encription / decryption. */ + struct pubnub_crypto_algorithm_t algorithm; + +} pubnub_cryptor; + + +/** Retrieves the cryptor algorithm identifier. + + @param cryptor Pointer to the cryptor structure. + + @return Pointer to the cryptor algorithm identifier. + */ +uint8_t const *pubnub_cryptor_identifier(pubnub_cryptor const *cryptor); + + +// TODO: return type - int or enum? +/** Encrypt provided data. + + @param cryptor Pointer to the cryptor structure. + @param msg The memory block (pointer and size) of the data to encrypt. + @param base64_block The char block (pointer and size) to write encrypted and + base64 encoded string. + + @return 0: OK, -1: error + */ +int pubnub_cryptor_encrypt(pubnub_cryptor const *cryptor, pubnub_bymebl_t const *msg, pubnub_chamebl_t base64_block); + + +// TODO: return type - int or enum? +/** Decrypt provided data. + + @param cryptor Pointer to the cryptor structure. + @param base64_block The char block (pointer and size) to Base64 decode and decrypt. + @param data User allocated memory block to write the decrypted contents to. + + @return 0: OK, -1: error + */ +int pubnub_cryptor_decrypt(pubnub_cryptor const *cryptor, pubnub_chamebl_t const *base64_block, pubnub_bymebl_t *data); + + +/** Cryptor module for data processing. */ +typedef struct pubnub_crypto_module_t { + /** Array of the cryptor algorithms. */ + struct pubnub_crypto_algorithm_t *algorithms; + + /** Number of the cryptor algorithms. */ + size_t algorithms_n; + +} pubnub_crypto_module; + + +// TODO: return type - int or enum? +/** Encrypt provided data. + + @param module crypto module Pointer to the cryptor module structure. + @param msg The memory block (pointer and size) of the data to encrypt. + @param base64_block The char block (pointer and size) to write encrypted and + base64 encoded string. + + @return 0: OK, -1: error + */ +int pubnub_crypto_module_encrypt(pubnub_crypto_module const *module, pubnub_bymebl_t const *msg, pubnub_chamebl_t base64_block); + + +// TODO: return type - int or enum? +/** Decrypt provided data. + + @param module crypto module Pointer to the cryptor module structure. + @param base64_block The char block (pointer and size) to Base64 decode and decrypt. + @param data User allocated memory block to write the decrypted contents to. + + @return 0: OK, -1: error + */ +int pubnub_crypto_module_decrypt(pubnub_crypto_module const *module, pubnub_chamebl_t const *base64_block, pubnub_bymebl_t *data); - /** Encrypted data length. */ - uint32_t data_length; -}; /** Sets @p secret_key to be used with the Pubnub context @p p.