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

Signed-off-by: Aleksander Adamowski <olo@fb.com>
[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.]
Link: https://lore.kernel.org/r/20210909212731.1151190-1-olo@fb.com
Signed-off-by: Eric Biggers <ebiggers@google.com>

1 files changed, 24 insertions, 4 deletions

diff --git a/man/fsverity.1.md b/man/fsverity.1.md
index e1007f5..a983912 100644
--- a/man/fsverity.1.md
+++ b/man/fsverity.1.md
@@ -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**.