blk-crypto.h

  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(src))
190		return __bio_crypt_clone(dst, src, gfp_mask);
191	return 0;
192}
193
194#endif /* __LINUX_BLK_CRYPTO_H */