Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) Inline Encryption
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) Background
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) ==========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) Inline encryption hardware sits logically between memory and the disk, and can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) en/decrypt data as it goes in/out of the disk. Inline encryption hardware has a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) fixed number of "keyslots" - slots into which encryption contexts (i.e. the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) encryption key, encryption algorithm, data unit size) can be programmed by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) kernel at any time. Each request sent to the disk can be tagged with the index
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) of a keyslot (and also a data unit number to act as an encryption tweak), and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) the inline encryption hardware will en/decrypt the data in the request with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) encryption context programmed into that keyslot. This is very different from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) full disk encryption solutions like self encrypting drives/TCG OPAL/ATA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) Security standards, since with inline encryption, any block on disk could be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) encrypted with any encryption context the kernel chooses.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) Objective
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) =========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) We want to support inline encryption (IE) in the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) To allow for testing, we also want a crypto API fallback when actual
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) IE hardware is absent. We also want IE to work with layered devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) like dm and loopback (i.e. we want to be able to use the IE hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) of the underlying devices if present, or else fall back to crypto API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) en/decryption).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) Constraints and notes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) - IE hardware has a limited number of "keyslots" that can be programmed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38)   with an encryption context (key, algorithm, data unit size, etc.) at any time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39)   One can specify a keyslot in a data request made to the device, and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40)   device will en/decrypt the data using the encryption context programmed into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41)   that specified keyslot. When possible, we want to make multiple requests with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42)   the same encryption context share the same keyslot.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) - We need a way for upper layers like filesystems to specify an encryption
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45)   context to use for en/decrypting a struct bio, and a device driver (like UFS)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46)   needs to be able to use that encryption context when it processes the bio.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) - We need a way for device drivers to expose their inline encryption
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49)   capabilities in a unified way to the upper layers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52) Design
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53) ======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) We add a struct bio_crypt_ctx to struct bio that can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) represent an encryption context, because we need to be able to pass this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) encryption context from the upper layers (like the fs layer) to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) device driver to act upon.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) While IE hardware works on the notion of keyslots, the FS layer has no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) knowledge of keyslots - it simply wants to specify an encryption context to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) use while en/decrypting a bio.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) We introduce a keyslot manager (KSM) that handles the translation from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) encryption contexts specified by the FS to keyslots on the IE hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) This KSM also serves as the way IE hardware can expose its capabilities to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) upper layers. The generic mode of operation is: each device driver that wants
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) to support IE will construct a KSM and set it up in its struct request_queue.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) Upper layers that want to use IE on this device can then use this KSM in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) the device's struct request_queue to translate an encryption context into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71) a keyslot. The presence of the KSM in the request queue shall be used to mean
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72) that the device supports IE.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74) The KSM uses refcounts to track which keyslots are idle (either they have no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) encryption context programmed, or there are no in-flight struct bios
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) referencing that keyslot). When a new encryption context needs a keyslot, it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77) tries to find a keyslot that has already been programmed with the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78) encryption context, and if there is no such keyslot, it evicts the least
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) recently used idle keyslot and programs the new encryption context into that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80) one. If no idle keyslots are available, then the caller will sleep until there
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) is at least one.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84) blk-mq changes, other block layer changes and blk-crypto-fallback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) =================================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) We add a pointer to a ``bi_crypt_context`` and ``keyslot`` to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) struct request. These will be referred to as the ``crypto fields``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) for the request. This ``keyslot`` is the keyslot into which the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90) ``bi_crypt_context`` has been programmed in the KSM of the ``request_queue``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) that this request is being sent to.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) We introduce ``block/blk-crypto-fallback.c``, which allows upper layers to remain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) blissfully unaware of whether or not real inline encryption hardware is present
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95) underneath. When a bio is submitted with a target ``request_queue`` that doesn't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96) support the encryption context specified with the bio, the block layer will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97) en/decrypt the bio with the blk-crypto-fallback.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99) If the bio is a ``WRITE`` bio, a bounce bio is allocated, and the data in the bio
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) is encrypted stored in the bounce bio - blk-mq will then proceed to process the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) bounce bio as if it were not encrypted at all (except when blk-integrity is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) concerned). ``blk-crypto-fallback`` sets the bounce bio's ``bi_end_io`` to an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) internal function that cleans up the bounce bio and ends the original bio.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) If the bio is a ``READ`` bio, the bio's ``bi_end_io`` (and also ``bi_private``)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) is saved and overwritten by ``blk-crypto-fallback`` to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) ``bio_crypto_fallback_decrypt_bio``.  The bio's ``bi_crypt_context`` is also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) overwritten with ``NULL``, so that to the rest of the stack, the bio looks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) as if it was a regular bio that never had an encryption context specified.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) ``bio_crypto_fallback_decrypt_bio`` will decrypt the bio, restore the original
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) ``bi_end_io`` (and also ``bi_private``) and end the bio again.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) Regardless of whether real inline encryption hardware is used or the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) blk-crypto-fallback is used, the ciphertext written to disk (and hence the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) on-disk format of data) will be the same (assuming the hardware's implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) of the algorithm being used adheres to spec and functions correctly).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) If a ``request queue``'s inline encryption hardware claimed to support the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) encryption context specified with a bio, then it will not be handled by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) ``blk-crypto-fallback``. We will eventually reach a point in blk-mq when a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) struct request needs to be allocated for that bio. At that point,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) blk-mq tries to program the encryption context into the ``request_queue``'s
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) keyslot_manager, and obtain a keyslot, which it stores in its newly added
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) ``keyslot`` field. This keyslot is released when the request is completed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) When the first bio is added to a request, ``blk_crypto_rq_bio_prep`` is called,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) which sets the request's ``crypt_ctx`` to a copy of the bio's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) ``bi_crypt_context``. bio_crypt_do_front_merge is called whenever a subsequent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) bio is merged to the front of the request, which updates the ``crypt_ctx`` of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) the request so that it matches the newly merged bio's ``bi_crypt_context``. In particular, the request keeps a copy of the ``bi_crypt_context`` of the first
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) bio in its bio-list (blk-mq needs to be careful to maintain this invariant
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) during bio and request merges).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) To make it possible for inline encryption to work with request queue based
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) layered devices, when a request is cloned, its ``crypto fields`` are cloned as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) well. When the cloned request is submitted, blk-mq programs the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) ``bi_crypt_context`` of the request into the clone's request_queue's keyslot
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) manager, and stores the returned keyslot in the clone's ``keyslot``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) API presented to users of the block layer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) =========================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) ``struct blk_crypto_key`` represents a crypto key (the raw key, size of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) key, the crypto algorithm to use, the data unit size to use, and the number of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) bytes required to represent data unit numbers that will be specified with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) ``bi_crypt_context``).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) ``blk_crypto_init_key`` allows upper layers to initialize such a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) ``blk_crypto_key``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) ``bio_crypt_set_ctx`` should be called on any bio that a user of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) the block layer wants en/decrypted via inline encryption (or the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) blk-crypto-fallback, if hardware support isn't available for the desired
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) crypto configuration). This function takes the ``blk_crypto_key`` and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) data unit number (DUN) to use when en/decrypting the bio.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) ``blk_crypto_config_supported`` allows upper layers to query whether or not the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) an encryption context passed to request queue can be handled by blk-crypto
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) (either by real inline encryption hardware, or by the blk-crypto-fallback).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) This is useful e.g. when blk-crypto-fallback is disabled, and the upper layer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) wants to use an algorithm that may not supported by hardware - this function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) lets the upper layer know ahead of time that the algorithm isn't supported,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) and the upper layer can fallback to something else if appropriate.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) ``blk_crypto_start_using_key`` - Upper layers must call this function on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) ``blk_crypto_key`` and a ``request_queue`` before using the key with any bio
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) headed for that ``request_queue``. This function ensures that either the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) hardware supports the key's crypto settings, or the crypto API fallback has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) transforms for the needed mode allocated and ready to go. Note that this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) function may allocate an ``skcipher``, and must not be called from the data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) path, since allocating ``skciphers`` from the data path can deadlock.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) ``blk_crypto_evict_key`` *must* be called by upper layers before a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) ``blk_crypto_key`` is freed. Further, it *must* only be called only once
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) there are no more in-flight requests that use that ``blk_crypto_key``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) ``blk_crypto_evict_key`` will ensure that a key is removed from any keyslots in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) inline encryption hardware that the key might have been programmed into (or the blk-crypto-fallback).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) API presented to device drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) A :c:type:``struct blk_keyslot_manager`` should be set up by device drivers in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) the ``request_queue`` of the device. The device driver needs to call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) ``blk_ksm_init`` (or its resource-managed variant ``devm_blk_ksm_init``) on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) ``blk_keyslot_manager``, while specifying the number of keyslots supported by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) the hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) The device driver also needs to tell the KSM how to actually manipulate the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) IE hardware in the device to do things like programming the crypto key into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) the IE hardware into a particular keyslot. All this is achieved through the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) struct blk_ksm_ll_ops field in the KSM that the device driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) must fill up after initing the ``blk_keyslot_manager``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) The KSM also handles runtime power management for the device when applicable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) (e.g. when it wants to program a crypto key into the IE hardware, the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) must be runtime powered on) - so the device driver must also set the ``dev``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) field in the ksm to point to the `struct device` for the KSM to use for runtime
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) power management.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) ``blk_ksm_reprogram_all_keys`` can be called by device drivers if the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) needs each and every of its keyslots to be reprogrammed with the key it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) "should have" at the point in time when the function is called. This is useful
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) e.g. if a device loses all its keys on runtime power down/up.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) If the driver used ``blk_ksm_init`` instead of ``devm_blk_ksm_init``, then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) ``blk_ksm_destroy`` should be called to free up all resources used by a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) ``blk_keyslot_manager`` once it is no longer needed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) Layered Devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) Request queue based layered devices like dm-rq that wish to support IE need to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) create their own keyslot manager for their request queue, and expose whatever
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) functionality they choose. When a layered device wants to pass a clone of that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) request to another ``request_queue``, blk-crypto will initialize and prepare the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) clone as necessary - see ``blk_crypto_insert_cloned_request`` in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) ``blk-crypto.c``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) Future Optimizations for layered devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) ========================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) Creating a keyslot manager for a layered device uses up memory for each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) keyslot, and in general, a layered device merely passes the request on to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) "child" device, so the keyslots in the layered device itself are completely
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) unused, and don't need any refcounting or keyslot programming. We can instead
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) define a new type of KSM; the "passthrough KSM", that layered devices can use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) to advertise an unlimited number of keyslots, and support for any encryption
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) algorithms they choose, while not actually using any memory for each keyslot.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) Another use case for the "passthrough KSM" is for IE devices that do not have a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) limited number of keyslots.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) Interaction between inline encryption and blk integrity
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) =======================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) At the time of this patch, there is no real hardware that supports both these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) features. However, these features do interact with each other, and it's not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) completely trivial to make them both work together properly. In particular,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) when a WRITE bio wants to use inline encryption on a device that supports both
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) features, the bio will have an encryption context specified, after which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) its integrity information is calculated (using the plaintext data, since
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) the encryption will happen while data is being written), and the data and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) integrity info is sent to the device. Obviously, the integrity info must be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) verified before the data is encrypted. After the data is encrypted, the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) must not store the integrity info that it received with the plaintext data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) since that might reveal information about the plaintext data. As such, it must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) re-generate the integrity info from the ciphertext data and store that on disk
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) instead. Another issue with storing the integrity info of the plaintext data is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) that it changes the on disk format depending on whether hardware inline
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) encryption support is present or the kernel crypto API fallback is used (since
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) if the fallback is used, the device will receive the integrity info of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) ciphertext, not that of the plaintext).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) Because there isn't any real hardware yet, it seems prudent to assume that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) hardware implementations might not implement both features together correctly,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) and disallow the combination for now. Whenever a device supports integrity, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) kernel will pretend that the device does not support hardware inline encryption
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) (by essentially setting the keyslot manager in the request_queue of the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) to NULL). When the crypto API fallback is enabled, this means that all bios with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) and encryption context will use the fallback, and IO will complete as usual.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) When the fallback is disabled, a bio with an encryption context will be failed.