Skip to contentSkip to conversation

Implement PKCS#11 opaque keys support through OpenSSL pkcs11 engine

PATCH Applied Aleksander Adamowski 2 participants 2 messages Sep 9, 2021 – Sep 13, 2021

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH v5 1/1 Implement PKCS#11 opaque keys support through OpenSSL pkcs11 engine

PKCS#11 API allows us to use opaque keys confined in hardware security modules (HSMs) and similar hardware tokens without direct access to the key material, providing logical separation of the keys from the cryptographic operations performed using them.

This commit allows using the popular libp11 pkcs11 module for the OpenSSL library with fsverity so that direct access to a private key file isn't necessary to sign files.

The user needs to supply the path to the engine shared library (typically the libp11 shared object file) and the PKCS#11 module library (a shared object file specific to the given hardware token). The user may also supply a token-specific key identifier.

Test evidence with a hardware PKCS#11 token:

  $ echo test > dummy
  $ ./fsverity sign dummy dummy.sig \
    --pkcs11-engine=/usr/lib64/engines-1.1/libpkcs11.so \
    --pkcs11-module=/usr/local/lib64/pkcs11_module.so \
    --cert=test-pkcs11-cert.pem && echo OK;
  Signed file 'dummy'
  (sha256:c497326752e21b3992b57f7eff159102d474a97d972dc2c2d99d23e0f5fbdb65)
  OK

Test evidence for regression check (checking that regular file-based key signing still works):

  $ ./fsverity sign dummy dummy.sig --key=key.pem --cert=cert.pem && \
    echo  OK;
  Signed file 'dummy'
  (sha256:c497326752e21b3992b57f7eff159102d474a97d972dc2c2d99d23e0f5fbdb65)
  OK

[EB: Avoided overloading the --key option and keyfile field, clarified
the documentation, removed logic from cmd_sign.c that libfsverity already handles, and many other improvements.]

---
 include/libfsverity.h | 44 ++++++++++++++++++---
 lib/sign_digest.c     | 92 ++++++++++++++++++++++++++++++++++++++-----
 man/fsverity.1.md     | 28 +++++++++++--
 programs/cmd_sign.c   | 48 +++++++++++++++-------
 programs/fsverity.c   |  5 ++-
 programs/fsverity.h   |  3 ++
 6 files changed, 185 insertions(+), 35 deletions(-)
include/libfsverity.h +38 -6
index 6cefa2b..fe89371 100644
@@ -81,11 +81,44 @@ struct libfsverity_digest {
 	uint8_t digest[];		/* the actual digest */
 };
 
