fscryptctl: add support for encrypted and trusted keys

For both v1 and v2 key setup mechanisms, userspace supplies the raw key
material to the kernel after which it is never again disclosed to
userspace. Use of encrypted and trusted keys offers stronger guarantees:
The key material is generated with the kernel and is never disclosed to
userspace in clear text and, in the case of trusted keys, can be directly
rooted to a trust source like a TPM chip.

Support for using encrypted and trusted keys is not yet mainline.
This draft PR is meant to be illustrative. It will be finalized should
the fscrypt encrypted/trusted key extension be merged.

Signed-off-by: Ahmad Fatoum <[email protected]>

Author: a3f

README.md

@@ -74,12 +74,17 @@ tips](https://github.com/google/fscrypt#getting-encryption-not-enabled-on-an-ext
 For full usage details, see the manual page (`man fscryptctl`), or alternatively
 run `fscryptctl --help`.
 
-The `add_key` command accepts the encryption key in binary on standard input.
+The `add_key` command, by default, accepts the encryption key in binary on
+standard input.
 It is critical that this be a real cryptographic key (and not a passphrase, for
 example), since `fscryptctl` doesn't do key stretching itself.  Obviously, don't
 store the raw encryption key alongside the encrypted files.  (If you need
 support for passphrases, use `fscrypt` instead of `fscryptctl`.)
 
+Alternatively, `add_key --description=$desc` will instruct the kernel to
+extract the kernel material from an existing encrypted or trusted key with
+the description `$desc`.
+
 After running the `add_key` command to add an encryption key to a filesystem,
 you can use the `set_policy` command to create an encrypted directory on that
 filesystem.  The encryption key is specified by the 32-character hex "key

fscrypt_uapi.h

@@ -120,12 +120,26 @@ struct fscrypt_provisioning_key_payload {
 	__u8 raw[];
 };
 
+/*
+ * fscrypt_add_key_arg::raw contains the raw key material directly
+ * if key_id == 0
+ */
+#define FSCRYPT_KEY_ADD_RAW_ASIS		0
+
+/*
+ * fscrypt_add_key_arg::raw is a key descriptor for an already
+ * existing kernel encrypted or trusted key if key_id == 0.
+ * The kernel key's material will be used as input for fscrypt.
+ */
+#define FSCRYPT_KEY_ADD_RAW_DESC		1
+
 /* Struct passed to FS_IOC_ADD_ENCRYPTION_KEY */
 struct fscrypt_add_key_arg {
 	struct fscrypt_key_specifier key_spec;
 	__u32 raw_size;
 	__u32 key_id;
-	__u32 __reserved[8];
+	__u32 raw_flags;	/* one of FSCRYPT_KEY_ADD_RAW_* */
+	__u32 __reserved[7];
 	__u8 raw[];
 };
 

fscryptctl.1.md

@@ -40,7 +40,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 +54,12 @@ 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**:
+
+**\-\-description**=*DESCRIPTION*
+:   Don't read raw key material from standard input. Instead, instruct the
+    kernel to extract key material from an existing encrypted or trusted
+    key with the supplied *DESCRIPTION*.
 
 ## **fscryptctl remove_key** [*OPTION*...] *KEY_IDENTIFIER* *MOUNTPOINT*
 

fscryptctl.c

@@ -65,6 +65,8 @@ static void secure_wipe(void *v, size_t n) {
 #define FSCRYPT_KEY_DESCRIPTOR_HEX_SIZE ((2 * FSCRYPT_KEY_DESCRIPTOR_SIZE) + 1)
 #define FSCRYPT_KEY_IDENTIFIER_HEX_SIZE ((2 * FSCRYPT_KEY_IDENTIFIER_SIZE) + 1)
 
+#define FSCRYPT_RAW_MAX_SIZE	4096 // max(KEY_MAX_DESC_SIZE, FSCRYPT_MAX_KEY_SIZE)
+
 // Human-readable strings for encryption modes, indexed by the encryption mode
 static const char *const mode_strings[] = {
     [FSCRYPT_MODE_AES_256_XTS] = "AES-256-XTS",
@@ -78,6 +80,7 @@ static const char *const mode_strings[] = {
 static const int padding_values[] = {4, 8, 16, 32};
 
 enum {
+  OPT_KEY_DESCRIPTION,
   OPT_ALL_USERS,
   OPT_CONTENTS,
   OPT_DIRECT_KEY,
@@ -94,8 +97,9 @@ static void __attribute__((__noreturn__)) usage(FILE *out) {
       "  fscryptctl <command> [arguments] [options]\n"
       "\nCommands:\n"
       "  fscryptctl add_key <mountpoint>\n"
-      "    Read a key from stdin, add it to the specified mounted filesystem,\n"
-      "    and print its identifier.\n"
+      "    Add a key add to the specified mounted filesystem and print its\n"
+      "    identifier. Raw key is read from stdin by default or is taken\n"
+      "    from the payload of a kernel trusted or encrypted key\n"
       "  fscryptctl remove_key <key identifier> <mountpoint>\n"
       "    Remove the key with the specified identifier from the specified\n"
       "    mounted filesystem.\n"
@@ -112,6 +116,10 @@ static void __attribute__((__noreturn__)) usage(FILE *out) {
       "        print this help screen\n"
       "    -v, --version\n"
       "        print the version of fscrypt\n"
+      "    add_key\n"
+      "        --description=<trusted-or-encrypted-key>\n"
+      "            Instead of reading raw key material over stdin, use the\n"
+      "            payload of an already existing encrypted or trusted key.\n"
       "    remove_key\n"
       "        --all-users\n"
       "            force-remove all users' claims to the key (requires root)\n"
@@ -372,22 +380,45 @@ static bool set_policy(const char *path,
 // -----------------------------------------------------------------------------
 
 static int cmd_add_key(int argc, char *const argv[]) {
-  handle_no_options(&argc, &argv);
+  const char *desc = NULL;
+
+  static const struct option add_key_options[] = {
+    {"description", required_argument, NULL, OPT_KEY_DESCRIPTION}, {NULL, 0, NULL, 0}};
+
+  int ch;
+  while ((ch = getopt_long(argc, argv, "", add_key_options, NULL)) != -1) {
+    switch (ch) {
+      case OPT_KEY_DESCRIPTION:
+        desc = optarg;
+        break;
+      default:
+        usage(stderr);
+    }
+  }
+  argc -= optind;
+  argv += optind;
   if (argc != 1) {
     fputs("error: must specify a single mountpoint\n", stderr);
     return EXIT_FAILURE;
   }
   const char *mountpoint = argv[0];
 
   struct fscrypt_add_key_arg *arg =
-      calloc(sizeof(*arg) + FSCRYPT_MAX_KEY_SIZE, 1);
+      calloc(sizeof(*arg) + FSCRYPT_RAW_MAX_SIZE, 1);
   if (!arg) {
     fputs("error: failed to allocate memory\n", stderr);
     return EXIT_FAILURE;
   }
 
   int status = EXIT_FAILURE;
-  arg->raw_size = read_key(arg->raw);
+  if (desc) {
+	  arg->raw_flags = FSCRYPT_KEY_ADD_RAW_DESC;
+	  arg->raw_size = strlen(desc);
+	  memcpy(arg->raw, desc, arg->raw_size);
+  } else {
+	  arg->raw_flags = FSCRYPT_KEY_ADD_RAW_ASIS;
+	  arg->raw_size = read_key(arg->raw);
+  }
   if (arg->raw_size == 0) {
     goto cleanup;
   }