Add a PKCS#11 interface for libzpc

CMakeLists.txt

@@ -387,6 +387,63 @@ install(
     DESTINATION ${CMAKE_INSTALL_MANDIR}/man1
 )
 
+###########################################################
+# zpckcs11
+
+if (${CMAKE_SYSTEM_PROCESSOR} STREQUAL s390x)
+
+set(ZPCPKCS11_SOURCES
+    src/pkcs11/pkcs11.c
+    src/pkcs11/openssl.c
+    src/pkcs11/config.c
+    src/pkcs11/utils.c
+    src/pkcs11/object.c
+    src/pkcs11/session.c
+    src/pkcs11/signature.c
+)
+
+add_library(zpcpkcs11 SHARED ${ZPCPKCS11_SOURCES})
+set_target_properties(zpcpkcs11
+    PROPERTIES
+    PREFIX                ""
+    C_VISIBILITY_PRESET   default
+    LINK_FLAGS            "-Wl,--version-script=${CMAKE_SOURCE_DIR}/zpcpkcs11.map"
+)
+target_include_directories(zpcpkcs11 PRIVATE src/pkcs11 ${OPENSSL_INCLUDE_DIR})
+target_link_libraries(zpcpkcs11 PRIVATE OpenSSL::Crypto)
+target_compile_definitions(
+    zpcpkcs11 PRIVATE
+    ZPCPKCS11_VERSION_MAJOR=${ZPC_VERSION_MAJOR}
+    ZPCPKCS11_VERSION_MINOR=${ZPC_VERSION_MINOR}
+    ZPCPKCS11_VERSION_PATCH=${ZPC_VERSION_PATCH}
+)
+target_include_directories(zpcpkcs11 PRIVATE src/pkcs11)
+
+if(PkgConfig_FOUND)
+    pkg_get_variable(P11KIT_MODULEDIR p11-kit-1 p11_module_path)
+endif()
+if(NOT P11KIT_MODULEDIR)
+    set(P11KIT_MODULEDIR "${CMAKE_INSTALL_LIBDIR}/pkcs11")
+endif()
+message(STATUS "PKCS#11 module install directory: ${P11KIT_MODULEDIR}")
+
+install(
+    TARGETS zpcpkcs11
+    LIBRARY DESTINATION ${P11KIT_MODULEDIR}
+)
+
+install(
+    FILES ${CMAKE_SOURCE_DIR}/man/zpcpkcs11.conf.5
+    DESTINATION ${CMAKE_INSTALL_MANDIR}/man5
+)
+
+install(
+    FILES ${CMAKE_SOURCE_DIR}/man/zpcpkcs11.7
+    DESTINATION ${CMAKE_INSTALL_MANDIR}/man7
+)
+
+endif() # CMAKE_SYSTEM_PROCESSOR == s390x
+
 ###########################################################
 # Test
 

man/zpcpkcs11.7

