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
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
/* Copyright 2018 New Vector 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.
*/
#ifndef OLM_PK_H_
#define OLM_PK_H_
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
typedef struct OlmPkEncryption OlmPkEncryption;
/* The size of an encryption object in bytes */
size_t olm_pk_encryption_size(void);
/** Initialise an encryption object using the supplied memory
* The supplied memory must be at least olm_pk_encryption_size() bytes */
OlmPkEncryption *olm_pk_encryption(
void * memory
);
/** A null terminated string describing the most recent error to happen to an
* encryption object */
const char * olm_pk_encryption_last_error(
OlmPkEncryption * encryption
);
/** Clears the memory used to back this encryption object */
size_t olm_clear_pk_encryption(
OlmPkEncryption *encryption
);
/** Set the recipient's public key for encrypting to */
size_t olm_pk_encryption_set_recipient_key(
OlmPkEncryption *encryption,
void const *public_key, size_t public_key_length
);
/** Get the length of the ciphertext that will correspond to a plaintext of the
* given length. */
size_t olm_pk_ciphertext_length(
OlmPkEncryption *encryption,
size_t plaintext_length
);
/** Get the length of the message authentication code. */
size_t olm_pk_mac_length(
OlmPkEncryption *encryption
);
/** Get the length of a public or ephemeral key */
size_t olm_pk_key_length(void);
/** The number of random bytes needed to encrypt a message. */
size_t olm_pk_encrypt_random_length(
OlmPkEncryption *encryption
);
/** Encrypt a plaintext for the recipient set using
* olm_pk_encryption_set_recipient_key. Writes to the ciphertext, mac, and
* ephemeral_key buffers, whose values should be sent to the recipient. mac is
* a Message Authentication Code to ensure that the data is received and
* decrypted properly. ephemeral_key is the public part of the ephemeral key
* used (together with the recipient's key) to generate a symmetric encryption
* key. Returns olm_error() on failure. If the ciphertext, mac, or
* ephemeral_key buffers were too small then olm_pk_encryption_last_error()
* will be "OUTPUT_BUFFER_TOO_SMALL". If there weren't enough random bytes then
* olm_pk_encryption_last_error() will be "OLM_INPUT_BUFFER_TOO_SMALL". */
size_t olm_pk_encrypt(
OlmPkEncryption *encryption,
void const * plaintext, size_t plaintext_length,
void * ciphertext, size_t ciphertext_length,
void * mac, size_t mac_length,
void * ephemeral_key, size_t ephemeral_key_size,
void * random, size_t random_length
);
typedef struct OlmPkDecryption OlmPkDecryption;
/* The size of a decryption object in bytes */
size_t olm_pk_decryption_size(void);
/** Initialise a decryption object using the supplied memory
* The supplied memory must be at least olm_pk_decryption_size() bytes */
OlmPkDecryption *olm_pk_decryption(
void * memory
);
/** A null terminated string describing the most recent error to happen to a
* decription object */
const char * olm_pk_decryption_last_error(
OlmPkDecryption * decryption
);
/** Clears the memory used to back this decryption object */
size_t olm_clear_pk_decryption(
OlmPkDecryption *decryption
);
/** Get the number of bytes required to store an olm private key
*/
size_t olm_pk_private_key_length();
/** Initialise the key from the private part of a key as returned by
* olm_pk_get_private_key(). The associated public key will be written to the
* pubkey buffer. Returns olm_error() on failure. If the pubkey buffer is too
* small then olm_pk_decryption_last_error() will be "OUTPUT_BUFFER_TOO_SMALL".
* If the private key was not long enough then olm_pk_decryption_last_error()
* will be "OLM_INPUT_BUFFER_TOO_SMALL".
*
* Note that the pubkey is a base64 encoded string, but the private key is
* an unencoded byte array
*/
size_t olm_pk_key_from_private(
OlmPkDecryption * decryption,
void * pubkey, size_t pubkey_length,
void * privkey, size_t privkey_length
);
/** Returns the number of bytes needed to store a decryption object. */
size_t olm_pickle_pk_decryption_length(
OlmPkDecryption * decryption
);
/** Stores decryption object as a base64 string. Encrypts the object using the
* supplied key. Returns the length of the pickled object on success.
* Returns olm_error() on failure. If the pickle output buffer
* is smaller than olm_pickle_account_length() then
* olm_pk_decryption_last_error() will be "OUTPUT_BUFFER_TOO_SMALL" */
size_t olm_pickle_pk_decryption(
OlmPkDecryption * decryption,
void const * key, size_t key_length,
void *pickled, size_t pickled_length
);
/** Loads a decryption object from a pickled base64 string. The associated
* public key will be written to the pubkey buffer. Decrypts the object using
* the supplied key. Returns olm_error() on failure. If the key doesn't
* match the one used to encrypt the account then olm_pk_decryption_last_error()
* will be "BAD_ACCOUNT_KEY". If the base64 couldn't be decoded then
* olm_pk_decryption_last_error() will be "INVALID_BASE64". The input pickled
* buffer is destroyed */
size_t olm_unpickle_pk_decryption(
OlmPkDecryption * decryption,
void const * key, size_t key_length,
void *pickled, size_t pickled_length,
void *pubkey, size_t pubkey_length
);
/** Get the length of the plaintext that will correspond to a ciphertext of the
* given length. */
size_t olm_pk_max_plaintext_length(
OlmPkDecryption * decryption,
size_t ciphertext_length
);
/** Decrypt a ciphertext. The input ciphertext buffer is destroyed. See the
* olm_pk_encrypt function for descriptions of the ephemeral_key and mac
* arguments. Returns the length of the plaintext on success. Returns
* olm_error() on failure. If the plaintext buffer is too small then
* olm_pk_encryption_last_error() will be "OUTPUT_BUFFER_TOO_SMALL". */
size_t olm_pk_decrypt(
OlmPkDecryption * decryption,
void const * ephemeral_key, size_t ephemeral_key_length,
void const * mac, size_t mac_length,
void * ciphertext, size_t ciphertext_length,
void * plaintext, size_t max_plaintext_length
);
/**
* Get the private key for an OlmDecryption object as an unencoded byte array
* private_key must be a pointer to a buffer of at least
* olm_pk_private_key_length() bytes and this length must be passed in
* private_key_length. If the given buffer is too small, returns olm_error()
* and olm_pk_encryption_last_error() will be "OUTPUT_BUFFER_TOO_SMALL".
* Returns the number of bytes written.
*/
size_t olm_pk_get_private_key(
OlmPkDecryption * decryption,
void *private_key, size_t private_key_length
);
#ifdef __cplusplus
}
#endif
#endif /* OLM_PK_H_ */
|
