1 /* 2 * Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. 3 * 4 * Licensed under the OpenSSL license (the "License"). You may not use 5 * this file except in compliance with the License. You can obtain a copy 6 * in the file LICENSE in the source distribution or at 7 * https://www.openssl.org/source/license.html 8 */ 9 10 #ifndef OPENSSL_HEADER_AES_H 11 #define OPENSSL_HEADER_AES_H 12 13 #include <openssl/base.h> 14 15 #if defined(__cplusplus) 16 extern "C" { 17 #endif 18 19 20 // Raw AES functions. 21 22 23 #define AES_ENCRYPT 1 24 #define AES_DECRYPT 0 25 26 // AES_MAXNR is the maximum number of AES rounds. 27 #define AES_MAXNR 14 28 29 #define AES_BLOCK_SIZE 16 30 31 // aes_key_st should be an opaque type, but EVP requires that the size be 32 // known. 33 struct aes_key_st { 34 uint32_t rd_key[4 * (AES_MAXNR + 1)]; 35 unsigned rounds; 36 }; 37 typedef struct aes_key_st AES_KEY; 38 39 // AES_set_encrypt_key configures |aeskey| to encrypt with the |bits|-bit key, 40 // |key|. |key| must point to |bits|/8 bytes. It returns zero on success and a 41 // negative number if |bits| is an invalid AES key size. 42 // 43 // WARNING: this function breaks the usual return value convention. 44 OPENSSL_EXPORT int AES_set_encrypt_key(const uint8_t *key, unsigned bits, 45 AES_KEY *aeskey); 46 47 // AES_set_decrypt_key configures |aeskey| to decrypt with the |bits|-bit key, 48 // |key|. |key| must point to |bits|/8 bytes. It returns zero on success and a 49 // negative number if |bits| is an invalid AES key size. 50 // 51 // WARNING: this function breaks the usual return value convention. 52 OPENSSL_EXPORT int AES_set_decrypt_key(const uint8_t *key, unsigned bits, 53 AES_KEY *aeskey); 54 55 // AES_encrypt encrypts a single block from |in| to |out| with |key|. The |in| 56 // and |out| pointers may overlap. 57 OPENSSL_EXPORT void AES_encrypt(const uint8_t *in, uint8_t *out, 58 const AES_KEY *key); 59 60 // AES_decrypt decrypts a single block from |in| to |out| with |key|. The |in| 61 // and |out| pointers may overlap. 62 OPENSSL_EXPORT void AES_decrypt(const uint8_t *in, uint8_t *out, 63 const AES_KEY *key); 64 65 66 // Block cipher modes. 67 68 // AES_ctr128_encrypt encrypts (or decrypts, it's the same in CTR mode) |len| 69 // bytes from |in| to |out|. The |num| parameter must be set to zero on the 70 // first call and |ivec| will be incremented. This function may be called 71 // in-place with |in| equal to |out|, but otherwise the buffers may not 72 // partially overlap. A partial overlap may overwrite input data before it is 73 // read. 74 OPENSSL_EXPORT void AES_ctr128_encrypt(const uint8_t *in, uint8_t *out, 75 size_t len, const AES_KEY *key, 76 uint8_t ivec[AES_BLOCK_SIZE], 77 uint8_t ecount_buf[AES_BLOCK_SIZE], 78 unsigned int *num); 79 80 // AES_ecb_encrypt encrypts (or decrypts, if |enc| == |AES_DECRYPT|) a single, 81 // 16 byte block from |in| to |out|. This function may be called in-place with 82 // |in| equal to |out|, but otherwise the buffers may not partially overlap. A 83 // partial overlap may overwrite input data before it is read. 84 OPENSSL_EXPORT void AES_ecb_encrypt(const uint8_t *in, uint8_t *out, 85 const AES_KEY *key, const int enc); 86 87 // AES_cbc_encrypt encrypts (or decrypts, if |enc| == |AES_DECRYPT|) |len| 88 // bytes from |in| to |out|. The length must be a multiple of the block size. 89 // This function may be called in-place with |in| equal to |out|, but otherwise 90 // the buffers may not partially overlap. A partial overlap may overwrite input 91 // data before it is read. 92 OPENSSL_EXPORT void AES_cbc_encrypt(const uint8_t *in, uint8_t *out, size_t len, 93 const AES_KEY *key, uint8_t *ivec, 94 const int enc); 95 96 // AES_ofb128_encrypt encrypts (or decrypts, it's the same in OFB mode) |len| 97 // bytes from |in| to |out|. The |num| parameter must be set to zero on the 98 // first call. This function may be called in-place with |in| equal to |out|, 99 // but otherwise the buffers may not partially overlap. A partial overlap may 100 // overwrite input data before it is read. 101 OPENSSL_EXPORT void AES_ofb128_encrypt(const uint8_t *in, uint8_t *out, 102 size_t len, const AES_KEY *key, 103 uint8_t *ivec, int *num); 104 105 // AES_cfb128_encrypt encrypts (or decrypts, if |enc| == |AES_DECRYPT|) |len| 106 // bytes from |in| to |out|. The |num| parameter must be set to zero on the 107 // first call. This function may be called in-place with |in| equal to |out|, 108 // but otherwise the buffers may not partially overlap. A partial overlap may 109 // overwrite input data before it is read. 110 OPENSSL_EXPORT void AES_cfb128_encrypt(const uint8_t *in, uint8_t *out, 111 size_t len, const AES_KEY *key, 112 uint8_t *ivec, int *num, int enc); 113 114 115 // AES key wrap. 116 // 117 // These functions implement AES Key Wrap mode, as defined in RFC 3394. They 118 // should never be used except to interoperate with existing systems that use 119 // this mode. 120 121 // AES_wrap_key performs AES key wrap on |in| which must be a multiple of 8 122 // bytes. |iv| must point to an 8 byte value or be NULL to use the default IV. 123 // |key| must have been configured for encryption. On success, it writes 124 // |in_len| + 8 bytes to |out| and returns |in_len| + 8. Otherwise, it returns 125 // -1. 126 OPENSSL_EXPORT int AES_wrap_key(const AES_KEY *key, const uint8_t *iv, 127 uint8_t *out, const uint8_t *in, size_t in_len); 128 129 // AES_unwrap_key performs AES key unwrap on |in| which must be a multiple of 8 130 // bytes. |iv| must point to an 8 byte value or be NULL to use the default IV. 131 // |key| must have been configured for decryption. On success, it writes 132 // |in_len| - 8 bytes to |out| and returns |in_len| - 8. Otherwise, it returns 133 // -1. 134 OPENSSL_EXPORT int AES_unwrap_key(const AES_KEY *key, const uint8_t *iv, 135 uint8_t *out, const uint8_t *in, 136 size_t in_len); 137 138 139 // AES key wrap with padding. 140 // 141 // These functions implement AES Key Wrap with Padding mode, as defined in RFC 142 // 5649. They should never be used except to interoperate with existing systems 143 // that use this mode. 144 145 // AES_wrap_key_padded performs a padded AES key wrap on |in| which must be 146 // between 1 and 2^32-1 bytes. |key| must have been configured for encryption. 147 // On success it writes at most |max_out| bytes of ciphertext to |out|, sets 148 // |*out_len| to the number of bytes written, and returns one. On failure it 149 // returns zero. To ensure success, set |max_out| to at least |in_len| + 15. 150 OPENSSL_EXPORT int AES_wrap_key_padded(const AES_KEY *key, uint8_t *out, 151 size_t *out_len, size_t max_out, 152 const uint8_t *in, size_t in_len); 153 154 // AES_unwrap_key_padded performs a padded AES key unwrap on |in| which must be 155 // a multiple of 8 bytes. |key| must have been configured for decryption. On 156 // success it writes at most |max_out| bytes to |out|, sets |*out_len| to the 157 // number of bytes written, and returns one. On failure it returns zero. Setting 158 // |max_out| to |in_len| is a sensible estimate. 159 OPENSSL_EXPORT int AES_unwrap_key_padded(const AES_KEY *key, uint8_t *out, 160 size_t *out_len, size_t max_out, 161 const uint8_t *in, size_t in_len); 162 163 164 #if defined(__cplusplus) 165 } // extern C 166 #endif 167 168 #endif // OPENSSL_HEADER_AES_H 169