| 1 |
|
| 2 | |
| 3 | * AES-XTS unauthenticated encryption and decryption
|
| 4 | *
|
| 5 | * Copyright 2026 Google LLC
|
| 6 |
|
| 7 | #ifndef _CRYPTO_AES_XTS_H
|
| 8 | #define _CRYPTO_AES_XTS_H
|
| 9 |
|
| 10 | #include <crypto/aes.h>
|
| 11 | #include <crypto/xts.h>
|
| 12 |
|
| 13 | |
| 14 | * struct aes_xts_key - A key prepared for AES-XTS encryption and decryption
|
| 15 | *
|
| 16 | * Note that (depending on the architecture) this typically is around 768 bytes,
|
| 17 | * which makes it a bit too large to allocate on the stack in most cases.
|
| 18 |
|
| 19 | struct aes_xts_key {
|
| 20 |
|
| 21 | struct aes_key main_key;
|
| 22 | struct aes_enckey tweak_key;
|
| 23 | };
|
| 24 |
|
| 25 | |
| 26 | * aes_xts_zeroize_key() - Zeroize an aes_xts_key structure
|
| 27 | * @key: The aes_xts_key to zeroize
|
| 28 |
|
| 29 | static inline void aes_xts_zeroize_key(struct aes_xts_key *key)
|
| 30 | {
|
| 31 | memzero_explicit(key, sizeof(*key));
|
| 32 | }
|
| 33 |
|
| 34 | |
| 35 | * aes_xts_preparekey() - Prepare a key for AES-XTS encryption and decryption
|
| 36 | * @key: (output) The key structure to initialize
|
| 37 | * @in_key: The raw AES-XTS key
|
| 38 | * @key_len: Length of the raw key in bytes
|
| 39 | * @flags: Optional flag XTS_FORBID_WEAK_KEYS to forbid keys whose two halves
|
| 40 | * are the same.
|
| 41 | *
|
| 42 | * Users should use aes_xts_zeroize_key() to zeroize the key struct at the end
|
| 43 | * of its lifetime. (But if this function fails, zeroization is unnecessary.)
|
| 44 | *
|
| 45 | * Context: Any context.
|
| 46 | * Return:
|
| 47 | * * 0 on success
|
| 48 | * * -EINVAL if the key is rejected because its length isn't 32, 64, or (when
|
| 49 | * FIPS mode isn't enabled) 48; or because its two halves are the same and
|
| 50 | * either XTS_FORBID_WEAK_KEYS is given or FIPS mode is enabled.
|
| 51 |
|
| 52 | int __must_check aes_xts_preparekey(struct aes_xts_key *key, const u8 *in_key,
|
| 53 | size_t key_len, int flags);
|
| 54 |
|
| 55 | |
| 56 | * aes_xts_encrypt() - Encrypt data using AES-XTS
|
| 57 | * @dst: The destination buffer. Can be in-place or out-of-place. For other
|
| 58 | * overlaps the behavior is unspecified.
|
| 59 | * @src: The source data
|
| 60 | * @len: Number of bytes to encrypt. On non-final calls it must be a nonzero
|
| 61 | * multiple of AES_BLOCK_SIZE. On the final call it can be any value >=
|
| 62 | * AES_BLOCK_SIZE, i.e. ciphertext stealing is supported.
|
| 63 | * @tweak: The tweak. It is updated with the next value, unless @len isn't a
|
| 64 | * multiple of AES_BLOCK_SIZE in which case the value is unspecified.
|
| 65 | * @key: The key, already prepared using aes_xts_preparekey()
|
| 66 | * @cont: %false to begin encrypting a new message (do the tweak encryption);
|
| 67 | * %true to continue encrypting a message (skip tweak encryption)
|
| 68 | *
|
| 69 | * This supports both one-shot and incremental encryption. On the first call,
|
| 70 | * pass @cont = %false. On any later calls, pass @cont = %true and the updated
|
| 71 | * @tweak; all earlier @len must have been multiples of AES_BLOCK_SIZE.
|
| 72 | *
|
| 73 | * Context: Any context.
|
| 74 |
|
| 75 | void aes_xts_encrypt(u8 *dst, const u8 *src, size_t len,
|
| 76 | u8 tweak[at_least AES_BLOCK_SIZE],
|
| 77 | const struct aes_xts_key *key, bool cont);
|
| 78 |
|
| 79 | |
| 80 | * aes_xts_decrypt() - Decrypt data using AES-XTS
|
| 81 | * @dst: The destination buffer. Can be in-place or out-of-place. For other
|
| 82 | * overlaps the behavior is unspecified.
|
| 83 | * @src: The source data
|
| 84 | * @len: Number of bytes to decrypt. On non-final calls it must be a nonzero
|
| 85 | * multiple of AES_BLOCK_SIZE. On the final call it can be any value >=
|
| 86 | * AES_BLOCK_SIZE, i.e. ciphertext stealing is supported.
|
| 87 | * @tweak: The tweak. It is updated with the next value, unless @len isn't a
|
| 88 | * multiple of AES_BLOCK_SIZE in which case the value is unspecified.
|
| 89 | * @key: The key, already prepared using aes_xts_preparekey()
|
| 90 | * @cont: %false to begin decrypting a new message (do the tweak encryption);
|
| 91 | * %true to continue decrypting a message (skip tweak encryption)
|
| 92 | *
|
| 93 | * This supports both one-shot and incremental decryption. On the first call,
|
| 94 | * pass @cont = %false. On any later calls, pass @cont = %true and the updated
|
| 95 | * @tweak; all earlier @len must have been multiples of AES_BLOCK_SIZE.
|
| 96 | *
|
| 97 | * Context: Any context.
|
| 98 |
|
| 99 | void aes_xts_decrypt(u8 *dst, const u8 *src, size_t len,
|
| 100 | u8 tweak[at_least AES_BLOCK_SIZE],
|
| 101 | const struct aes_xts_key *key, bool cont);
|
| 102 |
|
| 103 | #endif
|