aboutsummaryrefslogtreecommitdiff
path: root/include/olm/cipher.h
blob: 3296c3704c966472bf104a3ac80b407c13c0d820 (plain)
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
/* 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.
 */

#ifndef OLM_CIPHER_H_
#define OLM_CIPHER_H_

#include <stdint.h>
#include <stdlib.h>

#ifdef __cplusplus
extern "C" {
#endif

struct _olm_cipher;

struct _olm_cipher_ops {
    /**
     * Returns the length of the message authentication code that will be
     * appended to the output.
     */
    size_t (*mac_length)(const struct _olm_cipher *cipher);

    /**
     * Returns the length of cipher-text for a given length of plain-text.
     */
    size_t (*encrypt_ciphertext_length)(
        const struct _olm_cipher *cipher,
        size_t plaintext_length
    );

    /*
     * Encrypts the plain-text into the output buffer and authenticates the
     * contents of the output buffer covering both cipher-text and any other
     * associated data in the output buffer.
     *
     *  |---------------------------------------output_length-->|
     *  output  |--ciphertext_length-->|       |---mac_length-->|
     *          ciphertext
     *
     * The plain-text pointers and cipher-text pointers may be the same.
     *
     * Returns size_t(-1) if the length of the cipher-text or the output
     * buffer is too small. Otherwise returns the length of the output buffer.
     */
    size_t (*encrypt)(
        const struct _olm_cipher *cipher,
        uint8_t const * key, size_t key_length,
        uint8_t const * plaintext, size_t plaintext_length,
        uint8_t * ciphertext, size_t ciphertext_length,
        uint8_t * output, size_t output_length
    );

    /**
     * Returns the maximum length of plain-text that a given length of
     * cipher-text can contain.
     */
    size_t (*decrypt_max_plaintext_length)(
        const struct _olm_cipher *cipher,
        size_t ciphertext_length
    );

    /**
     * Authenticates the input and decrypts the cipher-text into the plain-text
     * buffer.
     *
     *  |----------------------------------------input_length-->|
     *  input   |--ciphertext_length-->|       |---mac_length-->|
     *          ciphertext
     *
     * The plain-text pointers and cipher-text pointers may be the same.
     *
     *  Returns size_t(-1) if the length of the plain-text buffer is too
     *  small or if the authentication check fails. Otherwise returns the length
     *  of the plain text.
     */
    size_t (*decrypt)(
        const struct _olm_cipher *cipher,
        uint8_t const * key, size_t key_length,
        uint8_t const * input, size_t input_length,
        uint8_t const * ciphertext, size_t ciphertext_length,
        uint8_t * plaintext, size_t max_plaintext_length
    );

    /** destroy any private data associated with this cipher */
    void (*destruct)(struct _olm_cipher *cipher);
};

struct _olm_cipher {
    const struct _olm_cipher_ops *ops;
    /* cipher-specific fields follow */
};

struct _olm_cipher_aes_sha_256 {
    struct _olm_cipher base_cipher;

    uint8_t const * kdf_info;
    size_t kdf_info_length;
};


/**
 * initialises a cipher type which uses AES256 for encryption and SHA256 for
 * authentication.
 *
 * cipher: structure to be initialised
 *
 * kdf_info: context string for the HKDF used for deriving the AES256 key, HMAC
 * key, and AES IV, from the key material passed to encrypt/decrypt. Note that
 * this is NOT copied so must have a lifetime at least as long as the cipher
 * instance.
 *
 * kdf_info_length: length of context string kdf_info
 */
struct _olm_cipher *_olm_cipher_aes_sha_256_init(
    struct _olm_cipher_aes_sha_256 *cipher,
    uint8_t const * kdf_info,
    size_t kdf_info_length);


#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* OLM_CIPHER_H_ */