Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 1 | /* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com) |
| 2 | * All rights reserved. |
| 3 | * |
| 4 | * This package is an SSL implementation written |
| 5 | * by Eric Young (eay@cryptsoft.com). |
| 6 | * The implementation was written so as to conform with Netscapes SSL. |
| 7 | * |
| 8 | * This library is free for commercial and non-commercial use as long as |
| 9 | * the following conditions are aheared to. The following conditions |
| 10 | * apply to all code found in this distribution, be it the RC4, RSA, |
| 11 | * lhash, DES, etc., code; not just the SSL code. The SSL documentation |
| 12 | * included with this distribution is covered by the same copyright terms |
| 13 | * except that the holder is Tim Hudson (tjh@cryptsoft.com). |
| 14 | * |
| 15 | * Copyright remains Eric Young's, and as such any Copyright notices in |
| 16 | * the code are not to be removed. |
| 17 | * If this package is used in a product, Eric Young should be given attribution |
| 18 | * as the author of the parts of the library used. |
| 19 | * This can be in the form of a textual message at program startup or |
| 20 | * in documentation (online or textual) provided with the package. |
| 21 | * |
| 22 | * Redistribution and use in source and binary forms, with or without |
| 23 | * modification, are permitted provided that the following conditions |
| 24 | * are met: |
| 25 | * 1. Redistributions of source code must retain the copyright |
| 26 | * notice, this list of conditions and the following disclaimer. |
| 27 | * 2. Redistributions in binary form must reproduce the above copyright |
| 28 | * notice, this list of conditions and the following disclaimer in the |
| 29 | * documentation and/or other materials provided with the distribution. |
| 30 | * 3. All advertising materials mentioning features or use of this software |
| 31 | * must display the following acknowledgement: |
| 32 | * "This product includes cryptographic software written by |
| 33 | * Eric Young (eay@cryptsoft.com)" |
| 34 | * The word 'cryptographic' can be left out if the rouines from the library |
| 35 | * being used are not cryptographic related :-). |
| 36 | * 4. If you include any Windows specific code (or a derivative thereof) from |
| 37 | * the apps directory (application code) you must include an acknowledgement: |
| 38 | * "This product includes software written by Tim Hudson (tjh@cryptsoft.com)" |
| 39 | * |
| 40 | * THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND |
| 41 | * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| 42 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| 43 | * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE |
| 44 | * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| 45 | * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| 46 | * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| 47 | * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| 48 | * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| 49 | * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| 50 | * SUCH DAMAGE. |
| 51 | * |
| 52 | * The licence and distribution terms for any publically available version or |
| 53 | * derivative of this code cannot be changed. i.e. this code cannot simply be |
| 54 | * copied and put under another distribution licence |
| 55 | * [including the GNU Public Licence.] */ |
| 56 | |
| 57 | #ifndef OPENSSL_HEADER_CIPHER_H |
| 58 | #define OPENSSL_HEADER_CIPHER_H |
| 59 | |
| 60 | #include <openssl/base.h> |
| 61 | |
| 62 | #if defined(__cplusplus) |
| 63 | extern "C" { |
| 64 | #endif |
| 65 | |
| 66 | |
| 67 | /* Ciphers. */ |
| 68 | |
| 69 | |
| 70 | /* Cipher primitives. |
| 71 | * |
| 72 | * The following functions return |EVP_CIPHER| objects that implement the named |
| 73 | * cipher algorithm. */ |
| 74 | |
| 75 | OPENSSL_EXPORT const EVP_CIPHER *EVP_rc4(void); |
| 76 | |
| 77 | OPENSSL_EXPORT const EVP_CIPHER *EVP_des_cbc(void); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 78 | OPENSSL_EXPORT const EVP_CIPHER *EVP_des_ecb(void); |
| 79 | OPENSSL_EXPORT const EVP_CIPHER *EVP_des_ede(void); |
Robert Sloan | 572a4e2 | 2017-04-17 10:52:19 -0700 | [diff] [blame] | 80 | OPENSSL_EXPORT const EVP_CIPHER *EVP_des_ede3(void); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 81 | OPENSSL_EXPORT const EVP_CIPHER *EVP_des_ede_cbc(void); |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 82 | OPENSSL_EXPORT const EVP_CIPHER *EVP_des_ede3_cbc(void); |
| 83 | |
| 84 | OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_128_ecb(void); |
| 85 | OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_128_cbc(void); |
| 86 | OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_128_ctr(void); |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 87 | OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_128_ofb(void); |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 88 | |
| 89 | OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_256_ecb(void); |
| 90 | OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_256_cbc(void); |
| 91 | OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_256_ctr(void); |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 92 | OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_256_ofb(void); |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 93 | OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_256_xts(void); |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 94 | |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 95 | /* EVP_enc_null returns a 'cipher' that passes plaintext through as |
| 96 | * ciphertext. */ |
| 97 | OPENSSL_EXPORT const EVP_CIPHER *EVP_enc_null(void); |
| 98 | |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 99 | /* EVP_rc2_cbc returns a cipher that implements 128-bit RC2 in CBC mode. */ |
| 100 | OPENSSL_EXPORT const EVP_CIPHER *EVP_rc2_cbc(void); |
| 101 | |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 102 | /* EVP_rc2_40_cbc returns a cipher that implements 40-bit RC2 in CBC mode. This |
| 103 | * is obviously very, very weak and is included only in order to read PKCS#12 |
| 104 | * files, which often encrypt the certificate chain using this cipher. It is |
| 105 | * deliberately not exported. */ |
| 106 | const EVP_CIPHER *EVP_rc2_40_cbc(void); |
| 107 | |
| 108 | /* EVP_get_cipherbynid returns the cipher corresponding to the given NID, or |
| 109 | * NULL if no such cipher is known. */ |
| 110 | OPENSSL_EXPORT const EVP_CIPHER *EVP_get_cipherbynid(int nid); |
| 111 | |
| 112 | |
| 113 | /* Cipher context allocation. |
| 114 | * |
| 115 | * An |EVP_CIPHER_CTX| represents the state of an encryption or decryption in |
| 116 | * progress. */ |
| 117 | |
| 118 | /* EVP_CIPHER_CTX_init initialises an, already allocated, |EVP_CIPHER_CTX|. */ |
| 119 | OPENSSL_EXPORT void EVP_CIPHER_CTX_init(EVP_CIPHER_CTX *ctx); |
| 120 | |
| 121 | /* EVP_CIPHER_CTX_new allocates a fresh |EVP_CIPHER_CTX|, calls |
| 122 | * |EVP_CIPHER_CTX_init| and returns it, or NULL on allocation failure. */ |
| 123 | OPENSSL_EXPORT EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void); |
| 124 | |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 125 | /* EVP_CIPHER_CTX_cleanup frees any memory referenced by |ctx|. It returns |
| 126 | * one. */ |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 127 | OPENSSL_EXPORT int EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *ctx); |
| 128 | |
| 129 | /* EVP_CIPHER_CTX_free calls |EVP_CIPHER_CTX_cleanup| on |ctx| and then frees |
| 130 | * |ctx| itself. */ |
| 131 | OPENSSL_EXPORT void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx); |
| 132 | |
| 133 | /* EVP_CIPHER_CTX_copy sets |out| to be a duplicate of the current state of |
| 134 | * |in|. The |out| argument must have been previously initialised. */ |
| 135 | OPENSSL_EXPORT int EVP_CIPHER_CTX_copy(EVP_CIPHER_CTX *out, |
| 136 | const EVP_CIPHER_CTX *in); |
| 137 | |
| 138 | |
| 139 | /* Cipher context configuration. */ |
| 140 | |
| 141 | /* EVP_CipherInit_ex configures |ctx| for a fresh encryption (or decryption, if |
| 142 | * |enc| is zero) operation using |cipher|. If |ctx| has been previously |
| 143 | * configured with a cipher then |cipher|, |key| and |iv| may be |NULL| and |
| 144 | * |enc| may be -1 to reuse the previous values. The operation will use |key| |
| 145 | * as the key and |iv| as the IV (if any). These should have the correct |
| 146 | * lengths given by |EVP_CIPHER_key_length| and |EVP_CIPHER_iv_length|. It |
| 147 | * returns one on success and zero on error. */ |
| 148 | OPENSSL_EXPORT int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, |
| 149 | const EVP_CIPHER *cipher, ENGINE *engine, |
| 150 | const uint8_t *key, const uint8_t *iv, |
| 151 | int enc); |
| 152 | |
| 153 | /* EVP_EncryptInit_ex calls |EVP_CipherInit_ex| with |enc| equal to one. */ |
| 154 | OPENSSL_EXPORT int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, |
| 155 | const EVP_CIPHER *cipher, ENGINE *impl, |
| 156 | const uint8_t *key, const uint8_t *iv); |
| 157 | |
| 158 | /* EVP_DecryptInit_ex calls |EVP_CipherInit_ex| with |enc| equal to zero. */ |
| 159 | OPENSSL_EXPORT int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, |
| 160 | const EVP_CIPHER *cipher, ENGINE *impl, |
| 161 | const uint8_t *key, const uint8_t *iv); |
| 162 | |
| 163 | |
| 164 | /* Cipher operations. */ |
| 165 | |
| 166 | /* EVP_EncryptUpdate encrypts |in_len| bytes from |in| to |out|. The number |
| 167 | * of output bytes may be up to |in_len| plus the block length minus one and |
| 168 | * |out| must have sufficient space. The number of bytes actually output is |
| 169 | * written to |*out_len|. It returns one on success and zero otherwise. */ |
| 170 | OPENSSL_EXPORT int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, uint8_t *out, |
| 171 | int *out_len, const uint8_t *in, |
| 172 | int in_len); |
| 173 | |
| 174 | /* EVP_EncryptFinal_ex writes at most a block of ciphertext to |out| and sets |
| 175 | * |*out_len| to the number of bytes written. If padding is enabled (the |
| 176 | * default) then standard padding is applied to create the final block. If |
| 177 | * padding is disabled (with |EVP_CIPHER_CTX_set_padding|) then any partial |
| 178 | * block remaining will cause an error. The function returns one on success and |
| 179 | * zero otherwise. */ |
| 180 | OPENSSL_EXPORT int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, uint8_t *out, |
| 181 | int *out_len); |
| 182 | |
| 183 | /* EVP_DecryptUpdate decrypts |in_len| bytes from |in| to |out|. The number of |
| 184 | * output bytes may be up to |in_len| plus the block length minus one and |out| |
| 185 | * must have sufficient space. The number of bytes actually output is written |
| 186 | * to |*out_len|. It returns one on success and zero otherwise. */ |
| 187 | OPENSSL_EXPORT int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, uint8_t *out, |
| 188 | int *out_len, const uint8_t *in, |
| 189 | int in_len); |
| 190 | |
| 191 | /* EVP_DecryptFinal_ex writes at most a block of ciphertext to |out| and sets |
| 192 | * |*out_len| to the number of bytes written. If padding is enabled (the |
| 193 | * default) then padding is removed from the final block. |
| 194 | * |
Steven Valdez | b0b45c6 | 2017-01-17 16:23:54 -0500 | [diff] [blame] | 195 | * WARNING: it is unsafe to call this function with unauthenticated |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 196 | * ciphertext if padding is enabled. */ |
| 197 | OPENSSL_EXPORT int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, |
| 198 | int *out_len); |
| 199 | |
| 200 | /* EVP_Cipher performs a one-shot encryption/decryption operation. No partial |
| 201 | * blocks are maintained between calls. However, any internal cipher state is |
| 202 | * still updated. For CBC-mode ciphers, the IV is updated to the final |
| 203 | * ciphertext block. For stream ciphers, the stream is advanced past the bytes |
| 204 | * used. It returns one on success and zero otherwise, unless |EVP_CIPHER_flags| |
| 205 | * has |EVP_CIPH_FLAG_CUSTOM_CIPHER| set. Then it returns the number of bytes |
| 206 | * written or -1 on error. |
| 207 | * |
| 208 | * WARNING: this differs from the usual return value convention when using |
| 209 | * |EVP_CIPH_FLAG_CUSTOM_CIPHER|. |
| 210 | * |
| 211 | * TODO(davidben): The normal ciphers currently never fail, even if, e.g., |
| 212 | * |in_len| is not a multiple of the block size for CBC-mode decryption. The |
| 213 | * input just gets rounded up while the output gets truncated. This should |
| 214 | * either be officially documented or fail. */ |
| 215 | OPENSSL_EXPORT int EVP_Cipher(EVP_CIPHER_CTX *ctx, uint8_t *out, |
| 216 | const uint8_t *in, size_t in_len); |
| 217 | |
| 218 | /* EVP_CipherUpdate calls either |EVP_EncryptUpdate| or |EVP_DecryptUpdate| |
| 219 | * depending on how |ctx| has been setup. */ |
| 220 | OPENSSL_EXPORT int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, uint8_t *out, |
| 221 | int *out_len, const uint8_t *in, |
| 222 | int in_len); |
| 223 | |
| 224 | /* EVP_CipherFinal_ex calls either |EVP_EncryptFinal_ex| or |
| 225 | * |EVP_DecryptFinal_ex| depending on how |ctx| has been setup. */ |
| 226 | OPENSSL_EXPORT int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, uint8_t *out, |
| 227 | int *out_len); |
| 228 | |
| 229 | |
| 230 | /* Cipher context accessors. */ |
| 231 | |
| 232 | /* EVP_CIPHER_CTX_cipher returns the |EVP_CIPHER| underlying |ctx|, or NULL if |
| 233 | * none has been set. */ |
| 234 | OPENSSL_EXPORT const EVP_CIPHER *EVP_CIPHER_CTX_cipher( |
| 235 | const EVP_CIPHER_CTX *ctx); |
| 236 | |
| 237 | /* EVP_CIPHER_CTX_nid returns a NID identifying the |EVP_CIPHER| underlying |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 238 | * |ctx| (e.g. |NID_aes_128_gcm|). It will crash if no cipher has been |
| 239 | * configured. */ |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 240 | OPENSSL_EXPORT int EVP_CIPHER_CTX_nid(const EVP_CIPHER_CTX *ctx); |
| 241 | |
| 242 | /* EVP_CIPHER_CTX_block_size returns the block size, in bytes, of the cipher |
| 243 | * underlying |ctx|, or one if the cipher is a stream cipher. It will crash if |
| 244 | * no cipher has been configured. */ |
| 245 | OPENSSL_EXPORT unsigned EVP_CIPHER_CTX_block_size(const EVP_CIPHER_CTX *ctx); |
| 246 | |
| 247 | /* EVP_CIPHER_CTX_key_length returns the key size, in bytes, of the cipher |
| 248 | * underlying |ctx| or zero if no cipher has been configured. */ |
| 249 | OPENSSL_EXPORT unsigned EVP_CIPHER_CTX_key_length(const EVP_CIPHER_CTX *ctx); |
| 250 | |
| 251 | /* EVP_CIPHER_CTX_iv_length returns the IV size, in bytes, of the cipher |
| 252 | * underlying |ctx|. It will crash if no cipher has been configured. */ |
| 253 | OPENSSL_EXPORT unsigned EVP_CIPHER_CTX_iv_length(const EVP_CIPHER_CTX *ctx); |
| 254 | |
| 255 | /* EVP_CIPHER_CTX_get_app_data returns the opaque, application data pointer for |
| 256 | * |ctx|, or NULL if none has been set. */ |
| 257 | OPENSSL_EXPORT void *EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx); |
| 258 | |
| 259 | /* EVP_CIPHER_CTX_set_app_data sets the opaque, application data pointer for |
| 260 | * |ctx| to |data|. */ |
| 261 | OPENSSL_EXPORT void EVP_CIPHER_CTX_set_app_data(EVP_CIPHER_CTX *ctx, |
| 262 | void *data); |
| 263 | |
| 264 | /* EVP_CIPHER_CTX_flags returns a value which is the OR of zero or more |
| 265 | * |EVP_CIPH_*| flags. It will crash if no cipher has been configured. */ |
| 266 | OPENSSL_EXPORT uint32_t EVP_CIPHER_CTX_flags(const EVP_CIPHER_CTX *ctx); |
| 267 | |
| 268 | /* EVP_CIPHER_CTX_mode returns one of the |EVP_CIPH_*| cipher mode values |
| 269 | * enumerated below. It will crash if no cipher has been configured. */ |
| 270 | OPENSSL_EXPORT uint32_t EVP_CIPHER_CTX_mode(const EVP_CIPHER_CTX *ctx); |
| 271 | |
| 272 | /* EVP_CIPHER_CTX_ctrl is an |ioctl| like function. The |command| argument |
| 273 | * should be one of the |EVP_CTRL_*| values. The |arg| and |ptr| arguments are |
| 274 | * specific to the command in question. */ |
| 275 | OPENSSL_EXPORT int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int command, |
| 276 | int arg, void *ptr); |
| 277 | |
| 278 | /* EVP_CIPHER_CTX_set_padding sets whether padding is enabled for |ctx| and |
| 279 | * returns one. Pass a non-zero |pad| to enable padding (the default) or zero |
| 280 | * to disable. */ |
| 281 | OPENSSL_EXPORT int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *ctx, int pad); |
| 282 | |
| 283 | /* EVP_CIPHER_CTX_set_key_length sets the key length for |ctx|. This is only |
| 284 | * valid for ciphers that can take a variable length key. It returns one on |
| 285 | * success and zero on error. */ |
Steven Valdez | b0b45c6 | 2017-01-17 16:23:54 -0500 | [diff] [blame] | 286 | OPENSSL_EXPORT int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *ctx, |
| 287 | unsigned key_len); |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 288 | |
| 289 | |
| 290 | /* Cipher accessors. */ |
| 291 | |
Steven Valdez | b0b45c6 | 2017-01-17 16:23:54 -0500 | [diff] [blame] | 292 | /* EVP_CIPHER_nid returns a NID identifying |cipher|. (For example, |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 293 | * |NID_aes_128_gcm|.) */ |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 294 | OPENSSL_EXPORT int EVP_CIPHER_nid(const EVP_CIPHER *cipher); |
| 295 | |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 296 | /* EVP_CIPHER_block_size returns the block size, in bytes, for |cipher|, or one |
| 297 | * if |cipher| is a stream cipher. */ |
| 298 | OPENSSL_EXPORT unsigned EVP_CIPHER_block_size(const EVP_CIPHER *cipher); |
| 299 | |
| 300 | /* EVP_CIPHER_key_length returns the key size, in bytes, for |cipher|. If |
| 301 | * |cipher| can take a variable key length then this function returns the |
| 302 | * default key length and |EVP_CIPHER_flags| will return a value with |
| 303 | * |EVP_CIPH_VARIABLE_LENGTH| set. */ |
| 304 | OPENSSL_EXPORT unsigned EVP_CIPHER_key_length(const EVP_CIPHER *cipher); |
| 305 | |
| 306 | /* EVP_CIPHER_iv_length returns the IV size, in bytes, of |cipher|, or zero if |
| 307 | * |cipher| doesn't take an IV. */ |
| 308 | OPENSSL_EXPORT unsigned EVP_CIPHER_iv_length(const EVP_CIPHER *cipher); |
| 309 | |
| 310 | /* EVP_CIPHER_flags returns a value which is the OR of zero or more |
| 311 | * |EVP_CIPH_*| flags. */ |
| 312 | OPENSSL_EXPORT uint32_t EVP_CIPHER_flags(const EVP_CIPHER *cipher); |
| 313 | |
| 314 | /* EVP_CIPHER_mode returns one of the cipher mode values enumerated below. */ |
| 315 | OPENSSL_EXPORT uint32_t EVP_CIPHER_mode(const EVP_CIPHER *cipher); |
| 316 | |
| 317 | |
| 318 | /* Key derivation. */ |
| 319 | |
| 320 | /* EVP_BytesToKey generates a key and IV for the cipher |type| by iterating |
| 321 | * |md| |count| times using |data| and |salt|. On entry, the |key| and |iv| |
| 322 | * buffers must have enough space to hold a key and IV for |type|. It returns |
| 323 | * the length of the key on success or zero on error. */ |
| 324 | OPENSSL_EXPORT int EVP_BytesToKey(const EVP_CIPHER *type, const EVP_MD *md, |
| 325 | const uint8_t *salt, const uint8_t *data, |
| 326 | size_t data_len, unsigned count, uint8_t *key, |
| 327 | uint8_t *iv); |
| 328 | |
| 329 | |
| 330 | /* Cipher modes (for |EVP_CIPHER_mode|). */ |
| 331 | |
| 332 | #define EVP_CIPH_STREAM_CIPHER 0x0 |
| 333 | #define EVP_CIPH_ECB_MODE 0x1 |
| 334 | #define EVP_CIPH_CBC_MODE 0x2 |
| 335 | #define EVP_CIPH_CFB_MODE 0x3 |
| 336 | #define EVP_CIPH_OFB_MODE 0x4 |
| 337 | #define EVP_CIPH_CTR_MODE 0x5 |
| 338 | #define EVP_CIPH_GCM_MODE 0x6 |
Kenny Root | b849459 | 2015-09-25 02:29:14 +0000 | [diff] [blame] | 339 | #define EVP_CIPH_XTS_MODE 0x7 |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 340 | |
| 341 | |
| 342 | /* Cipher flags (for |EVP_CIPHER_flags|). */ |
| 343 | |
| 344 | /* EVP_CIPH_VARIABLE_LENGTH indicates that the cipher takes a variable length |
| 345 | * key. */ |
| 346 | #define EVP_CIPH_VARIABLE_LENGTH 0x40 |
| 347 | |
| 348 | /* EVP_CIPH_ALWAYS_CALL_INIT indicates that the |init| function for the cipher |
| 349 | * should always be called when initialising a new operation, even if the key |
| 350 | * is NULL to indicate that the same key is being used. */ |
| 351 | #define EVP_CIPH_ALWAYS_CALL_INIT 0x80 |
| 352 | |
| 353 | /* EVP_CIPH_CUSTOM_IV indicates that the cipher manages the IV itself rather |
| 354 | * than keeping it in the |iv| member of |EVP_CIPHER_CTX|. */ |
| 355 | #define EVP_CIPH_CUSTOM_IV 0x100 |
| 356 | |
| 357 | /* EVP_CIPH_CTRL_INIT indicates that EVP_CTRL_INIT should be used when |
| 358 | * initialising an |EVP_CIPHER_CTX|. */ |
| 359 | #define EVP_CIPH_CTRL_INIT 0x200 |
| 360 | |
| 361 | /* EVP_CIPH_FLAG_CUSTOM_CIPHER indicates that the cipher manages blocking |
| 362 | * itself. This causes EVP_(En|De)crypt_ex to be simple wrapper functions. */ |
| 363 | #define EVP_CIPH_FLAG_CUSTOM_CIPHER 0x400 |
| 364 | |
| 365 | /* EVP_CIPH_FLAG_AEAD_CIPHER specifies that the cipher is an AEAD. This is an |
| 366 | * older version of the proper AEAD interface. See aead.h for the current |
| 367 | * one. */ |
| 368 | #define EVP_CIPH_FLAG_AEAD_CIPHER 0x800 |
| 369 | |
| 370 | /* EVP_CIPH_CUSTOM_COPY indicates that the |ctrl| callback should be called |
| 371 | * with |EVP_CTRL_COPY| at the end of normal |EVP_CIPHER_CTX_copy| |
| 372 | * processing. */ |
| 373 | #define EVP_CIPH_CUSTOM_COPY 0x1000 |
| 374 | |
| 375 | |
| 376 | /* Deprecated functions */ |
| 377 | |
| 378 | /* EVP_CipherInit acts like EVP_CipherInit_ex except that |EVP_CIPHER_CTX_init| |
| 379 | * is called on |cipher| first, if |cipher| is not NULL. */ |
| 380 | OPENSSL_EXPORT int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *cipher, |
| 381 | const uint8_t *key, const uint8_t *iv, |
| 382 | int enc); |
| 383 | |
| 384 | /* EVP_EncryptInit calls |EVP_CipherInit| with |enc| equal to one. */ |
| 385 | OPENSSL_EXPORT int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, |
| 386 | const EVP_CIPHER *cipher, const uint8_t *key, |
| 387 | const uint8_t *iv); |
| 388 | |
| 389 | /* EVP_DecryptInit calls |EVP_CipherInit| with |enc| equal to zero. */ |
| 390 | OPENSSL_EXPORT int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, |
| 391 | const EVP_CIPHER *cipher, const uint8_t *key, |
| 392 | const uint8_t *iv); |
| 393 | |
| 394 | /* EVP_add_cipher_alias does nothing and returns one. */ |
| 395 | OPENSSL_EXPORT int EVP_add_cipher_alias(const char *a, const char *b); |
| 396 | |
| 397 | /* EVP_get_cipherbyname returns an |EVP_CIPHER| given a human readable name in |
| 398 | * |name|, or NULL if the name is unknown. */ |
| 399 | OPENSSL_EXPORT const EVP_CIPHER *EVP_get_cipherbyname(const char *name); |
| 400 | |
Adam Langley | fad6327 | 2015-11-12 12:15:39 -0800 | [diff] [blame] | 401 | /* These AEADs are deprecated AES-GCM implementations that set |
| 402 | * |EVP_CIPH_FLAG_CUSTOM_CIPHER|. Use |EVP_aead_aes_128_gcm| and |
| 403 | * |EVP_aead_aes_256_gcm| instead. */ |
| 404 | OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_128_gcm(void); |
| 405 | OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_256_gcm(void); |
| 406 | |
| 407 | /* These are deprecated, 192-bit version of AES. */ |
| 408 | OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_ecb(void); |
| 409 | OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_cbc(void); |
| 410 | OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_ctr(void); |
| 411 | OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_gcm(void); |
| 412 | |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 413 | |
| 414 | /* Private functions. */ |
| 415 | |
| 416 | /* EVP_CIPH_NO_PADDING disables padding in block ciphers. */ |
| 417 | #define EVP_CIPH_NO_PADDING 0x800 |
| 418 | |
| 419 | /* EVP_CIPHER_CTX_ctrl commands. */ |
| 420 | #define EVP_CTRL_INIT 0x0 |
| 421 | #define EVP_CTRL_SET_KEY_LENGTH 0x1 |
| 422 | #define EVP_CTRL_GET_RC2_KEY_BITS 0x2 |
| 423 | #define EVP_CTRL_SET_RC2_KEY_BITS 0x3 |
| 424 | #define EVP_CTRL_GET_RC5_ROUNDS 0x4 |
| 425 | #define EVP_CTRL_SET_RC5_ROUNDS 0x5 |
| 426 | #define EVP_CTRL_RAND_KEY 0x6 |
| 427 | #define EVP_CTRL_PBE_PRF_NID 0x7 |
| 428 | #define EVP_CTRL_COPY 0x8 |
| 429 | #define EVP_CTRL_GCM_SET_IVLEN 0x9 |
| 430 | #define EVP_CTRL_GCM_GET_TAG 0x10 |
| 431 | #define EVP_CTRL_GCM_SET_TAG 0x11 |
| 432 | #define EVP_CTRL_GCM_SET_IV_FIXED 0x12 |
| 433 | #define EVP_CTRL_GCM_IV_GEN 0x13 |
| 434 | #define EVP_CTRL_AEAD_SET_MAC_KEY 0x17 |
| 435 | /* Set the GCM invocation field, decrypt only */ |
| 436 | #define EVP_CTRL_GCM_SET_IV_INV 0x18 |
| 437 | |
| 438 | /* GCM TLS constants */ |
| 439 | /* Length of fixed part of IV derived from PRF */ |
| 440 | #define EVP_GCM_TLS_FIXED_IV_LEN 4 |
| 441 | /* Length of explicit part of IV part of TLS records */ |
| 442 | #define EVP_GCM_TLS_EXPLICIT_IV_LEN 8 |
| 443 | /* Length of tag for TLS */ |
| 444 | #define EVP_GCM_TLS_TAG_LEN 16 |
| 445 | |
| 446 | #define EVP_MAX_KEY_LENGTH 64 |
| 447 | #define EVP_MAX_IV_LENGTH 16 |
| 448 | #define EVP_MAX_BLOCK_LENGTH 32 |
| 449 | |
| 450 | struct evp_cipher_ctx_st { |
| 451 | /* cipher contains the underlying cipher for this context. */ |
| 452 | const EVP_CIPHER *cipher; |
| 453 | |
| 454 | /* app_data is a pointer to opaque, user data. */ |
| 455 | void *app_data; /* application stuff */ |
| 456 | |
| 457 | /* cipher_data points to the |cipher| specific state. */ |
| 458 | void *cipher_data; |
| 459 | |
| 460 | /* key_len contains the length of the key, which may differ from |
| 461 | * |cipher->key_len| if the cipher can take a variable key length. */ |
| 462 | unsigned key_len; |
| 463 | |
| 464 | /* encrypt is one if encrypting and zero if decrypting. */ |
| 465 | int encrypt; |
| 466 | |
| 467 | /* flags contains the OR of zero or more |EVP_CIPH_*| flags, above. */ |
| 468 | uint32_t flags; |
| 469 | |
| 470 | /* oiv contains the original IV value. */ |
| 471 | uint8_t oiv[EVP_MAX_IV_LENGTH]; |
| 472 | |
| 473 | /* iv contains the current IV value, which may have been updated. */ |
| 474 | uint8_t iv[EVP_MAX_IV_LENGTH]; |
| 475 | |
| 476 | /* buf contains a partial block which is used by, for example, CTR mode to |
| 477 | * store unused keystream bytes. */ |
| 478 | uint8_t buf[EVP_MAX_BLOCK_LENGTH]; |
| 479 | |
| 480 | /* buf_len contains the number of bytes of a partial block contained in |
| 481 | * |buf|. */ |
| 482 | int buf_len; |
| 483 | |
| 484 | /* num contains the number of bytes of |iv| which are valid for modes that |
| 485 | * manage partial blocks themselves. */ |
David Benjamin | 4969cc9 | 2016-04-22 15:02:23 -0400 | [diff] [blame] | 486 | unsigned num; |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 487 | |
| 488 | /* final_used is non-zero if the |final| buffer contains plaintext. */ |
| 489 | int final_used; |
| 490 | |
| 491 | /* block_mask contains |cipher->block_size| minus one. (The block size |
| 492 | * assumed to be a power of two.) */ |
| 493 | int block_mask; |
| 494 | |
| 495 | uint8_t final[EVP_MAX_BLOCK_LENGTH]; /* possible final block */ |
| 496 | } /* EVP_CIPHER_CTX */; |
| 497 | |
| 498 | typedef struct evp_cipher_info_st { |
| 499 | const EVP_CIPHER *cipher; |
| 500 | unsigned char iv[EVP_MAX_IV_LENGTH]; |
| 501 | } EVP_CIPHER_INFO; |
| 502 | |
Adam Langley | f40f42d | 2015-03-24 18:25:20 -0700 | [diff] [blame] | 503 | struct evp_cipher_st { |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 504 | /* type contains a NID identifing the cipher. (e.g. NID_aes_128_gcm.) */ |
Adam Langley | f40f42d | 2015-03-24 18:25:20 -0700 | [diff] [blame] | 505 | int nid; |
| 506 | |
| 507 | /* block_size contains the block size, in bytes, of the cipher, or 1 for a |
| 508 | * stream cipher. */ |
| 509 | unsigned block_size; |
| 510 | |
| 511 | /* key_len contains the key size, in bytes, for the cipher. If the cipher |
| 512 | * takes a variable key size then this contains the default size. */ |
| 513 | unsigned key_len; |
| 514 | |
| 515 | /* iv_len contains the IV size, in bytes, or zero if inapplicable. */ |
| 516 | unsigned iv_len; |
| 517 | |
| 518 | /* ctx_size contains the size, in bytes, of the per-key context for this |
| 519 | * cipher. */ |
| 520 | unsigned ctx_size; |
| 521 | |
| 522 | /* flags contains the OR of a number of flags. See |EVP_CIPH_*|. */ |
| 523 | uint32_t flags; |
| 524 | |
| 525 | /* app_data is a pointer to opaque, user data. */ |
| 526 | void *app_data; |
| 527 | |
| 528 | int (*init)(EVP_CIPHER_CTX *ctx, const uint8_t *key, const uint8_t *iv, |
| 529 | int enc); |
| 530 | |
| 531 | int (*cipher)(EVP_CIPHER_CTX *ctx, uint8_t *out, const uint8_t *in, |
| 532 | size_t inl); |
| 533 | |
Adam Langley | f4e4272 | 2015-06-04 17:45:09 -0700 | [diff] [blame] | 534 | /* cleanup, if non-NULL, releases memory associated with the context. It is |
| 535 | * called if |EVP_CTRL_INIT| succeeds. Note that |init| may not have been |
| 536 | * called at this point. */ |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 537 | void (*cleanup)(EVP_CIPHER_CTX *); |
Adam Langley | f40f42d | 2015-03-24 18:25:20 -0700 | [diff] [blame] | 538 | |
| 539 | int (*ctrl)(EVP_CIPHER_CTX *, int type, int arg, void *ptr); |
| 540 | }; |
| 541 | |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 542 | |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 543 | #if defined(__cplusplus) |
| 544 | } /* extern C */ |
David Benjamin | f0c4a6c | 2016-08-11 13:26:41 -0400 | [diff] [blame] | 545 | |
| 546 | #if !defined(BORINGSSL_NO_CXX) |
| 547 | extern "C++" { |
| 548 | |
| 549 | namespace bssl { |
| 550 | |
| 551 | BORINGSSL_MAKE_DELETER(EVP_CIPHER_CTX, EVP_CIPHER_CTX_free) |
| 552 | |
| 553 | using ScopedEVP_CIPHER_CTX = |
| 554 | internal::StackAllocated<EVP_CIPHER_CTX, int, EVP_CIPHER_CTX_init, |
| 555 | EVP_CIPHER_CTX_cleanup>; |
| 556 | |
| 557 | } // namespace bssl |
| 558 | |
| 559 | } // extern C++ |
| 560 | #endif |
| 561 | |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 562 | #endif |
| 563 | |
Adam Langley | e9ada86 | 2015-05-11 17:20:37 -0700 | [diff] [blame] | 564 | #define CIPHER_R_AES_KEY_SETUP_FAILED 100 |
| 565 | #define CIPHER_R_BAD_DECRYPT 101 |
| 566 | #define CIPHER_R_BAD_KEY_LENGTH 102 |
| 567 | #define CIPHER_R_BUFFER_TOO_SMALL 103 |
| 568 | #define CIPHER_R_CTRL_NOT_IMPLEMENTED 104 |
| 569 | #define CIPHER_R_CTRL_OPERATION_NOT_IMPLEMENTED 105 |
| 570 | #define CIPHER_R_DATA_NOT_MULTIPLE_OF_BLOCK_LENGTH 106 |
| 571 | #define CIPHER_R_INITIALIZATION_ERROR 107 |
| 572 | #define CIPHER_R_INPUT_NOT_INITIALIZED 108 |
| 573 | #define CIPHER_R_INVALID_AD_SIZE 109 |
| 574 | #define CIPHER_R_INVALID_KEY_LENGTH 110 |
| 575 | #define CIPHER_R_INVALID_NONCE_SIZE 111 |
| 576 | #define CIPHER_R_INVALID_OPERATION 112 |
| 577 | #define CIPHER_R_IV_TOO_LARGE 113 |
| 578 | #define CIPHER_R_NO_CIPHER_SET 114 |
| 579 | #define CIPHER_R_OUTPUT_ALIASES_INPUT 115 |
| 580 | #define CIPHER_R_TAG_TOO_LARGE 116 |
| 581 | #define CIPHER_R_TOO_LARGE 117 |
| 582 | #define CIPHER_R_UNSUPPORTED_AD_SIZE 118 |
| 583 | #define CIPHER_R_UNSUPPORTED_INPUT_SIZE 119 |
| 584 | #define CIPHER_R_UNSUPPORTED_KEY_SIZE 120 |
| 585 | #define CIPHER_R_UNSUPPORTED_NONCE_SIZE 121 |
| 586 | #define CIPHER_R_UNSUPPORTED_TAG_SIZE 122 |
| 587 | #define CIPHER_R_WRONG_FINAL_BLOCK_LENGTH 123 |
| 588 | #define CIPHER_R_NO_DIRECTION_SET 124 |
Robert Sloan | 8ff0355 | 2017-06-14 12:40:58 -0700 | [diff] [blame^] | 589 | #define CIPHER_R_INVALID_NONCE 125 |
Adam Langley | d9e397b | 2015-01-22 14:27:53 -0800 | [diff] [blame] | 590 | |
| 591 | #endif /* OPENSSL_HEADER_CIPHER_H */ |