Add support for hardware-wrapped inline crypto keys

Makefile

@@ -28,7 +28,7 @@ PREFIX ?= /usr/local
 # Directory where the binary gets installed
 BINDIR ?= $(PREFIX)/bin
 
-# Direectory where the man page gets installed
+# Directory where the man page gets installed
 MANDIR ?= $(PREFIX)/share/man
 
 # C compiler flags
@@ -67,8 +67,8 @@ fscryptctl.1: fscryptctl.1.md
 
 ##############################################################################
 
-# Don't format fscrypt_uapi.h, so that it stays identical to the kernel version.
-FILES_TO_FORMAT := $(filter-out fscrypt_uapi.h, $(SRC) $(HDRS))
+# Don't format UAPI files.  They should stay identical to the kernel's copies.
+FILES_TO_FORMAT := $(filter-out %_uapi.h, $(SRC) $(HDRS))
 
 .PHONY: format format-check
 format:
@@ -108,7 +108,7 @@ test: fscryptctl
 		 python3 -m pytest test.py -s -q
 
 # Depend on test-teardown so that anything already present is cleaned up first.
-test-setup:test-teardown
+test-setup: test-teardown
 	dd if=/dev/zero of="$(TEST_IMAGE)" bs=1M count=32
 	mkfs.ext4 -b 4096 -O encrypt -F "$(TEST_IMAGE)"
 	mkdir -p "$(TEST_DIR)"

NEWS.md

@@ -1,5 +1,12 @@
 # fscryptctl release notes
 
+## Version 1.3.0
+
+* `fscryptctl add_key` now supports the `--hw-wrapped-key` option.
+
+* Added new commands `fscryptctl import_hw_wrapped_key`,
+  `fscryptctl generate_hw_wrapped_key`, and `fscryptctl prepare_hw_wrapped_key`.
+
 ## Version 1.2.0
 
 * `fscryptctl set_policy` now accepts the `--data-unit-size` option.
