Add a PKCS#11 interface for libzpc #50
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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). |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
typo: zpcpkcs11