xref: /linux/include/crypto/aes-xts.h (revision 486b257357c23743d9729ea715136d105fff461e)
1 /* SPDX-License-Identifier: GPL-2.0 */
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 	/* private: */
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 /* _CRYPTO_AES_XTS_H */
104