diff options
Diffstat (limited to 'libs/libsignal/src/group_cipher.h')
-rw-r--r-- | libs/libsignal/src/group_cipher.h | 114 |
1 files changed, 114 insertions, 0 deletions
diff --git a/libs/libsignal/src/group_cipher.h b/libs/libsignal/src/group_cipher.h new file mode 100644 index 0000000000..50b194c06f --- /dev/null +++ b/libs/libsignal/src/group_cipher.h @@ -0,0 +1,114 @@ +#ifndef GROUP_CIPHER_H +#define GROUP_CIPHER_H + +#include <stdint.h> +#include <stddef.h> +#include "signal_protocol_types.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* + * The main entry point for Signal Protocol group encrypt/decrypt operations. + * + * Once a session has been established with group_session_builder and a + * sender_key_distribution_message has been distributed to each member of + * the group, this class can be used for all subsequent encrypt/decrypt + * operations within that session (i.e. until group membership changes). + */ + +/** + * Construct a group cipher for encrypt/decrypt operations. + * + * The store and global contexts must remain valid for the lifetime of the + * group cipher. + * + * When finished, free the returned instance by calling group_cipher_free(). + * + * @param cipher set to a freshly allocated group cipher instance + * @param store the signal_protocol_store_context to store all state information in + * @param sender_key_id the sender that messages will be encrypted to or decrypted from + * @param global_context the global library context + * @return 0 on success, or negative on failure + */ +int group_cipher_create(group_cipher **cipher, + signal_protocol_store_context *store, const signal_protocol_sender_key_name *sender_key_id, + signal_context *global_context); + +/** + * Set the optional user data pointer for the group cipher. + * + * This is to give callback functions a way of accessing app specific + * context information for this cipher. + */ +void group_cipher_set_user_data(group_cipher *cipher, void *user_data); + +/** + * Get the optional user data pointer for the group cipher. + * + * This is to give callback functions a way of accessing app specific + * context information for this cipher. + */ +void *group_cipher_get_user_data(group_cipher *cipher); + +/** + * Set the callback function that is called during the decrypt process. + * + * The callback function is called from within group_cipher_decrypt() after + * decryption is complete but before the updated session state has been + * committed to the session store. If the callback function returns a + * negative value, then the decrypt function will immediately fail with + * an error. + * + * This a callback allows some implementations to store the committed plaintext + * to their local message store first, in case they are concerned with a crash + * or write error happening between the time the session state is updated but + * before they're able to successfully store the plaintext to disk. + * + * @param callback the callback function to set + */ +void group_cipher_set_decryption_callback(group_cipher *cipher, + int (*callback)(group_cipher *cipher, signal_buffer *plaintext, void *decrypt_context)); + +/** + * Encrypt a message. + * + * @param padded_plaintext The plaintext message bytes, optionally padded to a constant multiple. + * @param padded_plaintext_len The length of the data pointed to by padded_message + * @param encrypted_message Set to a ciphertext message encrypted to the group+sender+device tuple. + * + * @retval SG_SUCCESS Success + * @retval SG_ERR_NO_SESSION if there is no established session for this contact. + * @retval SG_ERR_INVALID_KEY if there is no valid private key for this session. + */ +int group_cipher_encrypt(group_cipher *cipher, + const uint8_t *padded_plaintext, size_t padded_plaintext_len, + ciphertext_message **encrypted_message); + +/** + * Decrypt a message. + * + * @param ciphertext The sender_key_message to decrypt. + * @param decrypt_context Optional context pointer associated with the + * ciphertext, which is passed to the decryption callback function + * @param plaintext Set to a newly allocated buffer containing the plaintext. + * + * @retval SG_SUCCESS Success + * @retval SG_ERR_INVALID_MESSAGE if the input is not valid ciphertext. + * @retval SG_ERR_DUPLICATE_MESSAGE if the input is a message that has already been received. + * @retval SG_ERR_LEGACY_MESSAGE if the input is a message formatted by a protocol version that + * is no longer supported. + * @retval SG_ERR_NO_SESSION if there is no established session for this contact. + */ +int group_cipher_decrypt(group_cipher *cipher, + sender_key_message *ciphertext, void *decrypt_context, + signal_buffer **plaintext); + +void group_cipher_free(group_cipher *cipher); + +#ifdef __cplusplus +} +#endif + +#endif /* GROUP_CIPHER_H */ |