pk.h 4.68 KB
Newer Older
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
/* 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();

/** 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();

/** 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. 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
 * "NOT_ENOUGH_RANDOM". */
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();

/** 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
);

/** The number of random bytes needed to generate a new key. */
size_t olm_pk_generate_key_random_length();

/** Generate a new key to use for decrypting messages. 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 there weren't enough random bytes then
 * olm_pk_decryption_last_error() will be "NOT_ENOUGH_RANDOM". */
size_t olm_pk_generate_key(
    OlmPkDecryption * decryption,
    void * pubkey, size_t pubkey_length,
    void * random, size_t random_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.  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 * decrytion,
    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
);

#ifdef __cplusplus
}
#endif

#endif /* OLM_PK_H_ */