Add support for importing TPM2 keys with PKCS11 vendor attributes

- Add support for importing TPM2 keys (as persistent handle or key objects) using PKCS11 vendor-specific attributes
- Add a new CLI tool: key_import
- Add integration test
- Add docs/KEY_IMPORT_TOOL.md

Signed-off-by: wenxin.leong <[email protected]>

Makefile-integration.am

@@ -10,15 +10,17 @@ integration_scripts = \
     test/integration/pkcs11-javarunner.sh.java \
     test/integration/nss-tests.sh \
     test/integration/ptool-link.sh.nosetup \
-    test/integration/python-pkcs11.sh
+    test/integration/python-pkcs11.sh \
+    test/integration/key_import-link.sh.nosetup
 
 # Note that -fapi.sh.fapi is symlinked to .sh.nosetup
 # If we'd use the .fapi extension then .nosetup and .fapi overwrite each others .log
 # thus we use -fapi.sh.fapi as suffix.
 if HAVE_FAPI
 integration_scripts += \
     test/integration/p11-tool-fapi.sh.fapi \
-    test/integration/pkcs11-tool-init-fapi.sh.fapi
+    test/integration/pkcs11-tool-init-fapi.sh.fapi \
+    test/integration/key_import-link-fapi.sh.fapi
 endif
 
 EXTRA_DIST += \

Makefile.am

@@ -72,6 +72,16 @@ endif
 
 AM_DISTCHECK_CONFIGURE_FLAGS = --with-p11kitconfigdir='$$(datarootdir)/p11kitconfigdir' --with-p11kitmoduledir='$$(libdir)'
 
+# The key_import tool
+bin_PROGRAMS = tools/key_import/key_import
+if ENABLE_ASAN
+  tools_key_import_key_import_LDFLAGS = $(AM_LDFLAGS) -shared-libasan
+else
+  tools_key_import_key_import_LDFLAGS = $(AM_LDFLAGS)
+endif
+tools_key_import_key_import_LDADD = $(libtpm2_pkcs11)
+tools_key_import_key_import_SOURCES = tools/key_import/import.c
+
 #
 # Due to limitations in how cmocka works, we build a separate library here so we
 # can have a PKCS11 shared object with undefined calls into the rest of the lib
@@ -113,8 +123,8 @@ AM_TESTS_ENVIRONMENT = \
     PYTHON_INTERPRETER=@PYTHON_INTERPRETER@ \
     TEST_FUNC_LIB=$(srcdir)/test/integration/scripts/int-test-funcs.sh \
     TEST_FIXTURES=$(abs_top_srcdir)/test/integration/fixtures \
-    PATH=$(abs_top_srcdir)/tools:./src:$(PATH) \
-    PYTHONPATH=$(abs_top_srcdir)/tools:$(PYTHONPATH) \
+    PATH=$(abs_top_srcdir)/tools/tpm2_ptool:$(abs_builddir)/tools/key_import:./src:$(PATH) \
+    PYTHONPATH=$(abs_top_srcdir)/tools/tpm2_ptool:$(PYTHONPATH) \
     TPM2_PKCS11_MODULE=$(abs_builddir)/src/.libs/libtpm2_pkcs11.so \
     TEST_JAVA_ROOT=$(JAVAROOT) \
     PACKAGE_URL=$(PACKAGE_URL) \

docs/KEY_IMPORT_TOOL.md

@@ -0,0 +1,14 @@
+# The key_import Tool
+
+The `key_import` tool in this project is a C program that serves as an example for importing TPM keys into a tpm2-pkcs11 token. The key import mechanism uses PKCS #11 vendor-specific attributes and works with both FAPI and ESYSDB backends.
+
+Supported modes:
+- Key to be imported: Ordinary TPM key with or without an auth value.
+- Key Import Formats: Keys can be imported as persistent handle or TSS key objects obtained from `tpm2 create` (`TPM2B_PUBLIC` and `TPM2B_PRIVATE` blobs).
+    - If key objects are used, the associated parent key must be the same primary key used for PKCS#11 token initialization. Parent keys with or without an auth value are supported.
+
+The PKCS #11 vendor-specific attributes used during the key import procedure are:
+- Persistent Handle: `CKA_TPM2_PERSISTENT_HANDLE` and `CKA_TPM2_OBJAUTH`.
+- TSS Key Objects: `CKA_TPM2_PUB_BLOB`, `CKA_TPM2_PRIV_BLOB`, and `CKA_TPM2_OBJAUTH`.
+
+For complete examples, please refer to `test/integration/key_import-link.sh.nosetup`.

