1 /********************************************************************** 2 Copyright(c) 2011-2024 Intel Corporation All rights reserved. 3 4 Redistribution and use in source and binary forms, with or without 5 modification, are permitted provided that the following conditions 6 are met: 7 * Redistributions of source code must retain the above copyright 8 notice, this list of conditions and the following disclaimer. 9 * Redistributions in binary form must reproduce the above copyright 10 notice, this list of conditions and the following disclaimer in 11 the documentation and/or other materials provided with the 12 distribution. 13 * Neither the name of Intel Corporation nor the names of its 14 contributors may be used to endorse or promote products derived 15 from this software without specific prior written permission. 16 17 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 19 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 20 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 21 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 22 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 23 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 27 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28 **********************************************************************/ 29 30 #ifndef _AES_XTS_H 31 #define _AES_XTS_H 32 33 /** 34 * @file aes_xts.h 35 * @brief AES XTS encryption function prototypes. 36 * 37 * This defines the interface to optimized AES XTS functions 38 * 39 * <b>Pre-expanded keys</b> 40 * 41 * For key encryption, pre-expanded keys are stored in the order that they will be 42 * used. As an example, if Key[0] is the 128-bit initial key used for an AES-128 43 * encryption, the rest of the keys are stored as follows: 44 * 45 * <ul> 46 * <li> Key[0] : Initial encryption key 47 * <li> Key[1] : Round 1 encryption key 48 * <li> Key[2] : Round 2 encryption key 49 * <li> ... 50 * <li> Key[10] : Round 10 encryption key 51 * </ul> 52 * 53 * For decryption, the order of keys is reversed. However, we apply the 54 * necessary aesimc instructions before storing the expanded keys. For the same key 55 * used above, the pre-expanded keys will be stored as follows: 56 * 57 * <ul> 58 * <li> Key[0] : Round 10 encryption key 59 * <li> Key[1] : aesimc(Round 9 encryption key) 60 * <li> Key[2] : aesimc(Round 8 encryption key) 61 * <li> ... 62 * <li> Key[9] : aesimc(Round 1 encryption key) 63 * <li> Key[10] : Initial encryption key 64 * </ul> 65 * 66 * <b>Note:</b> The expanded key decryption requires a decryption key only for the block 67 * decryption step. The tweak step in the expanded key decryption requires the same expanded 68 * encryption key that is used in the expanded key encryption. 69 * 70 * <b>Input and Output Buffers </b> 71 * 72 * The input and output buffers can be overlapping as long as the output buffer 73 * pointer is not less than the input buffer pointer. If the two pointers are the 74 * same, then encryption/decryption will occur in-place. 75 * 76 * <b>Data Length</b> 77 * 78 * <ul> 79 * <li> The functions support data length of any bytes greater than or equal to 16 bytes. 80 * <li> Data length is a 64-bit value, which makes the largest possible data length 81 * 2^64 - 1 bytes. 82 * <li> For data lengths from 0 to 15 bytes, the functions return without any error 83 * codes, without reading or writing any data. 84 * <li> The functions only support byte lengths, not bits. 85 * </ul> 86 * 87 * <b>Initial Tweak</b> 88 * 89 * The functions accept a 128-bit initial tweak value. The user is responsible for 90 * padding the initial tweak value to this length. 91 * 92 * <b>Data Alignment</b> 93 * 94 * The input and output buffers, keys, pre-expanded keys and initial tweak value 95 * are not required to be aligned to 16 bytes, any alignment works. 96 * 97 */ 98 99 #include <stdint.h> 100 #include "types.h" 101 102 #ifdef __cplusplus 103 extern "C" { 104 #endif 105 106 /* 107 * Define enums from API v2.24, so applications that were using this version 108 * will still be compiled successfully. 109 * This list does not need to be extended for new definitions. 110 */ 111 #ifndef NO_COMPAT_ISAL_CRYPTO_API_2_24 112 /***** Previous hash constants and typedefs *****/ 113 #define AES_XTS_MIN_LEN ISAL_AES_XTS_MIN_LEN 114 #define AES_XTS_MAX_LEN ISAL_AES_XTS_MAX_LEN 115 #endif /* !NO_COMPAT_ISAL_CRYPTO_API_2_24 */ 116 117 #define ISAL_AES_XTS_MIN_LEN 16 118 #define ISAL_AES_XTS_MAX_LEN (1 << 24) 119 120 /** @brief XTS-AES-128 Encryption 121 * 122 * @requires AES-NI 123 * @deprecated Please use isal_aes_xts_enc_128() instead. 124 */ 125 ISAL_DEPRECATED("Please use isal_aes_xts_enc_128() instead") 126 void 127 XTS_AES_128_enc(uint8_t *k2, //!< key used for tweaking, 16 bytes 128 uint8_t *k1, //!< key used for encryption of tweaked plaintext, 16 bytes 129 uint8_t *TW_initial, //!< initial tweak value, 16 bytes 130 uint64_t N, //!< sector size, in bytes 131 const uint8_t *pt, //!< plaintext sector input data 132 uint8_t *ct //!< ciphertext sector output data 133 ); 134 135 /** @brief XTS-AES-128 Encryption with pre-expanded keys 136 * 137 * @requires AES-NI 138 * @deprecated Please use isal_aes_xts_enc_128_expanded_key() instead. 139 */ 140 ISAL_DEPRECATED("Please use isal_aes_xts_enc_128_expanded_key() instead") 141 void 142 XTS_AES_128_enc_expanded_key( 143 uint8_t *k2, //!< expanded key used for tweaking, 16*11 bytes 144 uint8_t *k1, //!< expanded key used for encryption of tweaked plaintext, 16*11 bytes 145 uint8_t *TW_initial, //!< initial tweak value, 16 bytes 146 uint64_t N, //!< sector size, in bytes 147 const uint8_t *pt, //!< plaintext sector input data 148 uint8_t *ct //!< ciphertext sector output data 149 ); 150 151 /** @brief XTS-AES-128 Decryption 152 * 153 * @requires AES-NI 154 * @deprecated Please use isal_aes_xts_dec_128() instead. 155 */ 156 ISAL_DEPRECATED("Please use isal_aes_xts_dec_128() instead") 157 void 158 XTS_AES_128_dec(uint8_t *k2, //!< key used for tweaking, 16 bytes 159 uint8_t *k1, //!< key used for decryption of tweaked ciphertext, 16 bytes 160 uint8_t *TW_initial, //!< initial tweak value, 16 bytes 161 uint64_t N, //!< sector size, in bytes 162 const uint8_t *ct, //!< ciphertext sector input data 163 uint8_t *pt //!< plaintext sector output data 164 ); 165 166 /** @brief XTS-AES-128 Decryption with pre-expanded keys 167 * 168 * @requires AES-NI 169 * @deprecated Please use isal_aes_xts_dec_128_expanded_key() instead. 170 */ 171 ISAL_DEPRECATED("Please use isal_aes_xts_dec_128_expanded_key() instead") 172 void 173 XTS_AES_128_dec_expanded_key( 174 uint8_t *k2, //!< expanded key used for tweaking, 16*11 bytes - encryption key is used 175 uint8_t *k1, //!< expanded decryption key used for decryption of tweaked ciphertext, 16*11 176 //!< bytes 177 uint8_t *TW_initial, //!< initial tweak value, 16 bytes 178 uint64_t N, //!< sector size, in bytes 179 const uint8_t *ct, //!< ciphertext sector input data 180 uint8_t *pt //!< plaintext sector output data 181 ); 182 183 /** @brief XTS-AES-256 Encryption 184 * 185 * @requires AES-NI 186 * @deprecated Please use isal_aes_xts_enc_256() instead. 187 */ 188 ISAL_DEPRECATED("Please use isal_aes_xts_enc_256() instead") 189 void 190 XTS_AES_256_enc(uint8_t *k2, //!< key used for tweaking, 16*2 bytes 191 uint8_t *k1, //!< key used for encryption of tweaked plaintext, 16*2 bytes 192 uint8_t *TW_initial, //!< initial tweak value, 16 bytes 193 uint64_t N, //!< sector size, in bytes 194 const uint8_t *pt, //!< plaintext sector input data 195 uint8_t *ct //!< ciphertext sector output data 196 ); 197 198 /** @brief XTS-AES-256 Encryption with pre-expanded keys 199 * 200 * @requires AES-NI 201 * @deprecated Please use isal_aes_xts_enc_256_expanded_key() instead. 202 */ 203 ISAL_DEPRECATED("Please use isal_aes_xts_enc_256_expanded_key() instead") 204 void 205 XTS_AES_256_enc_expanded_key( 206 uint8_t *k2, //!< expanded key used for tweaking, 16*15 bytes 207 uint8_t *k1, //!< expanded key used for encryption of tweaked plaintext, 16*15 bytes 208 uint8_t *TW_initial, //!< initial tweak value, 16 bytes 209 uint64_t N, //!< sector size, in bytes 210 const uint8_t *pt, //!< plaintext sector input data 211 uint8_t *ct //!< ciphertext sector output data 212 ); 213 214 /** @brief XTS-AES-256 Decryption 215 * 216 * @requires AES-NI 217 * @deprecated Please use isal_aes_xts_dec_256() instead. 218 */ 219 ISAL_DEPRECATED("Please use isal_aes_xts_dec_256() instead") 220 void 221 XTS_AES_256_dec(uint8_t *k2, //!< key used for tweaking, 16*2 bytes 222 uint8_t *k1, //!< key used for decryption of tweaked ciphertext, 16*2 bytes 223 uint8_t *TW_initial, //!< initial tweak value, 16 bytes 224 uint64_t N, //!< sector size, in bytes 225 const uint8_t *ct, //!< ciphertext sector input data 226 uint8_t *pt //!< plaintext sector output data 227 ); 228 229 /** @brief XTS-AES-256 Decryption with pre-expanded keys 230 * 231 * @requires AES-NI 232 * @deprecated Please use isal_aes_xts_dec_256_expanded_key() instead. 233 */ 234 ISAL_DEPRECATED("Please use isal_aes_xts_dec_256_expanded_key() instead") 235 void 236 XTS_AES_256_dec_expanded_key( 237 uint8_t *k2, //!< expanded key used for tweaking, 16*15 bytes - encryption key is used 238 uint8_t *k1, //!< expanded decryption key used for decryption of tweaked ciphertext, 16*15 239 //!< bytes 240 uint8_t *TW_initial, //!< initial tweak value, 16 bytes 241 uint64_t N, //!< sector size, in bytes 242 const uint8_t *ct, //!< ciphertext sector input data 243 uint8_t *pt //!< plaintext sector output data 244 ); 245 246 /** @brief XTS-AES-128 Encryption 247 * 248 * @requires AES extensions and SSE4.1 for x86 or ASIMD for ARM 249 * @return Operation status 250 * @retval 0 on success 251 * @retval Non-zero \a ISAL_CRYPTO_ERR on failure 252 */ 253 254 int 255 isal_aes_xts_enc_128(const uint8_t *k2, //!< key used for tweaking, 16 bytes 256 const uint8_t *k1, //!< key used for encryption of tweaked plaintext, 16 bytes 257 const uint8_t *initial_tweak, //!< initial tweak value, 16 bytes 258 const uint64_t len_bytes, //!< sector size, in bytes 259 const void *in, //!< plaintext sector input data 260 void *out //!< ciphertext sector output data 261 ); 262 263 /** @brief XTS-AES-128 Encryption with pre-expanded keys 264 * 265 * @requires AES extensions and SSE4.1 for x86 or ASIMD for ARM 266 * @return Operation status 267 * @retval 0 on success 268 * @retval Non-zero \a ISAL_CRYPTO_ERR on failure 269 */ 270 271 int 272 isal_aes_xts_enc_128_expanded_key( 273 const uint8_t *k2, //!< expnaded key used for tweaking, 16*11 bytes 274 const uint8_t *k1, //!< expanded key used for encryption of tweaked plaintext, 16*11 bytes 275 const uint8_t *initial_tweak, //!< initial tweak value, 16 bytes 276 const uint64_t len_bytes, //!< sector size, in bytes 277 const void *in, //!< plaintext sector input data 278 void *out //!< ciphertext sector output data 279 ); 280 281 /** @brief XTS-AES-128 Decryption 282 * 283 * @requires AES extensions and SSE4.1 for x86 or ASIMD for ARM 284 * @return Operation status 285 * @retval 0 on success 286 * @retval Non-zero \a ISAL_CRYPTO_ERR on failure 287 */ 288 289 int 290 isal_aes_xts_dec_128( 291 const uint8_t *k2, //!< key used for tweaking, 16 bytes 292 const uint8_t *k1, //!< key used for decryption of tweaked ciphertext, 16 bytes 293 const uint8_t *initial_tweak, //!< initial tweak value, 16 bytes 294 const uint64_t len_bytes, //!< sector size, in bytes 295 const void *in, //!< ciphertext sector input data 296 void *out //!< plaintext sector output data 297 ); 298 299 /** @brief XTS-AES-128 Decryption with pre-expanded keys 300 * 301 * @requires AES extensions and SSE4.1 for x86 or ASIMD for ARM 302 * @return Operation status 303 * @retval 0 on success 304 * @retval Non-zero \a ISAL_CRYPTO_ERR on failure 305 */ 306 307 int 308 isal_aes_xts_dec_128_expanded_key( 309 const uint8_t *k2, //!< expanded key used for tweaking, 16*11 bytes 310 const uint8_t *k1, //!< expanded key used for decryption of tweaked ciphertext, 16*11 bytes 311 const uint8_t *initial_tweak, //!< initial tweak value, 16 bytes 312 const uint64_t len_bytes, //!< sector size, in bytes 313 const void *in, //!< ciphertext sector input data 314 void *out //!< plaintext sector output data 315 ); 316 317 /** @brief XTS-AES-256 Encryption 318 * 319 * @requires AES extensions and SSE4.1 for x86 or ASIMD for ARM 320 * @return Operation status 321 * @retval 0 on success 322 * @retval Non-zero \a ISAL_CRYPTO_ERR on failure 323 */ 324 325 int 326 isal_aes_xts_enc_256( 327 const uint8_t *k2, //!< key used for tweaking, 16*2 bytes 328 const uint8_t *k1, //!< key used for encryption of tweaked plaintext, 16*2 bytes 329 const uint8_t *initial_tweak, //!< initial tweak value, 16 bytes 330 const uint64_t len_bytes, //!< sector size, in bytes 331 const void *in, //!< plaintext sector input data 332 void *out //!< ciphertext sector output data 333 ); 334 335 /** @brief XTS-AES-256 Encryption with pre-expanded keys 336 * 337 * @requires AES extensions and SSE4.1 for x86 or ASIMD for ARM 338 * @return Operation status 339 * @retval 0 on success 340 * @retval Non-zero \a ISAL_CRYPTO_ERR on failure 341 */ 342 343 int 344 isal_aes_xts_enc_256_expanded_key( 345 const uint8_t *k2, //!< expnaded key used for tweaking, 16*15 bytes 346 const uint8_t *k1, //!< expanded key used for encryption of tweaked plaintext, 16*15 bytes 347 const uint8_t *initial_tweak, //!< initial tweak value, 16 bytes 348 const uint64_t len_bytes, //!< sector size, in bytes 349 const void *in, //!< plaintext sector input data 350 void *out //!< ciphertext sector output data 351 ); 352 353 /** @brief XTS-AES-256 Decryption 354 * 355 * @requires AES extensions and SSE4.1 for x86 or ASIMD for ARM 356 * @return Operation status 357 * @retval 0 on success 358 * @retval Non-zero \a ISAL_CRYPTO_ERR on failure 359 */ 360 361 int 362 isal_aes_xts_dec_256( 363 const uint8_t *k2, //!< key used for tweaking, 16 bytes 364 const uint8_t *k1, //!< key used for decryption of tweaked ciphertext, 16*2 bytes 365 const uint8_t *initial_tweak, //!< initial tweak value, 16*2 bytes 366 const uint64_t len_bytes, //!< sector size, in bytes 367 const void *in, //!< ciphertext sector input data 368 void *out //!< plaintext sector output data 369 ); 370 371 /** @brief XTS-AES-256 Decryption with pre-expanded keys 372 * 373 * @requires AES extensions and SSE4.1 for x86 or ASIMD for ARM 374 * @return Operation status 375 * @retval 0 on success 376 * @retval Non-zero \a ISAL_CRYPTO_ERR on failure 377 */ 378 379 int 380 isal_aes_xts_dec_256_expanded_key( 381 const uint8_t *k2, //!< expanded key used for tweaking, 16*15 bytes 382 const uint8_t *k1, //!< expanded key used for decryption of tweaked ciphertext, 16*15 bytes 383 const uint8_t *initial_tweak, //!< initial tweak value, 16 bytes 384 const uint64_t len_bytes, //!< sector size, in bytes 385 const void *in, //!< ciphertext sector input data 386 void *out //!< plaintext sector output data 387 ); 388 #ifdef __cplusplus 389 } 390 #endif 391 392 #endif //_AES_XTS_H 393