1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
#ifndef SESSION_CIPHER_H
#define SESSION_CIPHER_H
#include <stdint.h>
#include <stddef.h>
#include "axolotl_types.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* The main entry point for Axolotl encrypt/decrypt operations.
*
* Once a session has been established with session_builder,
* this class can be used for all encrypt/decrypt operations within
* that session.
*/
/**
* Construct a session cipher for encrypt/decrypt operations on a session.
* In order to use session_cipher, a session must have already been created
* and stored using session_builder.
*
* The store and global contexts must remain valid for the lifetime of the
* session cipher.
*
* When finished, free the returned instance by calling session_cipher_free().
*
* @param cipher set to a freshly allocated session cipher instance
* @param store the axolotl_store_context to store all state information in
* @param remote_address the remote address 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 session_cipher_create(session_cipher **cipher,
axolotl_store_context *store, const axolotl_address *remote_address,
axolotl_context *global_context);
/**
* Set the optional user data pointer for the session cipher.
*
* This is to give callback functions a way of accessing app specific
* context information for this cipher.
*/
void session_cipher_set_user_data(session_cipher *cipher, void *user_data);
/**
* Get the optional user data pointer for the session cipher.
*
* This is to give callback functions a way of accessing app specific
* context information for this cipher.
*/
void *session_cipher_get_user_data(session_cipher *cipher);
/**
* Set the callback function that is called during the decrypt process.
*
* The callback function is called from within
* session_cipher_decrypt_pre_key_whisper_message() and
* session_cipher_decrypt_whisper_message() 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
* @param user_data user data pointer provided to the callback
*/
void session_cipher_set_decryption_callback(session_cipher *cipher,
int (*callback)(session_cipher *cipher, axolotl_buffer *plaintext, void *decrypt_context));
/**
* Encrypt a message.
*
* @param padded_message The plaintext message bytes, optionally padded to a constant multiple.
* @param padded_message_len The length of the data pointed to by padded_message
* @param encrypted_message Set to a ciphertext message encrypted to the recipient+device tuple.
*
* @return AX_SUCCESS on success, negative on error
*/
int session_cipher_encrypt(session_cipher *cipher,
const uint8_t *padded_message, size_t padded_message_len,
ciphertext_message **encrypted_message);
/**
* Decrypt a message.
*
* @param ciphertext The pre_key_whisper_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 AX_SUCCESS Success
* @retval AX_ERR_INVALID_MESSAGE if the input is not valid ciphertext.
* @retval AX_ERR_DUPLICATE_MESSAGE if the input is a message that has already been received.
* @retval AX_ERR_LEGACY_MESSAGE if the input is a message formatted by a protocol version that
* is no longer supported.
* @retval AX_ERR_INVALID_KEY_ID when there is no local pre_key_record
* that corresponds to the pre key ID in the message.
* @retval AX_ERR_INVALID_KEY when the message is formatted incorrectly.
* @retval AX_ERR_UNTRUSTED_IDENTITY when the identity key of the sender is untrusted.
*/
int session_cipher_decrypt_pre_key_whisper_message(session_cipher *cipher,
pre_key_whisper_message *ciphertext, void *decrypt_context,
axolotl_buffer **plaintext);
/**
* Decrypt a message.
*
* @param ciphertext The whisper_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 AX_SUCCESS Success
* @retval AX_ERR_INVALID_MESSAGE if the input is not valid ciphertext.
* @retval AX_ERR_DUPLICATE_MESSAGE if the input is a message that has already been received.
* @retval AX_ERR_LEGACY_MESSAGE if the input is a message formatted by a protocol version that
* is no longer supported.
* @retval AX_ERR_NO_SESSION if there is no established session for this contact.
*/
int session_cipher_decrypt_whisper_message(session_cipher *cipher,
whisper_message *ciphertext, void *decrypt_context,
axolotl_buffer **plaintext);
/**
* Gets the remote registration ID for this session cipher.
*
* @param remote_id Set to the value of the remote registration ID
*
* @return AX_SUCCESS on success, negative on error
*/
int session_cipher_get_remote_registration_id(session_cipher *cipher, uint32_t *remote_id);
/**
* Gets the version of the session associated with this session cipher.
*
* @param version Set to the value of the session version
*
* @retval AX_SUCCESS Success
* @retval AX_ERR_NO_SESSION if no session could be found
*/
int session_cipher_get_session_version(session_cipher *cipher, uint32_t *version);
void session_cipher_free(session_cipher *cipher);
#ifdef __cplusplus
}
#endif
#endif /* SESSION_CIPHER_H */
|