@@ -0,0 +1,313 @@
+'\" t
+.\" Automatically generated by Pandoc 3.1.3
+.\"
+.\" Define V font for inline verbatim, using C font in formats
+.\" that render this, and otherwise B font.
+.ie "\f[CB]x\f[]"x" \{\
+. ftr V B
+. ftr VI BI
+. ftr VB B
+. ftr VBI BI
+.\}
+.el \{\
+. ftr V CR
+. ftr VI CI
+. ftr VB CB
+. ftr VBI CBI
+.\}
+.TH "ZPCPKCS11" "7" "2026" "LIBZPC v2" ""
+.hy
+.SH NAME
+.PP
+\f[V]zpcpkcs11\f[R] - A PKCS#11 library providing hardware-backed key
+cryptographic operations on IBM Z and IBM LinuxONE.
+.SH DESCRIPTION
+.PP
+The \f[V]zpcpkcs11\f[R] library (\f[V]zpcpkcs11.so\f[R]) is a PKCS#11
+v3.2 provider that exposes IBM Z protected-key cryptographic operations
+through the standard PKCS#11 Cryptoki API.
+It is the PKCS#11 counterpart to the \f[V]hbkzpc provider\f[R] for
+OpenSSL (hbkzpcprovider(7)), targeting applications that consume
+cryptographic services via PKCS#11 rather than OpenSSL directly.
+.PP
+The library implements the full PKCS#11 v3.2 function list.
+Functions that are not supported return
+\f[V]CKR_FUNCTION_NOT_SUPPORTED\f[R].
+See section \f[I]Supported Functions\f[R] for a complete listing.
+.SS Hardware-backed keys
+.PP
+Hardware-backed keys (\f[I]HBK\f[R]) are a generic concept where the
+secret information of cryptographic keys is never exposed to main
+memory, but cryptographic operations with such keys are still possible.
+Instead of the raw secret key information, opaque key objects are
+exposed to applications.
+The IBM Z platform uses IBM Crypto Express (\f[I]CEX\f[R]) adapters or
+the IBM Secure Execution for Linux ultravisor to securely store secret
+key material and securely export it to the firmware.
+.PP
+See hbkzpcprovider(7) for a detailed description of the protected-key
+concept and the HBKZPC URI format used to reference these keys.
+.SS Token and slot model
+.PP
+The library presents exactly one slot (slot ID \f[V]0\f[R]) containing
+one token (label \f[V]ZPC\f[R]).
+The token is permanently present, hardware-backed, and
+\f[B]read-only\f[R]: object creation, modification, and deletion are not
+supported.
+.PP
+All keys exposed by the token are loaded at initialization time from the
+configuration file.
+See zpcpkcs11.conf(5) for the configuration file format.
+.SS Session model
+.PP
+The library supports an unlimited number of concurrent read-only
+sessions (\f[V]CKF_SERIAL_SESSION\f[R]).
+Read-write sessions are accepted but behave identically to read-only
+sessions because the token is write-protected.
+Asynchronous sessions (\f[V]CKF_ASYNC_SESSION\f[R]) are not supported.
+.SS Login model
+.PP
+The library accepts \f[V]C_Login\f[R] and \f[V]C_LoginUser\f[R] with
+user type \f[V]CKU_USER\f[R].
+Login as the security officer (\f[V]CKU_SO\f[R]) or any other user type
+returns \f[V]CKR_USER_TYPE_INVALID\f[R].
+The PIN value is ignored.
+The library does not enforce login for any operation; the login state is
+maintained solely to satisfy the PKCS#11 state machine expected by
+callers.
+.PP
+PIN protection is not meaningful in this context: the protected key
+origins configured in zpcpkcs11.conf(5) are not access-restricted.
+Retrievable secrets and other protected key origins can be transformed
+into protected keys by any application via the PKEY ioctl interface,
+without any additional access control.
+.SH SUPPORTED FUNCTIONS
+.SS Implemented functions
+.PP
+The following functions are fully implemented:
+.PP
+\f[V]C_Initialize\f[R], \f[V]C_Finalize\f[R], \f[V]C_GetInfo\f[R],
+\f[V]C_GetFunctionList\f[R], \f[V]C_GetInterfaceList\f[R],
+\f[V]C_GetInterface\f[R] : Library lifecycle and introspection.
+.PP
+\f[V]C_GetSlotList\f[R], \f[V]C_GetSlotInfo\f[R],
+\f[V]C_GetTokenInfo\f[R], \f[V]C_GetMechanismList\f[R],
+\f[V]C_GetMechanismInfo\f[R] : Slot, token, and mechanism introspection.
+.PP
+\f[V]C_OpenSession\f[R], \f[V]C_CloseSession\f[R],
+\f[V]C_CloseAllSessions\f[R], \f[V]C_GetSessionInfo\f[R],
+\f[V]C_SessionCancel\f[R] : Session management.
+.TP
+\f[V]C_Login\f[R], \f[V]C_LoginUser\f[R], \f[V]C_Logout\f[R]
+Login state management (PIN is not verified; only \f[V]CKU_USER\f[R] is
+supported).
+.TP
+\f[V]C_FindObjectsInit\f[R], \f[V]C_FindObjects\f[R], \f[V]C_FindObjectsFinal\f[R]
+Object enumeration and search by template attributes.
+.TP
+\f[V]C_GetObjectSize\f[R], \f[V]C_GetAttributeValue\f[R]
+Object attribute retrieval.
+.TP
+\f[V]C_SignInit\f[R], \f[V]C_Sign\f[R], \f[V]C_SignUpdate\f[R], \f[V]C_SignFinal\f[R]
+One-shot and multi-part signing.
+.TP
+\f[V]C_VerifyInit\f[R], \f[V]C_Verify\f[R], \f[V]C_VerifyUpdate\f[R], \f[V]C_VerifyFinal\f[R]
+One-shot and multi-part signature verification.
+.PP
+\f[V]C_VerifySignatureInit\f[R], \f[V]C_VerifySignature\f[R],
+\f[V]C_VerifySignatureUpdate\f[R], \f[V]C_VerifySignatureFinal\f[R] :
+PKCS#11 v3.2 combined-signature verify operations.
+.TP
+\f[V]C_GetOperationState\f[R], \f[V]C_SetOperationState\f[R]
+Always return \f[V]CKR_STATE_UNSAVEABLE\f[R].
+.TP
+\f[V]C_GetFunctionStatus\f[R], \f[V]C_CancelFunction\f[R]
+Always return \f[V]CKR_FUNCTION_NOT_PARALLEL\f[R].
+.SS Unsupported functions
+.PP
+All functions not listed above return
+\f[V]CKR_FUNCTION_NOT_SUPPORTED\f[R] or
+\f[V]CKR_TOKEN_WRITE_PROTECTED\f[R] where applicable.
+This includes: encryption, decryption, digesting, key generation, key
+wrapping/unwrapping, key derivation, random number generation, and all
+message-based operation variants.
+.SH SUPPORTED MECHANISMS
+.PP
+The library registers the following PKCS#11 mechanisms, all supporting
+the \f[V]CKF_SIGN\f[R] and \f[V]CKF_VERIFY\f[R] flags:
+.PP
+.TS
+tab(@);
+l l.
+T{
+Mechanism
+T}@T{
+Key sizes (bits)
+T}
+_
+T{
+\f[V]CKM_ECDSA\f[R]
+T}@T{
+256 \[en] 521
+T}
+T{
+\f[V]CKM_ECDSA_SHA1\f[R]
+T}@T{
+256 \[en] 521
+T}
+T{
+\f[V]CKM_ECDSA_SHA224\f[R]
+T}@T{
+256 \[en] 521
+T}
+T{
+\f[V]CKM_ECDSA_SHA256\f[R]
+T}@T{
+256 \[en] 521
+T}
+T{
+\f[V]CKM_ECDSA_SHA384\f[R]
+T}@T{
+256 \[en] 521
+T}
+T{
+\f[V]CKM_ECDSA_SHA512\f[R]
+T}@T{
+256 \[en] 521
+T}
+T{
+\f[V]CKM_ECDSA_SHA3_224\f[R]
+T}@T{
+256 \[en] 521
+T}
+T{
+\f[V]CKM_ECDSA_SHA3_256\f[R]
+T}@T{
+256 \[en] 521
+T}
+T{
+\f[V]CKM_ECDSA_SHA3_384\f[R]
+T}@T{
+256 \[en] 521
+T}
+T{
+\f[V]CKM_ECDSA_SHA3_512\f[R]
+T}@T{
+256 \[en] 521
+T}
+T{
+\f[V]CKM_EDDSA\f[R]
+T}@T{
+255 \[en] 448
+T}
+.TE
+.PP
+All ECDSA mechanisms support \f[V]CKF_EC_OID\f[R], \f[V]CKF_EC_F_P\f[R],
+\f[V]CKF_EC_UNCOMPRESS\f[R], and \f[V]CKF_EC_COMPRESS\f[R].
+\f[V]CKM_EDDSA\f[R] supports \f[V]CKF_EC_OID\f[R], \f[V]CKF_EC_F_P\f[R],
+and \f[V]CKF_EC_COMPRESS\f[R].
+.SS Mechanism parameter restrictions
+.TP
+\f[B]\f[VB]CKM_EDDSA\f[B]\f[R]
+The \f[V]CK_EDDSA_PARAMS\f[R] structure is optional.
+If provided, the following restrictions apply; violating either returns
+\f[V]CKR_MECHANISM_PARAM_INVALID\f[R]:
+.RS
+.IP \[bu] 2
+\f[V]phFlag\f[R] must be \f[V]CK_FALSE\f[R]: pre-hash mode (HashEdDSA)
+is not supported.
+.IP \[bu] 2
+\f[V]ulContextDataLen\f[R] must be \f[V]0\f[R]: non-empty context data
+is not supported.
+.RE
+.SS Supported ECC curves
+.IP \[bu] 2
+\f[B]ECDSA\f[R]: prime256v1 (P-256), secp384r1 (P-384), secp521r1
+(P-521)
+.IP \[bu] 2
+\f[B]EdDSA\f[R]: ED25519, ED448
+.SH INITIALIZATION
+.PP
+When \f[V]C_Initialize\f[R] is called, the library loads and processes
+the configuration file (see zpcpkcs11.conf(5)), creating PKCS#11 key
+objects for each valid entry.
+If initialization fails, \f[V]CKR_FUNCTION_FAILED\f[R] is returned.
+.PP
+\f[V]C_Initialize\f[R] requires \f[V]CKF_OS_LOCKING_OK\f[R] to be set in
+the flags of the \f[V]CK_C_INITIALIZE_ARGS\f[R] structure when arguments
+are provided.
+\f[V]CKF_LIBRARY_CANT_CREATE_OS_THREADS\f[R] is not supported and causes
+\f[V]CKR_ARGUMENTS_BAD\f[R] to be returned.
+.SH USAGE
+.PP
+To use \f[V]zpcpkcs11\f[R] with a PKCS#11-aware application, configure
+the application to load \f[V]zpcpkcs11.so\f[R] as its PKCS#11 module.
+The exact configuration method depends on the application.
+.SS p11-kit
+.PP
+When using \f[V]p11-kit\f[R], create a module configuration file:
+.IP
+.nf
+\f[C]
+[p11-kit-module]
+module: /path/to/zpcpkcs11.so
+\f[R]
+.fi
+.SS p11tool
+.PP
+Keys available in the token can be enumerated using \f[V]p11tool\f[R]:
+.IP
+.nf
+\f[C]
+$ p11tool --provider /path/to/zpcpkcs11.so --list-all
+Object 0:
+    URL: pkcs11:model=ZPC;manufacturer=IBM;serial=01;token=ZPC;...
+    Type: Private Key (EC/ECDSA)
+    Label: my-signing-key
+    ...
+\f[R]
+.fi
+.SH CONFIGURATION
+.PP
+The library reads its key configuration from:
+.IP
+.nf
+\f[C]
+/etc/zpcpkcs11/zpcpkcs11.conf
+\f[R]
+.fi
+.PP
+The path can be overridden with the \f[V]ZPCPKCS11_CONFIG\f[R]
+environment variable.
+See zpcpkcs11.conf(5) for the full configuration file format.
+.SH ENVIRONMENT
+.TP
+\f[B]ZPCPKCS11_CONFIG\f[R]
+Overrides the default configuration file path.
+Ignored in privileged processes (see \f[I]secure_getenv\f[R](3)).
+.SH FILES
+.TP
+\f[V]/etc/zpcpkcs11/zpcpkcs11.conf\f[R]
+Default key configuration file.
+.TP
+\f[V]zpcpkcs11.so\f[R]
+The PKCS#11 shared library.
+.SH GLOSSARY
+.TP
+CEX
+IBM Crypto Express
+.TP
+CPACF
+CP Assist for Cryptographic Functions
+.TP
+HBK
+hardware-backed key
+.TP
+SEL
+IBM Secure Execution for Linux
+.TP
+ZPC
+IBM Z protected key cryptography
+.SH SEE ALSO
+.PP
+zpcpkcs11.conf(5), hbkzpcprovider(7), hbkzpcprovider.conf(5), zpckey(1).