+/**
+ * struct libfsverity_signature_params - certificate and private key information
+ *
+ * Zero this, then set @certfile.  Then, to specify the private key by key file,
+ * set @keyfile.  Alternatively, to specify the private key by PKCS#11 token,
+ * set @pkcs11_engine, @pkcs11_module, and optionally @pkcs11_keyid.
+ *
+ * Support for PKCS#11 tokens is unavailable when libfsverity was linked to
+ * BoringSSL rather than OpenSSL.
+ */
 struct libfsverity_signature_params {
-	const char *keyfile;		/* path to key file (PEM format) */
-	const char *certfile;		/* path to certificate (PEM format) */
-	uint64_t reserved1[8];		/* must be 0 */
-	uintptr_t reserved2[8];		/* must be 0 */
+
+	/** @keyfile: the path to the key file in PEM format, when applicable */
+	const char *keyfile;
+
+	/** @certfile: the path to the certificate file in PEM format */
+	const char *certfile;
+
+	/** @reserved1: must be 0 */
+	uint64_t reserved1[8];
+
+	/**
+	 * @pkcs11_engine: the path to the PKCS#11 engine .so file, when
+	 * applicable
+	 */
+	const char *pkcs11_engine;
+
+	/**
+	 * @pkcs11_module: the path to the PKCS#11 module .so file, when
+	 * applicable
+	 */
+	const char *pkcs11_module;
+
+	/** @pkcs11_keyid: the PKCS#11 key identifier, when applicable */
+	const char *pkcs11_keyid;
+
+	/** @reserved2: must be 0 */
+	uintptr_t reserved2[5];
 };
 
 struct libfsverity_metadata_callbacks {
@@ -161,8 +194,7 @@ libfsverity_compute_digest(void *fd, libfsverity_read_fn_t read_fn,
  *          Documentation/filesystems/fsverity.rst in the kernel source tree for
  *          further details.
  * @digest: pointer to previously computed digest
- * @sig_params: struct libfsverity_signature_params providing filenames of
- *          the keyfile and certificate file. Reserved fields must be zero.
+ * @sig_params: pointer to the certificate and private key information
  * @sig_ret: Pointer to pointer for signed digest
  * @sig_size_ret: Pointer to size of signed return digest
  *
lib/sign_digest.c +83 -9

141 lines not on this page · raw message

man/fsverity.1.md +24 -4
index e1007f5..a983912 100644
@@ -11,7 +11,7 @@ fsverity - userspace utility for fs-verity
 **fsverity dump_metadata** [*OPTION*...] *TYPE* *FILE* \
 **fsverity enable** [*OPTION*...] *FILE* \
 **fsverity measure** *FILE*... \
-**fsverity sign \-\-key**=*KEYFILE* [*OPTION*...] *FILE* *OUT_SIGFILE*
+**fsverity sign** [*OPTION*...] *FILE* *OUT_SIGFILE*
 
 # DESCRIPTION
 
@@ -149,12 +149,18 @@ for each file regardless of the size of the file.
 
 **fsverity measure** does not accept any options.
 
-## **fsverity sign** **\-\-key**=*KEYFILE* [*OPTION*...] *FILE* *OUT_SIGFILE*
+## **fsverity sign** [*OPTION*...] *FILE* *OUT_SIGFILE*
 
 Sign the given file for fs-verity, in a way that is compatible with the Linux
 kernel's fs-verity built-in signature verification support.  The signature will
 be written to *OUT_SIGFILE* in PKCS#7 DER format.
 
+The private key can be specified either by key file or by PKCS#11 token.  To use
+a key file, provide **\-\-key** and optionally **\-\-cert**.  To use a PKCS#11
+token, provide **\-\-pkcs11-engine**, **\-\-pkcs11-module**, **\-\-cert**, and
+optionally **\-\-pkcs11-keyid**.  PKCS#11 token support is unavailable when
+fsverity-utils was built with BoringSSL rather than OpenSSL.
+
 Options accepted by **fsverity sign**:
 
 **\-\-block-size**=*BLOCK_SIZE*
@@ -163,14 +169,14 @@ Options accepted by **fsverity sign**:
 **\-\-cert**=*CERTFILE*
 :   Specifies the file that contains the certificate, in PEM format.  This
     option is required if *KEYFILE* contains only the private key and not also
-    the certificate.
+    the certificate, or if a PKCS#11 token is used.
 
 **\-\-hash-alg**=*HASH_ALG*
 :   Same as for **fsverity digest**.
 
 **\-\-key**=*KEYFILE*
 :   Specifies the file that contains the private key, in PEM format.  This
-    option is required.
+    option is required when not using a PKCS#11 token.
 
 **\-\-out-descriptor**=*FILE*
 :   Same as for **fsverity digest**.
@@ -178,6 +184,20 @@ Options accepted by **fsverity sign**:
 **\-\-out-merkle-tree**=*FILE*
 :   Same as for **fsverity digest**.
 
+**\-\-pkcs11-engine**=*SOFILE*
+:   Specifies the path to the OpenSSL PKCS#11 engine file.  This typically will
+    be a path to the libp11 .so file.  This option is required when using a
+    PKCS#11 token.
+
+**\-\-pkcs11-keyid**=*KEYID*
+:   Specifies the key identifier in the form of a PKCS#11 URI.  If not provided,
+    the default key associated with the token is used.  This option is only
+    applicable when using a PKCS#11 token.
+
+**\-\-pkcs11-module**=*SOFILE*
+:   Specifies the path to the PKCS#11 token-specific module library.  This
+    option is required when using a PKCS#11 token.
+
 **\-\-salt**=*SALT*
 :   Same as for **fsverity digest**.
 
programs/cmd_sign.c +34 -14

77 lines not on this page · raw message

programs/fsverity.c +3 -2
index f6aff3a..813ea2a 100644
@@ -58,10 +58,11 @@ static const struct fsverity_command {
 		.func = fsverity_cmd_sign,
 		.short_desc = "Sign a file for fs-verity",
 		.usage_str =
-"    fsverity sign FILE OUT_SIGFILE --key=KEYFILE\n"
+"    fsverity sign FILE OUT_SIGFILE\n"
+"               [--key=KEYFILE] [--cert=CERTFILE] [--pkcs11-engine=SOFILE]\n"
+"               [--pkcs11-module=SOFILE] [--pkcs11-keyid=KEYID]\n"
 "               [--hash-alg=HASH_ALG] [--block-size=BLOCK_SIZE] [--salt=SALT]\n"
 "               [--out-merkle-tree=FILE] [--out-descriptor=FILE]\n"
-"               [--cert=CERTFILE]\n"
 	}
 };
 
programs/fsverity.h +3 -0
index fe24087..ad54cc2 100644
@@ -31,6 +31,9 @@ enum {
 	OPT_OFFSET,
 	OPT_OUT_DESCRIPTOR,
 	OPT_OUT_MERKLE_TREE,
+	OPT_PKCS11_ENGINE,
+	OPT_PKCS11_KEYID,
+	OPT_PKCS11_MODULE,
 	OPT_SALT,
 	OPT_SIGNATURE,
 };
Signature · 1 line
2.30.2
maintainer Applied
#1 lore raw
Quoted 34 lines · Aleksander Adamowski

PKCS#11 API allows us to use opaque keys confined in hardware security modules (HSMs) and similar hardware tokens without direct access to the key material, providing logical separation of the keys from the cryptographic operations performed using them.

This commit allows using the popular libp11 pkcs11 module for the OpenSSL library with fsverity so that direct access to a private key file isn't necessary to sign files.

The user needs to supply the path to the engine shared library (typically the libp11 shared object file) and the PKCS#11 module library (a shared object file specific to the given hardware token). The user may also supply a token-specific key identifier.

Test evidence with a hardware PKCS#11 token:

  $ echo test > dummy
  $ ./fsverity sign dummy dummy.sig \
    --pkcs11-engine=/usr/lib64/engines-1.1/libpkcs11.so \
    --pkcs11-module=/usr/local/lib64/pkcs11_module.so \
    --cert=test-pkcs11-cert.pem && echo OK;
  Signed file 'dummy'
  (sha256:c497326752e21b3992b57f7eff159102d474a97d972dc2c2d99d23e0f5fbdb65)
  OK

Test evidence for regression check (checking that regular file-based key signing still works):

  $ ./fsverity sign dummy dummy.sig --key=key.pem --cert=cert.pem && \
    echo  OK;
  Signed file 'dummy'
  (sha256:c497326752e21b3992b57f7eff159102d474a97d972dc2c2d99d23e0f5fbdb65)
  OK
Quoted 6 lines

[EB: Avoided overloading the --key option and keyfile field, clarified
the documentation, removed logic from cmd_sign.c that libfsverity already handles, and many other improvements.]

---

Applied, thanks.

- Eric