1 /* SPDX-License-Identifier: GPL-2.0 */
2 /*
3 * Copyright 2019 Google LLC
4 */
5
6 #ifndef __LINUX_BLK_CRYPTO_H
7 #define __LINUX_BLK_CRYPTO_H
8
9 #include <linux/minmax.h>
10 #include <linux/types.h>
11 #include <uapi/linux/blk-crypto.h>
12
13 enum blk_crypto_mode_num {
14 BLK_ENCRYPTION_MODE_INVALID,
15 BLK_ENCRYPTION_MODE_AES_256_XTS,
16 BLK_ENCRYPTION_MODE_AES_128_CBC_ESSIV,
17 BLK_ENCRYPTION_MODE_ADIANTUM,
18 BLK_ENCRYPTION_MODE_SM4_XTS,
19 BLK_ENCRYPTION_MODE_MAX,
20 };
21
22 /*
23 * Supported types of keys. Must be bitflags due to their use in
24 * blk_crypto_profile::key_types_supported.
25 */
26 enum blk_crypto_key_type {
27 /*
28 * Raw keys (i.e. "software keys"). These keys are simply kept in raw,
29 * plaintext form in kernel memory.
30 */
31 BLK_CRYPTO_KEY_TYPE_RAW = 0x1,
32
33 /*
34 * Hardware-wrapped keys. These keys are only present in kernel memory
35 * in ephemerally-wrapped form, and they can only be unwrapped by
36 * dedicated hardware. For details, see the "Hardware-wrapped keys"
37 * section of Documentation/block/inline-encryption.rst.
38 */
39 BLK_CRYPTO_KEY_TYPE_HW_WRAPPED = 0x2,
40 };
41
42 /*
43 * Currently the maximum raw key size is 64 bytes, as that is the key size of
44 * BLK_ENCRYPTION_MODE_AES_256_XTS which takes the longest key.
45 *
46 * The maximum hardware-wrapped key size depends on the hardware's key wrapping
47 * algorithm, which is a hardware implementation detail, so it isn't precisely
48 * specified. But currently 128 bytes is plenty in practice. Implementations
49 * are recommended to wrap a 32-byte key for the hardware KDF with AES-256-GCM,
50 * which should result in a size closer to 64 bytes than 128.
51 *
52 * Both of these values can trivially be increased if ever needed.
53 */
54 #define BLK_CRYPTO_MAX_RAW_KEY_SIZE 64
55 #define BLK_CRYPTO_MAX_HW_WRAPPED_KEY_SIZE 128
56
57 #define BLK_CRYPTO_MAX_ANY_KEY_SIZE \
58 MAX(BLK_CRYPTO_MAX_RAW_KEY_SIZE, BLK_CRYPTO_MAX_HW_WRAPPED_KEY_SIZE)
59
60 /*
61 * Size of the "software secret" which can be derived from a hardware-wrapped
62 * key. This is currently always 32 bytes. Note, the choice of 32 bytes
63 * assumes that the software secret is only used directly for algorithms that
64 * don't require more than a 256-bit key to get the desired security strength.
65 * If it were to be used e.g. directly as an AES-256-XTS key, then this would
66 * need to be increased (which is possible if hardware supports it, but care
67 * would need to be taken to avoid breaking users who need exactly 32 bytes).
68 */
69 #define BLK_CRYPTO_SW_SECRET_SIZE 32
70
71 /**
72 * struct blk_crypto_config - an inline encryption key's crypto configuration
73 * @crypto_mode: encryption algorithm this key is for
74 * @data_unit_size: the data unit size for all encryption/decryptions with this
75 * key. This is the size in bytes of each individual plaintext and
76 * ciphertext. This is always a power of 2. It might be e.g. the
77 * filesystem block size or the disk sector size.
78 * @dun_bytes: the maximum number of bytes of DUN used when using this key
79 * @key_type: the type of this key -- either raw or hardware-wrapped
80 */
81 struct blk_crypto_config {
82 enum blk_crypto_mode_num crypto_mode;
83 unsigned int data_unit_size;
84 unsigned int dun_bytes;
85 enum blk_crypto_key_type key_type;
86 };
87
88 /**
89 * struct blk_crypto_key - an inline encryption key
90 * @crypto_cfg: the crypto mode, data unit size, key type, and other
91 * characteristics of this key and how it will be used
92 * @data_unit_size_bits: log2 of data_unit_size
93 * @size: size of this key in bytes. The size of a raw key is fixed for a given
94 * crypto mode, but the size of a hardware-wrapped key can vary.
95 * @bytes: the bytes of this key. Only the first @size bytes are significant.
96 *
97 * A blk_crypto_key is immutable once created, and many bios can reference it at
98 * the same time. It must not be freed until all bios using it have completed
99 * and it has been evicted from all devices on which it may have been used.
100 */
101 struct blk_crypto_key {
102 struct blk_crypto_config crypto_cfg;
103 unsigned int data_unit_size_bits;
104 unsigned int size;
105 u8 bytes[BLK_CRYPTO_MAX_ANY_KEY_SIZE];
106 };
107
108 #define BLK_CRYPTO_MAX_IV_SIZE 32
109 #define BLK_CRYPTO_DUN_ARRAY_SIZE (BLK_CRYPTO_MAX_IV_SIZE / sizeof(u64))
110
111 /**
112 * struct bio_crypt_ctx - an inline encryption context
113 * @bc_key: the key, algorithm, and data unit size to use
114 * @bc_dun: the data unit number (starting IV) to use
115 *
116 * A bio_crypt_ctx specifies that the contents of the bio will be encrypted (for
117 * write requests) or decrypted (for read requests) inline by the storage device
118 * or controller, or by the crypto API fallback.
119 */
120 struct bio_crypt_ctx {
121 const struct blk_crypto_key *bc_key;
122 u64 bc_dun[BLK_CRYPTO_DUN_ARRAY_SIZE];
123 };
124
125 #include <linux/blk_types.h>
126 #include <linux/blkdev.h>
127
128 #ifdef CONFIG_BLK_INLINE_ENCRYPTION
129
bio_has_crypt_ctx(struct bio * bio)130 static inline bool bio_has_crypt_ctx(struct bio *bio)
131 {
132 return bio->bi_crypt_context;
133 }
134
bio_crypt_ctx(struct bio * bio)135 static inline struct bio_crypt_ctx *bio_crypt_ctx(struct bio *bio)
136 {
137 return bio->bi_crypt_context;
138 }
139
140 void bio_crypt_set_ctx(struct bio *bio, const struct blk_crypto_key *key,
141 const u64 dun[BLK_CRYPTO_DUN_ARRAY_SIZE],
142 gfp_t gfp_mask);
143
144 bool bio_crypt_dun_is_contiguous(const struct bio_crypt_ctx *bc,
145 unsigned int bytes,
146 const u64 next_dun[BLK_CRYPTO_DUN_ARRAY_SIZE]);
147
148 int blk_crypto_init_key(struct blk_crypto_key *blk_key,
149 const u8 *key_bytes, size_t key_size,
150 enum blk_crypto_key_type key_type,
151 enum blk_crypto_mode_num crypto_mode,
152 unsigned int dun_bytes,
153 unsigned int data_unit_size);
154
155 int blk_crypto_start_using_key(struct block_device *bdev,
156 const struct blk_crypto_key *key);
157
158 void blk_crypto_evict_key(struct block_device *bdev,
159 const struct blk_crypto_key *key);
160
161 bool blk_crypto_config_supported_natively(struct block_device *bdev,
162 const struct blk_crypto_config *cfg);
163 bool blk_crypto_config_supported(struct block_device *bdev,
164 const struct blk_crypto_config *cfg);
165
166 int blk_crypto_derive_sw_secret(struct block_device *bdev,
167 const u8 *eph_key, size_t eph_key_size,
168 u8 sw_secret[BLK_CRYPTO_SW_SECRET_SIZE]);
169
170 #else /* CONFIG_BLK_INLINE_ENCRYPTION */
171
bio_has_crypt_ctx(struct bio * bio)172 static inline bool bio_has_crypt_ctx(struct bio *bio)
173 {
174 return false;
175 }
176
bio_crypt_ctx(struct bio * bio)177 static inline struct bio_crypt_ctx *bio_crypt_ctx(struct bio *bio)
178 {
179 return NULL;
180 }
181
182 #endif /* CONFIG_BLK_INLINE_ENCRYPTION */
183
184 bool __blk_crypto_submit_bio(struct bio *bio);
185
186 /**
187 * blk_crypto_submit_bio - Submit a bio that may have a crypto context
188 * @bio: bio to submit
189 *
190 * If @bio has no crypto context, or the crypt context attached to @bio is
191 * supported by the underlying device's inline encryption hardware, just submit
192 * @bio.
193 *
194 * Otherwise, try to perform en/decryption for this bio by falling back to the
195 * kernel crypto API. For encryption this means submitting newly allocated
196 * bios for the encrypted payload while keeping back the source bio until they
197 * complete, while for reads the decryption happens in-place by a hooked in
198 * completion handler.
199 */
blk_crypto_submit_bio(struct bio * bio)200 static inline void blk_crypto_submit_bio(struct bio *bio)
201 {
202 if (!bio_has_crypt_ctx(bio) || __blk_crypto_submit_bio(bio))
203 submit_bio(bio);
204 }
205
206 int __bio_crypt_clone(struct bio *dst, struct bio *src, gfp_t gfp_mask);
207 /**
208 * bio_crypt_clone - clone bio encryption context
209 * @dst: destination bio
210 * @src: source bio
211 * @gfp_mask: memory allocation flags
212 *
213 * If @src has an encryption context, clone it to @dst.
214 *
215 * Return: 0 on success, -ENOMEM if out of memory. -ENOMEM is only possible if
216 * @gfp_mask doesn't include %__GFP_DIRECT_RECLAIM.
217 */
bio_crypt_clone(struct bio * dst,struct bio * src,gfp_t gfp_mask)218 static inline int bio_crypt_clone(struct bio *dst, struct bio *src,
219 gfp_t gfp_mask)
220 {
221 if (bio_has_crypt_ctx(src))
222 return __bio_crypt_clone(dst, src, gfp_mask);
223 return 0;
224 }
225
226 #endif /* __LINUX_BLK_CRYPTO_H */
227