include/linux/blk-crypto-profile.h

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 /*
0003  * Copyright 2019 Google LLC
0004  */
0005
0006 #ifndef __LINUX_BLK_CRYPTO_PROFILE_H
0007 #define __LINUX_BLK_CRYPTO_PROFILE_H
0008
0009 #include <linux/bio.h>
0010 #include <linux/blk-crypto.h>
0011
0012 struct blk_crypto_profile;
0013
0014 /**
0015  * struct blk_crypto_ll_ops - functions to control inline encryption hardware
0016  *
0017  * Low-level operations for controlling inline encryption hardware.  This
0018  * interface must be implemented by storage drivers that support inline
0019  * encryption.  All functions may sleep, are serialized by profile->lock, and
0020  * are never called while profile->dev (if set) is runtime-suspended.
0021  */
0022 struct blk_crypto_ll_ops {
0023
0024     /**
0025      * @keyslot_program: Program a key into the inline encryption hardware.
0026      *
0027      * Program @key into the specified @slot in the inline encryption
0028      * hardware, overwriting any key that the keyslot may already contain.
0029      * The keyslot is guaranteed to not be in-use by any I/O.
0030      *
0031      * This is required if the device has keyslots.  Otherwise (i.e. if the
0032      * device is a layered device, or if the device is real hardware that
0033      * simply doesn't have the concept of keyslots) it is never called.
0034      *
0035      * Must return 0 on success, or -errno on failure.
0036      */
0037     int (*keyslot_program)(struct blk_crypto_profile *profile,
0038                    const struct blk_crypto_key *key,
0039                    unsigned int slot);
0040
0041     /**
0042      * @keyslot_evict: Evict a key from the inline encryption hardware.
0043      *
0044      * If the device has keyslots, this function must evict the key from the
0045      * specified @slot.  The slot will contain @key, but there should be no
0046      * need for the @key argument to be used as @slot should be sufficient.
0047      * The keyslot is guaranteed to not be in-use by any I/O.
0048      *
0049      * If the device doesn't have keyslots itself, this function must evict
0050      * @key from any underlying devices.  @slot won't be valid in this case.
0051      *
0052      * If there are no keyslots and no underlying devices, this function
0053      * isn't required.
0054      *
0055      * Must return 0 on success, or -errno on failure.
0056      */
0057     int (*keyslot_evict)(struct blk_crypto_profile *profile,
0058                  const struct blk_crypto_key *key,
0059                  unsigned int slot);
0060 };
0061
0062 /**
0063  * struct blk_crypto_profile - inline encryption profile for a device
0064  *
0065  * This struct contains a storage device's inline encryption capabilities (e.g.
0066  * the supported crypto algorithms), driver-provided functions to control the
0067  * inline encryption hardware (e.g. programming and evicting keys), and optional
0068  * device-independent keyslot management data.
0069  */
0070 struct blk_crypto_profile {
0071
0072     /* public: Drivers must initialize the following fields. */
0073
0074     /**
0075      * @ll_ops: Driver-provided functions to control the inline encryption
0076      * hardware, e.g. program and evict keys.
0077      */
0078     struct blk_crypto_ll_ops ll_ops;
0079
0080     /**
0081      * @max_dun_bytes_supported: The maximum number of bytes supported for
0082      * specifying the data unit number (DUN).  Specifically, the range of
0083      * supported DUNs is 0 through (1 << (8 * max_dun_bytes_supported)) - 1.
0084      */
0085     unsigned int max_dun_bytes_supported;
0086
0087     /**
0088      * @modes_supported: Array of bitmasks that specifies whether each
0089      * combination of crypto mode and data unit size is supported.
0090      * Specifically, the i'th bit of modes_supported[crypto_mode] is set if
0091      * crypto_mode can be used with a data unit size of (1 << i).  Note that
0092      * only data unit sizes that are powers of 2 can be supported.
0093      */
0094     unsigned int modes_supported[BLK_ENCRYPTION_MODE_MAX];
0095
0096     /**
0097      * @dev: An optional device for runtime power management.  If the driver
0098      * provides this device, it will be runtime-resumed before any function
0099      * in @ll_ops is called and will remain resumed during the call.
0100      */
0101     struct device *dev;
0102
0103     /* private: The following fields shouldn't be accessed by drivers. */
0104
0105     /* Number of keyslots, or 0 if not applicable */
0106     unsigned int num_slots;
0107
0108     /*
0109      * Serializes all calls to functions in @ll_ops as well as all changes
0110      * to @slot_hashtable.  This can also be taken in read mode to look up
0111      * keyslots while ensuring that they can't be changed concurrently.
0112      */
0113     struct rw_semaphore lock;
0114
0115     /* List of idle slots, with least recently used slot at front */
0116     wait_queue_head_t idle_slots_wait_queue;
0117     struct list_head idle_slots;
0118     spinlock_t idle_slots_lock;
0119
0120     /*
0121      * Hash table which maps struct *blk_crypto_key to keyslots, so that we
0122      * can find a key's keyslot in O(1) time rather than O(num_slots).
0123      * Protected by 'lock'.
0124      */
0125     struct hlist_head *slot_hashtable;
0126     unsigned int log_slot_ht_size;
0127
0128     /* Per-keyslot data */
0129     struct blk_crypto_keyslot *slots;
0130 };
0131
0132 int blk_crypto_profile_init(struct blk_crypto_profile *profile,
0133                 unsigned int num_slots);
0134
0135 int devm_blk_crypto_profile_init(struct device *dev,
0136                  struct blk_crypto_profile *profile,
0137                  unsigned int num_slots);
0138
0139 unsigned int blk_crypto_keyslot_index(struct blk_crypto_keyslot *slot);
0140
0141 blk_status_t blk_crypto_get_keyslot(struct blk_crypto_profile *profile,
0142                     const struct blk_crypto_key *key,
0143                     struct blk_crypto_keyslot **slot_ptr);
0144
0145 void blk_crypto_put_keyslot(struct blk_crypto_keyslot *slot);
0146
0147 bool __blk_crypto_cfg_supported(struct blk_crypto_profile *profile,
0148                 const struct blk_crypto_config *cfg);
0149
0150 int __blk_crypto_evict_key(struct blk_crypto_profile *profile,
0151                const struct blk_crypto_key *key);
0152
0153 void blk_crypto_reprogram_all_keys(struct blk_crypto_profile *profile);
0154
0155 void blk_crypto_profile_destroy(struct blk_crypto_profile *profile);
0156
0157 void blk_crypto_intersect_capabilities(struct blk_crypto_profile *parent,
0158                        const struct blk_crypto_profile *child);
0159
0160 bool blk_crypto_has_capabilities(const struct blk_crypto_profile *target,
0161                  const struct blk_crypto_profile *reference);
0162
0163 void blk_crypto_update_capabilities(struct blk_crypto_profile *dst,
0164                     const struct blk_crypto_profile *src);
0165
0166 #endif /* __LINUX_BLK_CRYPTO_PROFILE_H */