1/*
2 * libwebsockets - small server side websockets and web server implementation
3 *
4 * Copyright (C) 2010 - 2020 Andy Green <andy@warmcat.com>
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to
8 * deal in the Software without restriction, including without limitation the
9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10 * sell copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22 * IN THE SOFTWARE.
23 */
24
25/*! \defgroup generic AES
26 * ## Generic AES related functions
27 *
28 * Lws provides generic AES functions that abstract the ones
29 * provided by whatever tls library you are linking against.
30 *
31 * It lets you use the same code if you build against mbedtls or OpenSSL
32 * for example.
33 */
34///@{
35
36#if defined(LWS_WITH_MBEDTLS)
37#include <mbedtls/aes.h>
38#include <mbedtls/gcm.h>
39#endif
40
41enum enum_aes_modes {
42 LWS_GAESM_CBC,
43 LWS_GAESM_CFB128,
44 LWS_GAESM_CFB8,
45 LWS_GAESM_CTR,
46 LWS_GAESM_ECB,
47 LWS_GAESM_OFB,
48 LWS_GAESM_XTS, /* care... requires double-length key */
49 LWS_GAESM_GCM,
50 LWS_GAESM_KW,
51};
52
53enum enum_aes_operation {
54 LWS_GAESO_ENC,
55 LWS_GAESO_DEC
56};
57
58enum enum_aes_padding {
59 LWS_GAESP_NO_PADDING,
60 LWS_GAESP_WITH_PADDING
61};
62
63/* include/libwebsockets/lws-jwk.h must be included before this */
64
65#define LWS_AES_BLOCKSIZE 128
66#define LWS_AES_CBC_BLOCKLEN 16
67
68struct lws_genaes_ctx {
69#if defined(LWS_WITH_MBEDTLS)
70 union {
71 mbedtls_aes_context ctx;
72#if defined(MBEDTLS_CIPHER_MODE_XTS)
73 mbedtls_aes_xts_context ctx_xts;
74#endif
75 mbedtls_gcm_context ctx_gcm;
76 } u;
77#else
78 EVP_CIPHER_CTX *ctx;
79 const EVP_CIPHER *cipher;
80 ENGINE *engine;
81 char init;
82#endif
83 unsigned char tag[16];
84 struct lws_gencrypto_keyelem *k;
85 enum enum_aes_operation op;
86 enum enum_aes_modes mode;
87 enum enum_aes_padding padding;
88 int taglen;
89 char underway;
90};
91
92/** lws_genaes_create() - Create genaes AES context
93 *
94 * \param ctx: your struct lws_genaes_ctx
95 * \param op: LWS_GAESO_ENC or LWS_GAESO_DEC
96 * \param mode: one of LWS_GAESM_
97 * \param el: struct prepared with key element data
98 * \param padding: 0 = no padding, 1 = padding
99 * \param engine: if openssl engine used, pass the pointer here
100 *
101 * Creates an AES context with a key associated with it, formed from
102 * the key elements in \p el.
103 *
104 * Returns 0 for OK or nonzero for error.
105 *
106 * This and related APIs operate identically with OpenSSL or mbedTLS backends.
107 */
108LWS_VISIBLE LWS_EXTERN int
109lws_genaes_create(struct lws_genaes_ctx *ctx, enum enum_aes_operation op,
110 enum enum_aes_modes mode, struct lws_gencrypto_keyelem *el,
111 enum enum_aes_padding padding, void *engine);
112
113/** lws_genaes_destroy() - Destroy genaes AES context
114 *
115 * \param ctx: your struct lws_genaes_ctx
116 * \param tag: NULL, or, GCM-only: buffer to receive tag
117 * \param tlen: 0, or, GCM-only: length of tag buffer
118 *
119 * Destroys any allocations related to \p ctx.
120 *
121 * For GCM only, up to tlen bytes of tag buffer will be set on exit.
122 *
123 * This and related APIs operate identically with OpenSSL or mbedTLS backends.
124 */
125LWS_VISIBLE LWS_EXTERN int
126lws_genaes_destroy(struct lws_genaes_ctx *ctx, unsigned char *tag, size_t tlen);
127
128/** lws_genaes_crypt() - Encrypt or decrypt
129 *
130 * \param ctx: your struct lws_genaes_ctx
131 * \param in: input plaintext or ciphertext
132 * \param len: length of input (which is always length of output)
133 * \param out: output plaintext or ciphertext
134 * \param iv_or_nonce_ctr_or_data_unit_16: NULL, iv, nonce_ctr16, or data_unit16
135 * \param stream_block_16: pointer to 16-byte stream block for CTR mode only
136 * \param nc_or_iv_off: NULL or pointer to nc, or iv_off
137 * \param taglen: length of tag
138 *
139 * Encrypts or decrypts using the AES mode set when the ctx was created.
140 * The last three arguments have different meanings depending on the mode:
141 *
142 * KW CBC CFB128 CFB8 CTR ECB OFB XTS
143 * iv_or_nonce_ct.._unit_16 : iv iv iv iv nonce NULL iv dataunt
144 * stream_block_16 : NULL NULL NULL NULL stream NULL NULL NULL
145 * nc_or_iv_off : NULL NULL iv_off NULL nc_off NULL iv_off NULL
146 *
147 * For GCM:
148 *
149 * iv_or_nonce_ctr_or_data_unit_16 : iv
150 * stream_block_16 : pointer to tag
151 * nc_or_iv_off : set pointed-to size_t to iv length
152 * in : first call: additional data, subsequently
153 * : input data
154 * len : first call: add data length, subsequently
155 * : input / output length
156 *
157 * The length of the optional arg is always 16 if used, regardless of the mode.
158 *
159 * Returns 0 for OK or nonzero for error.
160 *
161 * This and related APIs operate identically with OpenSSL or mbedTLS backends.
162 */
163LWS_VISIBLE LWS_EXTERN int
164lws_genaes_crypt(struct lws_genaes_ctx *ctx, const uint8_t *in, size_t len,
165 uint8_t *out,
166 uint8_t *iv_or_nonce_ctr_or_data_unit_16,
167 uint8_t *stream_block_16,
168 size_t *nc_or_iv_off, int taglen);
169
170///@}
171