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
13enum 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 */
26enum 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 */
81struct 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 */
101struct 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 */
120struct 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
130static inline bool bio_has_crypt_ctx(struct bio *bio)
131{
132 return bio->bi_crypt_context;
133}
134
135void bio_crypt_set_ctx(struct bio *bio, const struct blk_crypto_key *key,
136 const u64 dun[BLK_CRYPTO_DUN_ARRAY_SIZE],
137 gfp_t gfp_mask);
138
139bool bio_crypt_dun_is_contiguous(const struct bio_crypt_ctx *bc,
140 unsigned int bytes,
141 const u64 next_dun[BLK_CRYPTO_DUN_ARRAY_SIZE]);
142
143int blk_crypto_init_key(struct blk_crypto_key *blk_key,
144 const u8 *key_bytes, size_t key_size,
145 enum blk_crypto_key_type key_type,
146 enum blk_crypto_mode_num crypto_mode,
147 unsigned int dun_bytes,
148 unsigned int data_unit_size);
149
150int blk_crypto_start_using_key(struct block_device *bdev,
151 const struct blk_crypto_key *key);
152
153void blk_crypto_evict_key(struct block_device *bdev,
154 const struct blk_crypto_key *key);
155
156bool blk_crypto_config_supported_natively(struct block_device *bdev,
157 const struct blk_crypto_config *cfg);
158bool blk_crypto_config_supported(struct block_device *bdev,
159 const struct blk_crypto_config *cfg);
160
161int blk_crypto_derive_sw_secret(struct block_device *bdev,
162 const u8 *eph_key, size_t eph_key_size,
163 u8 sw_secret[BLK_CRYPTO_SW_SECRET_SIZE]);
164
165#else /* CONFIG_BLK_INLINE_ENCRYPTION */
166
167static inline bool bio_has_crypt_ctx(struct bio *bio)
168{
169 return false;
170}
171
172#endif /* CONFIG_BLK_INLINE_ENCRYPTION */
173
174int __bio_crypt_clone(struct bio *dst, struct bio *src, gfp_t gfp_mask);
175/**
176 * bio_crypt_clone - clone bio encryption context
177 * @dst: destination bio
178 * @src: source bio
179 * @gfp_mask: memory allocation flags
180 *
181 * If @src has an encryption context, clone it to @dst.
182 *
183 * Return: 0 on success, -ENOMEM if out of memory. -ENOMEM is only possible if
184 * @gfp_mask doesn't include %__GFP_DIRECT_RECLAIM.
185 */
186static inline int bio_crypt_clone(struct bio *dst, struct bio *src,
187 gfp_t gfp_mask)
188{
189 if (bio_has_crypt_ctx(bio: src))
190 return __bio_crypt_clone(dst, src, gfp_mask);
191 return 0;
192}
193
194#endif /* __LINUX_BLK_CRYPTO_H */
195