Skip to contentSkip to conversation

Implement PKCS#11 opaque keys support through OpenSSL pkcs11 engine

PATCH Superseded Aleksander Adamowski 2 participants 7 messages Aug 28, 2021 – Sep 9, 2021

Subsystems (2)

v2 of 5 Superseded Latest is v5 →

lore
Share & tools
lore
#0 lore raw

PATCH v2 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 libp11 shared object file) and the PKCS#11 module library (a shared object file specific to the given hardware token).

Additionally, the existing key argument can be used to pass an optional token-specific key identifier (instead of a private key file name) for tokens that can contain multiple keys.

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
---
 include/libfsverity.h |  6 ++-
 lib/sign_digest.c     | 96 ++++++++++++++++++++++++++++++++++++++++---
 man/fsverity.1.md     | 23 ++++++++++-
 programs/cmd_sign.c   | 31 ++++++++++++++
 programs/fsverity.c   |  4 +-
 programs/fsverity.h   |  2 +
 6 files changed, 151 insertions(+), 11 deletions(-)
include/libfsverity.h +4 -2
index 6cefa2b..4b34f43 100644
@@ -82,10 +82,12 @@ struct libfsverity_digest {
 };
 
 struct libfsverity_signature_params {
-	const char *keyfile;		/* path to key file (PEM format) */
+	const char *keyfile;	/* path to key file (PEM format), optional */
 	const char *certfile;		/* path to certificate (PEM format) */
 	uint64_t reserved1[8];		/* must be 0 */
-	uintptr_t reserved2[8];		/* must be 0 */
+	const char *pkcs11_engine;	/* path to PKCS#11 engine .so, optional */
+	const char *pkcs11_module;	/* path to PKCS#11 module .so, optional */
+	uintptr_t reserved2[6];		/* must be 0 */
 };
 
 struct libfsverity_metadata_callbacks {
lib/sign_digest.c +90 -6

132 lines not on this page · raw message

man/fsverity.1.md +21 -2
index e1007f5..f44aeb0 100644
@@ -169,8 +169,27 @@ Options accepted by **fsverity sign**:
 :   Same as for **fsverity digest**.
 
 **\-\-key**=*KEYFILE*
-:   Specifies the file that contains the private key, in PEM format.  This
-    option is required.
+:   Specifies the file that contains the private key, in PEM format.  If any
+    PKCS#11 options are used, it can be used instead to specify the key
+    identifier in the form of PKCS#11 URI.  This option is required when
+    private key is read from disk and optional when using a PKCS#11 token.
+
+**\-\-pkcs11-engine**=*SOFILE*
+:   Specifies the path to the OpenSSL engine library to be used, when a PKCS#11
+    cryptographic token is used instead of a private key file. Typically it
+    will be a path to the libp11 .so file.  This option is required when
+    **\-\-pkcs11-module** is used.
+
+    Note that this option is only supported with classical OpenSSL, and not
+    BoringSSL.
+
+**\-\-pkcs11-module**=*SOFILE*
+:   Specifies the path to the token-specific module library, when a PKCS#11
+    cryptographic token is used instead of a private key file.  This option is
+    required when **\-\-pkcs11-engine** is used.
+
+    Note that this option is only supported with classical OpenSSL, and not
+    BoringSSL.
 
 **\-\-out-descriptor**=*FILE*
 :   Same as for **fsverity digest**.
programs/cmd_sign.c +31 -0
index 81a4ddc..0d502c9 100644
@@ -34,6 +34,8 @@ static const struct option longopts[] = {
 	{"out-descriptor",  required_argument, NULL, OPT_OUT_DESCRIPTOR},
 	{"key",		    required_argument, NULL, OPT_KEY},
 	{"cert",	    required_argument, NULL, OPT_CERT},
+	{"pkcs11-engine",	    required_argument, NULL, OPT_PKCS11_ENGINE},
+	{"pkcs11-module",	    required_argument, NULL, OPT_PKCS11_MODULE},
 	{NULL, 0, NULL, 0}
 };
 
@@ -68,6 +70,12 @@ int fsverity_cmd_sign(const struct fsverity_command *cmd,
 			}
 			sig_params.keyfile = optarg;
 			break;
+		case OPT_PKCS11_ENGINE:
+			sig_params.pkcs11_engine = optarg;
+			break;
+		case OPT_PKCS11_MODULE:
+			sig_params.pkcs11_module = optarg;
+			break;
 		case OPT_CERT:
 			if (sig_params.certfile != NULL) {
 				error_msg("--cert can only be specified once");
@@ -86,12 +94,35 @@ int fsverity_cmd_sign(const struct fsverity_command *cmd,
 	if (argc != 2)
 		goto out_usage;
 
+#ifdef OPENSSL_IS_BORINGSSL
 	if (sig_params.keyfile == NULL) {
 		error_msg("Missing --key argument");
 		goto out_usage;
 	}
 	if (sig_params.certfile == NULL)
 		sig_params.certfile = sig_params.keyfile;
+#else
+	if (sig_params.keyfile == NULL && sig_params.pkcs11_engine == NULL &&
+	    sig_params.pkcs11_module == NULL) {
+		error_msg("Missing --key argument or a pair of --pkcs11-engine "
+			  "and --pkcs11-module");
+		goto out_usage;
+	}
+	if (sig_params.certfile == NULL) {
+		if (sig_params.keyfile == NULL) {
+			error_msg(
+			    "--cert must be specified when PKCS#11 is used");
+			goto out_usage;
+		}
+		sig_params.certfile = sig_params.keyfile;
+	}
+	if ((sig_params.pkcs11_engine == NULL) !=
+	    (sig_params.pkcs11_module == NULL)) {
+		error_msg("Both --pkcs11-engine and --pkcs11-module must be "
+			  "specified when used");
+		goto out_usage;
+	}
+#endif
 
 	if (!open_file(&file, argv[0], O_RDONLY, 0))
 		goto out_err;
programs/fsverity.c +3 -1
index f6aff3a..a4e8f5b 100644
@@ -58,7 +58,9 @@ 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 [--key=KEYFILE]\n"
+"               [--pkcs11-engine=PATH_TO_OPENSSL_ENGINE]\n"
+"               [--pkcs11-module=PATH_TO_OPENSSL_MODULE]\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 +2 -0
index fe24087..eb5ba33 100644
@@ -33,6 +33,8 @@ enum {
 	OPT_OUT_MERKLE_TREE,
 	OPT_SALT,
 	OPT_SIGNATURE,
+	OPT_PKCS11_ENGINE,
+	OPT_PKCS11_MODULE,
 };
 
 struct fsverity_command;
Signature · 1 line
2.30.2
maintainer
#1 lore raw
Quoted 8 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.

Sorry, I didn't notice that you had already sent out a new version of this patch. Is this version intended to address all my comments? Some of the comments I made don't seem to have been fully addressed.

- Eric

#2 lore raw
Quoted 3 lines · Eric Biggers

Sorry, I didn't notice that you had already sent out a new version of this patch. Is this version intended to address all my comments? Some of the comments I made don't seem to have been fully addressed.

Hi!

Yes, the patch was intended to address all of your previous comment.

I went over it to double check and noticed that I somehow left one OPENSSL_IS_BORINGSSL ifdef in programs/cmd_sign.c.

I will remove it in V3. As far as I can tell, all of your other comments are already addressed, unless I'm still missing something?

maintainer
#3 lore raw
Quoted 5 lines · Aleksander Adamowski
Quoted 3 lines · Eric Biggers

Sorry, I didn't notice that you had already sent out a new version of this patch. Is this version intended to address all my comments? Some of the comments I made don't seem to have been fully addressed.

Quoted 7 lines

Hi!

Yes, the patch was intended to address all of your previous comment.

I went over it to double check and noticed that I somehow left one OPENSSL_IS_BORINGSSL ifdef in programs/cmd_sign.c.

I will remove it in V3. As far as I can tell, all of your other comments are already addressed, unless I'm still missing something?

Regarding struct libfsverity_signature_params, I wrote "Please write a comment that clearly explains which parameters must be specified and when.".

Also I mentioned "The !OPENSSL_IS_BORINGSSL case no longer returns an error if sig_params->keyfile or sig_params->certfile is unset". That wasn't addressed for sig_params->certfile.

- Eric

#4 lore raw
Quoted 2 lines · Eric Biggers

Regarding struct libfsverity_signature_params, I wrote "Please write a comment that clearly explains which parameters must be specified and when.".

Got it. I assumed that the detailed explanation in the manpage covering the same parameters would be sufficient, as repeating it in struct comments would make the information redundant and require reformatting that part to multi-line comments.

I can add it to the struct comments, but this will mean I'll need to change them to multi-line comments (above each struct member) and add empty lines between members (following the same commenting style as in struct libfsverity_merkle_tree_params). Are you okay with that change?

Quoted 3 lines

Also I mentioned "The !OPENSSL_IS_BORINGSSL case no longer returns an error if sig_params->keyfile or sig_params->certfile is unset". That wasn't addressed for sig_params->certfile.

Ah, I see. In my patch V2, after your suggestion, there's a new NULL check for certfile in lib/sign_digest.c:87 that I intended as a replacement for the previous check in lib/sign_digest.c:337. I think it's a better place for that check, as it's in the place of actual use.

Do you want me to place that check back in the pre-check logic in libfsverity_sign_digest()?

maintainer
#5 lore raw
Quoted 9 lines · Aleksander Adamowski
Quoted 2 lines · Eric Biggers

Regarding struct libfsverity_signature_params, I wrote "Please write a comment that clearly explains which parameters must be specified and when.".

Got it. I assumed that the detailed explanation in the manpage covering the same parameters would be sufficient, as repeating it in struct comments would make the information redundant and require reformatting that part to multi-line comments.

Quoted 4 lines

I can add it to the struct comments, but this will mean I'll need to change them to multi-line comments (above each struct member) and add empty lines between members (following the same commenting style as in struct libfsverity_merkle_tree_params). Are you okay with that change?

The fsverity.1 man page documents the fsverity tool, whereas the comments in libfsverity.h document the interface to libfsverity. These are different things, so the documentation for one doesn't really apply to the other, unless they explicitly reference each other. (Which you can do if it would avoid redundancy. The point is, if the documentation is somewhere else, people actually need to be told where to find it.)

It's fine to reformat the comments and code if necessary.

Quoted 5 lines
Quoted 4 lines

Also I mentioned "The !OPENSSL_IS_BORINGSSL case no longer returns an error if sig_params->keyfile or sig_params->certfile is unset". That wasn't addressed for sig_params->certfile.

Quoted 7 lines

Ah, I see. In my patch V2, after your suggestion, there's a new NULL check for certfile in lib/sign_digest.c:87 that I intended as a replacement for the previous check in lib/sign_digest.c:337. I think it's a better place for that check, as it's in the place of actual use.

Do you want me to place that check back in the pre-check logic in libfsverity_sign_digest()?

Your patch has:

	if (!certfile) {
		libfsverity_error_msg("certfile must be specified");
	}

It needs to be:

	if (!certfile) {
		libfsverity_error_msg("certfile must be specified");
		return -EINVAL;
	}

- Eric

#6 lore raw
Quoted 1 line · Eric Biggers

It's fine to reformat the comments and code if necessary.

Will do.

Quoted 6 lines

It needs to be:

        if (!certfile) {
                libfsverity_error_msg("certfile must be specified");
                return -EINVAL;
        }

{facepalm}

Argh, will fix that in V4 !
How did I miss that. Thanks for catching it!