src/lib/attrs.c

@@ -167,10 +167,12 @@ static attr_handler2 attr_handlers[] = {
     ADD_ATTR_HANDLER(CKA_WRAP_TEMPLATE, TYPE_BYTE_TEMP_SEQ),
     ADD_ATTR_HANDLER(CKA_UNWRAP_TEMPLATE, TYPE_BYTE_TEMP_SEQ),
     ADD_ATTR_HANDLER(CKA_ALLOWED_MECHANISMS, TYPE_BYTE_INT_SEQ),
+    ADD_ATTR_HANDLER(CKA_TPM2_OBJAUTH, TYPE_BYTE_HEX_STR),
     ADD_ATTR_HANDLER(CKA_TPM2_OBJAUTH_ENC, TYPE_BYTE_HEX_STR),
     ADD_ATTR_HANDLER(CKA_TPM2_PUB_BLOB, TYPE_BYTE_HEX_STR),
     ADD_ATTR_HANDLER(CKA_TPM2_PRIV_BLOB, TYPE_BYTE_HEX_STR),
     ADD_ATTR_HANDLER(CKA_TPM2_ENC_BLOB, TYPE_BYTE_HEX_STR),
+    ADD_ATTR_HANDLER(CKA_TPM2_PERSISTENT_HANDLE, TYPE_BYTE_INT),
 };
 
 static attr_handler2 default_handler = { .memtype = 0, .name="UNKNOWN" };

src/lib/attrs.h

@@ -10,11 +10,13 @@
 /*
  * We will allow these to be accessed, but the values are not stable
  */
-#define CKA_VENDOR_TPM2_DEFINED 0x0F000000UL
-#define CKA_TPM2_OBJAUTH_ENC (CKA_VENDOR_DEFINED|CKA_VENDOR_TPM2_DEFINED|0x1UL)
-#define CKA_TPM2_PUB_BLOB    (CKA_VENDOR_DEFINED|CKA_VENDOR_TPM2_DEFINED|0x2UL)
-#define CKA_TPM2_PRIV_BLOB   (CKA_VENDOR_DEFINED|CKA_VENDOR_TPM2_DEFINED|0x3UL)
-#define CKA_TPM2_ENC_BLOB    (CKA_VENDOR_DEFINED|CKA_VENDOR_TPM2_DEFINED|0x4UL)
+#define CKA_VENDOR_TPM2_DEFINED     0x0F000000UL
+#define CKA_TPM2_OBJAUTH_ENC        (CKA_VENDOR_DEFINED|CKA_VENDOR_TPM2_DEFINED|0x1UL)
+#define CKA_TPM2_PUB_BLOB           (CKA_VENDOR_DEFINED|CKA_VENDOR_TPM2_DEFINED|0x2UL)
+#define CKA_TPM2_PRIV_BLOB          (CKA_VENDOR_DEFINED|CKA_VENDOR_TPM2_DEFINED|0x3UL)
+#define CKA_TPM2_ENC_BLOB           (CKA_VENDOR_DEFINED|CKA_VENDOR_TPM2_DEFINED|0x4UL)
+#define CKA_TPM2_OBJAUTH            (CKA_VENDOR_DEFINED|CKA_VENDOR_TPM2_DEFINED|0x5UL)
+#define CKA_TPM2_PERSISTENT_HANDLE  (CKA_VENDOR_DEFINED|CKA_VENDOR_TPM2_DEFINED|0x6UL)
 
 /* Invalid values for error detection */
 #define CK_OBJECT_CLASS_BAD (~(CK_OBJECT_CLASS)0)