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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
/* Copyright 2015 OpenMarket Ltd
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#include "axolotl/crypto.hh"
#include "axolotl/list.hh"
namespace axolotl {
class Cipher;
typedef std::uint8_t SharedKey[32];
struct ChainKey {
std::uint32_t index;
SharedKey key;
};
struct MessageKey {
std::uint32_t index;
SharedKey key;
};
struct SenderChain {
Curve25519KeyPair ratchet_key;
ChainKey chain_key;
};
struct ReceiverChain {
Curve25519PublicKey ratchet_key;
ChainKey chain_key;
};
struct SkippedMessageKey {
Curve25519PublicKey ratchet_key;
MessageKey message_key;
};
enum struct ErrorCode {
SUCCESS = 0, /*!< There wasn't an error */
NOT_ENOUGH_RANDOM = 1, /*!< Not enough entropy was supplied */
OUTPUT_BUFFER_TOO_SMALL = 2, /*!< Supplied output buffer is too small */
BAD_MESSAGE_VERSION = 3, /*!< The message version is unsupported */
BAD_MESSAGE_FORMAT = 4, /*!< The message couldn't be decoded */
BAD_MESSAGE_MAC = 5, /*!< The message couldn't be decrypted */
};
static std::size_t const MAX_RECEIVER_CHAINS = 5;
static std::size_t const MAX_SKIPPED_MESSAGE_KEYS = 40;
struct KdfInfo {
std::uint8_t const * root_info;
std::size_t root_info_length;
std::uint8_t const * ratchet_info;
std::size_t ratchet_info_length;
};
struct Session {
Session(
KdfInfo const & kdf_info,
Cipher const & ratchet_cipher
);
/** A some strings identifying the application to feed into the KDF. */
KdfInfo const & kdf_info;
/** The AEAD cipher to use for encrypting messages. */
Cipher const & ratchet_cipher;
/** The last error that happened encrypting or decrypting a message. */
ErrorCode last_error;
/** The root key is used to generate chain keys from the ephemeral keys.
* A new root_key derived each time a chain key is derived. */
SharedKey root_key;
/** The sender chain is used to send messages. Each time a new ephemeral
* key is received from the remote server we generate a new sender chain
* with a new empheral key when we next send a message. */
List<SenderChain, 1> sender_chain;
/** The receiver chain is used to decrypt received messages. We store the
* last few chains so we can decrypt any out of order messages we haven't
* received yet. */
List<ReceiverChain, MAX_RECEIVER_CHAINS> receiver_chains;
/** List of message keys we've skipped over when advancing the receiver
* chain. */
List<SkippedMessageKey, MAX_SKIPPED_MESSAGE_KEYS> skipped_message_keys;
/** Initialise the session using a shared secret and the public part of the
* remote's first ratchet key */
void initialise_as_bob(
std::uint8_t const * shared_secret, std::size_t shared_secret_length,
Curve25519PublicKey const & their_ratchet_key
);
/** Initialise the session using a shared secret and the public/private key
* pair for the first ratchet key */
void initialise_as_alice(
std::uint8_t const * shared_secret, std::size_t shared_secret_length,
Curve25519KeyPair const & our_ratchet_key
);
/** The number of bytes needed to persist the current session. */
std::size_t pickle_max_output_length();
/** Persists a session as a sequence of bytes, encrypting using a key
* Returns the number of output bytes used. */
std::size_t pickle(
std::uint8_t const * key, std::size_t key_length,
std::uint8_t * output, std::size_t max_output_length
);
/** Loads a session from a sequence of bytes, decrypting using a key.
* Returns 0 on success, or std::size_t(-1) on failure. The last_error
* will be BAD_SESSION_KEY if the supplied key is incorrect. */
std::size_t unpickle(
std::uint8_t const * key, std::size_t key_length,
std::uint8_t * input, std::size_t input_length
);
/** The maximum number of bytes of output the encrypt method will write for
* a given message length. */
std::size_t encrypt_max_output_length(
std::size_t plaintext_length
);
/** The number of bytes of random data the encrypt method will need to
* encrypt a message. This will be 32 bytes if the session needs to
* generate a new ephemeral key, or will be 0 bytes otherwise.*/
std::size_t encrypt_random_length();
/** Encrypt some plain-text. Returns the length of the encrypted message
* or std::size_t(-1) on failure. On failure last_error will be set with
* an error code. The last_error will be NOT_ENOUGH_RANDOM if the number
* of random bytes is too small. The last_error will be
* OUTPUT_BUFFER_TOO_SMALL if the output buffer is too small. */
std::size_t encrypt(
std::uint8_t const * plaintext, std::size_t plaintext_length,
std::uint8_t const * random, std::size_t random_length,
std::uint8_t * output, std::size_t max_output_length
);
/** An upper bound on the number of bytes of plain-text the decrypt method
* will write for a given input message length. */
std::size_t decrypt_max_plaintext_length(
std::size_t input_length
);
/** Decrypt a message. Returns the length of the decrypted plain-text or
* std::size_t(-1) on failure. On failure last_error will be set with an
* error code. The last_error will be OUTPUT_BUFFER_TOO_SMALL if the
* plain-text buffer is too small. The last_error will be
* BAD_MESSAGE_VERSION if the message was encrypted with an unsupported
* version of the protocol. The last_error will be BAD_MESSAGE_FORMAT if
* the message headers could not be decoded. The last_error will be
* BAD_MESSAGE_MAC if the message could not be verified */
std::size_t decrypt(
std::uint8_t const * input, std::size_t input_length,
std::uint8_t * plaintext, std::size_t max_plaintext_length
);
};
} // namespace axolotl
|