@@ -72,4 +79,4 @@ Note: this release of `fscryptctl` only includes support for v1 policies.  For
 v2 policies, users will need to use v1.0.0 or later.
 
 For more information about v1 and v2 encryption policies, see [the Linux kernel
-documentation](https://www.kernel.org/doc/html/latest/filesystems/fscrypt.html).
+documentation](https://docs.kernel.org/filesystems/fscrypt.html).

README.md

@@ -5,9 +5,9 @@
 
 `fscryptctl` is a low-level tool written in C that handles raw keys and manages
 policies for [Linux filesystem
-encryption](https://www.kernel.org/doc/html/latest/filesystems/fscrypt.html),
-specifically the "fscrypt" kernel interface which is supported by the ext4,
-f2fs, UBIFS, and CephFS filesystems.
+encryption](https://docs.kernel.org/filesystems/fscrypt.html), specifically the
+"fscrypt" kernel interface which is supported by the ext4, f2fs, UBIFS, and
+CephFS filesystems.
 
 `fscryptctl` is mainly intended for embedded systems which can't use the
 full-featured [`fscrypt` tool](https://github.com/google/fscrypt), or for
@@ -18,8 +18,8 @@ which supports these features and generally is much easier to use.
 
 As `fscryptctl` is intended for advanced users, you should read the [kernel
 documentation for filesystem
-encryption](https://www.kernel.org/doc/html/latest/filesystems/fscrypt.html)
-before using `fscryptctl`.
+encryption](https://docs.kernel.org/filesystems/fscrypt.html) before using
+`fscryptctl`.
 
 For the release notes, see the [NEWS file](NEWS.md).
 
@@ -29,6 +29,7 @@ For the release notes, see the [NEWS file](NEWS.md).
 - [Runtime Dependencies](#runtime-dependencies)
 - [Features](#features)
 - [Example Usage](#example-usage)
+- [Example Usage with Hardware-Wrapped Key](#example-usage-with-hardware-wrapped-key)
 - [Contributing](#contributing)
 - [Legal](#legal)
 
@@ -72,6 +73,9 @@ tips](https://github.com/google/fscrypt#getting-encryption-not-enabled-on-an-ext
 * `fscryptctl key_status` - get the status of an encryption key on a filesystem
 * `fscryptctl get_policy` - get the encryption policy of a file or directory
 * `fscryptctl set_policy` - set the encryption policy of an empty directory
+* `fscryptctl import_hw_wrapped_key` - import a hardware-wrapped key
+* `fscryptctl generate_hw_wrapped_key` - generate a hardware-wrapped key
+* `fscryptctl prepare_hw_wrapped_key` - prepare a hardware-wrapped key
 
 For full usage details, see the manual page (`man fscryptctl`), or alternatively
 run `fscryptctl --help`.
@@ -154,6 +158,24 @@ bar foo
 foo
 ```
 
+## Example Usage with Hardware-Wrapped Key
+
+On systems that support hardware-wrapped inline encryption keys,
+hardware-wrapped keys can be used instead of raw keys:
+
+```shell
+> mkfs.ext4 -O encrypt,stable_inodes /dev/vdb
+> mount /dev/vdb -o inlinecrypt /mnt
+> head -c 32 /dev/urandom | fscryptctl import_hw_wrapped_key /dev/vdb > /tmp/lt_key
+> fscryptctl prepare_hw_wrapped_key /dev/vdb < /tmp/lt_key | fscryptctl add_key --hw-wrapped-key /mnt
+f12fccad977328d20a16c79627787a1c
+> mkdir /mnt/dir
+> fscryptctl set_policy --iv-ino-lblk-64 f12fccad977328d20a16c79627787a1c /mnt/dir
+```
+
+Hardware-wrapped inline encryption keys require Linux 6.16 or later as well as
+hardware that supports this feature, for example the Qualcomm SM8650 HDK.
+
 ## Contributing
 
 We would love to accept your contributions to `fscryptctl`.  See the

blk-crypto_uapi.h

@@ -0,0 +1,44 @@
+/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
+#ifndef _UAPI_LINUX_BLK_CRYPTO_H
+#define _UAPI_LINUX_BLK_CRYPTO_H
+
+#include <linux/ioctl.h>
+#include <linux/types.h>
+
+struct blk_crypto_import_key_arg {
+	/* Raw key (input) */
+	__u64 raw_key_ptr;
+	__u64 raw_key_size;
+	/* Long-term wrapped key blob (output) */
+	__u64 lt_key_ptr;
+	__u64 lt_key_size;
+	__u64 reserved[4];
+};
+
+struct blk_crypto_generate_key_arg {
+	/* Long-term wrapped key blob (output) */
+	__u64 lt_key_ptr;
+	__u64 lt_key_size;
+	__u64 reserved[4];
+};
+
+struct blk_crypto_prepare_key_arg {
+	/* Long-term wrapped key blob (input) */
+	__u64 lt_key_ptr;
+	__u64 lt_key_size;
+	/* Ephemerally-wrapped key blob (output) */
+	__u64 eph_key_ptr;
+	__u64 eph_key_size;
+	__u64 reserved[4];
+};
+
+/*
+ * These ioctls share the block device ioctl space; see uapi/linux/fs.h.
+ * 140-141 are reserved for future blk-crypto ioctls; any more than that would
+ * require an additional allocation from the block device ioctl space.
+ */
+#define BLKCRYPTOIMPORTKEY _IOWR(0x12, 137, struct blk_crypto_import_key_arg)
+#define BLKCRYPTOGENERATEKEY _IOWR(0x12, 138, struct blk_crypto_generate_key_arg)
+#define BLKCRYPTOPREPAREKEY _IOWR(0x12, 139, struct blk_crypto_prepare_key_arg)
+
+#endif /* _UAPI_LINUX_BLK_CRYPTO_H */

fscrypt_uapi.h

@@ -119,7 +119,7 @@ struct fscrypt_key_specifier {
  */
 struct fscrypt_provisioning_key_payload {
 	__u32 type;
-	__u32 __reserved;
+	__u32 flags;
 	__u8 raw[];
 };
 
@@ -128,7 +128,9 @@ struct fscrypt_add_key_arg {
 	struct fscrypt_key_specifier key_spec;
 	__u32 raw_size;
 	__u32 key_id;
-	__u32 __reserved[8];
+#define FSCRYPT_ADD_KEY_FLAG_HW_WRAPPED	0x00000001
+	__u32 flags;
+	__u32 __reserved[7];
 	__u8 raw[];
 };
 

fscryptctl.1.md

@@ -9,7 +9,10 @@ fscryptctl - low-level userspace tool for Linux filesystem encryption
 **fscryptctl remove_key** [*OPTION*...] *KEY_IDENTIFIER* *MOUNTPOINT* \
 **fscryptctl key_status** *KEY_IDENTIFIER* *MOUNTPOINT* \
 **fscryptctl get_policy** *PATH* \
-**fscryptctl set_policy** [*OPTION*...] *KEY_IDENTIFIER* *DIRECTORY*
+**fscryptctl set_policy** [*OPTION*...] *KEY_IDENTIFIER* *DIRECTORY* \
+**fscryptctl import_hw_wrapped_key** *BLOCK_DEVICE* \
+**fscryptctl generate_hw_wrapped_key** *BLOCK_DEVICE* \
+**fscryptctl prepare_hw_wrapped_key** *BLOCK_DEVICE*
 
 # DESCRIPTION
 
@@ -40,7 +43,7 @@ feature, see the references at the end of this page.
 
 # SUBCOMMANDS
 
-## **fscryptctl add_key** *MOUNTPOINT*
+## **fscryptctl add_key** [*OPTION*...] *MOUNTPOINT*
 
 Add an encryption key to the given mounted filesystem.  This will "unlock" any
 files and directories that are protected by the given key on the given
@@ -54,7 +57,11 @@ If successful, **fscryptctl add_key** will print the key identifier of the newly
 added key; this will be a 32-character hex string which can be passed to other
 **fscryptctl** commands.
 
-**fscryptctl add_key** does not accept any options.
+Options accepted by **fscryptctl add_key**:
+
+**\-\-hw\-wrapped\-key**
+:   Add a hardware-wrapped key.  If this option is given, the key must be a
+    hardware-wrapped key in ephemerally-wrapped form, rather than a raw key.
 
 ## **fscryptctl remove_key** [*OPTION*...] *KEY_IDENTIFIER* *MOUNTPOINT*
 
@@ -143,13 +150,50 @@ Options accepted by **fscryptctl set_policy**:
 :   Select the crypto data unit size, i.e. the granularity of file contents
     encryption, in bytes.
 
+## **fscryptctl import_hw_wrapped_key** *BLOCK_DEVICE*
+
+Create a hardware-wrapped inline encryption key by importing a raw key, turning
+it into a long-term wrapped key.  The raw key is read from standard input and
+the long-term wrapped key blob is written to standard output, both in binary.
+
+This subcommand is a thin wrapper around the **BLKCRYPTOIMPORTKEY** ioctl.  For
+more information, see the kernel documentation.
+
+**fscryptctl import_hw_wrapped_key** does not accept any options.
+
+## **fscryptctl generate_hw_wrapped_key** *BLOCK_DEVICE*
+
+Create a hardware-wrapped inline encryption key by having the hardware generate
+one.  The new long-term wrapped key blob is written to standard output in
+binary.
+
+This subcommand is a thin wrapper around the **BLKCRYPTOGENERATEKEY** ioctl.
+For more information, see the kernel documentation.
+
+**fscryptctl generate_hw_wrapped_key** does not accept any options.
+
+## **fscryptctl prepare_hw_wrapped_key** *BLOCK_DEVICE*
+
+Prepares a hardware-wrapped inline encryption key to be used by converting it
+from long-term wrapped form to ephemerally-wrapped form.  The long-term wrapped
+key blob is read from standard input and the ephemerally-wrapped key blob is
+written to standard output, both in binary.
+
+This subcommand is a thin wrapper around the **BLKCRYPTOPREPAREKEY** ioctl.  For
+more information, see the kernel documentation.
+
+**fscryptctl prepare_hw_wrapped_key** does not accept any options.
+
 # SEE ALSO
 
 * [**fscryptctl** README
   file](https://github.com/google/fscryptctl/blob/master/README.md)
 
 * [Linux kernel documentation for filesystem
-  encryption](https://www.kernel.org/doc/html/latest/filesystems/fscrypt.html)
+  encryption](https://docs.kernel.org/filesystems/fscrypt.html)
 
 * [**fscrypt** tool, recommended for most users over
   fscryptctl](https://github.com/google/fscrypt)
+
+* [Linux kernel documentation for hardware-wrapped
+  keys](https://docs.kernel.org/block/inline-encryption.html#hardware-wrapped-keys)