diff --git a/CMakeLists.txt b/CMakeLists.txt index 74e3684..9e3d58f 100644 --- a/CMakeLists.txt +++ b/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 diff --git a/man/zpcpkcs11.7 b/man/zpcpkcs11.7 new file mode 100644 index 0000000..2c53baf --- /dev/null +++ b/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). diff --git a/man/zpcpkcs11.7.md b/man/zpcpkcs11.7.md new file mode 100644 index 0000000..2287ad6 --- /dev/null +++ b/man/zpcpkcs11.7.md @@ -0,0 +1,229 @@ +% ZPCPKCS11(7) LIBZPC v2 +% +% 2026 + +# NAME + +`zpcpkcs11` - A PKCS#11 library providing hardware-backed key cryptographic +operations on IBM Z and IBM LinuxONE. + +# DESCRIPTION + +The `zpcpkcs11` library (`zpcpkcs11.so`) 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 `hbkzpc provider` +for OpenSSL (hbkzpcprovider(7)), targeting applications that consume +cryptographic services via PKCS#11 rather than OpenSSL directly. + +The library implements the full PKCS#11 v3.2 function list. Functions that are +not supported return `CKR_FUNCTION_NOT_SUPPORTED`. See section *Supported +Functions* for a complete listing. + +## Hardware-backed keys + +Hardware-backed keys (*HBK*) 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 (*CEX*) adapters or the IBM Secure Execution for Linux +ultravisor to securely store secret key material and securely export it to the +firmware. + +See hbkzpcprovider(7) for a detailed description of the protected-key +concept and the HBKZPC URI format used to reference these keys. + +## Token and slot model + +The library presents exactly one slot (slot ID `0`) containing one token +(label `ZPC`). The token is permanently present, hardware-backed, and +**read-only**: object creation, modification, and deletion are not supported. + +All keys exposed by the token are loaded at initialization time from the +configuration file. See zpcpkcs11.conf(5) for the configuration file format. + +## Session model + +The library supports an unlimited number of concurrent read-only sessions +(`CKF_SERIAL_SESSION`). Read-write sessions are accepted but behave +identically to read-only sessions because the token is write-protected. +Asynchronous sessions (`CKF_ASYNC_SESSION`) are not supported. + +## Login model + +The library accepts `C_Login` and `C_LoginUser` with user type `CKU_USER`. +Login as the security officer (`CKU_SO`) or any other user type returns +`CKR_USER_TYPE_INVALID`. 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. + +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. + +# SUPPORTED FUNCTIONS + +## Implemented functions + +The following functions are fully implemented: + +`C_Initialize`, `C_Finalize`, `C_GetInfo`, `C_GetFunctionList`, +`C_GetInterfaceList`, `C_GetInterface` +: Library lifecycle and introspection. + +`C_GetSlotList`, `C_GetSlotInfo`, `C_GetTokenInfo`, `C_GetMechanismList`, +`C_GetMechanismInfo` +: Slot, token, and mechanism introspection. + +`C_OpenSession`, `C_CloseSession`, `C_CloseAllSessions`, `C_GetSessionInfo`, +`C_SessionCancel` +: Session management. + +`C_Login`, `C_LoginUser`, `C_Logout` +: Login state management (PIN is not verified; only `CKU_USER` is supported). + +`C_FindObjectsInit`, `C_FindObjects`, `C_FindObjectsFinal` +: Object enumeration and search by template attributes. + +`C_GetObjectSize`, `C_GetAttributeValue` +: Object attribute retrieval. + +`C_SignInit`, `C_Sign`, `C_SignUpdate`, `C_SignFinal` +: One-shot and multi-part signing. + +`C_VerifyInit`, `C_Verify`, `C_VerifyUpdate`, `C_VerifyFinal` +: One-shot and multi-part signature verification. + +`C_VerifySignatureInit`, `C_VerifySignature`, `C_VerifySignatureUpdate`, +`C_VerifySignatureFinal` +: PKCS#11 v3.2 combined-signature verify operations. + +`C_GetOperationState`, `C_SetOperationState` +: Always return `CKR_STATE_UNSAVEABLE`. + +`C_GetFunctionStatus`, `C_CancelFunction` +: Always return `CKR_FUNCTION_NOT_PARALLEL`. + +## Unsupported functions + +All functions not listed above return `CKR_FUNCTION_NOT_SUPPORTED` or +`CKR_TOKEN_WRITE_PROTECTED` where applicable. This includes: encryption, +decryption, digesting, key generation, key wrapping/unwrapping, key +derivation, random number generation, and all message-based operation +variants. + +# SUPPORTED MECHANISMS + +The library registers the following PKCS#11 mechanisms, all supporting the +`CKF_SIGN` and `CKF_VERIFY` flags: + +| Mechanism | Key sizes (bits) | +|---|---| +| `CKM_ECDSA` | 256 – 521 | +| `CKM_ECDSA_SHA1` | 256 – 521 | +| `CKM_ECDSA_SHA224` | 256 – 521 | +| `CKM_ECDSA_SHA256` | 256 – 521 | +| `CKM_ECDSA_SHA384` | 256 – 521 | +| `CKM_ECDSA_SHA512` | 256 – 521 | +| `CKM_ECDSA_SHA3_224` | 256 – 521 | +| `CKM_ECDSA_SHA3_256` | 256 – 521 | +| `CKM_ECDSA_SHA3_384` | 256 – 521 | +| `CKM_ECDSA_SHA3_512` | 256 – 521 | +| `CKM_EDDSA` | 255 – 448 | + +All ECDSA mechanisms support `CKF_EC_OID`, `CKF_EC_F_P`, +`CKF_EC_UNCOMPRESS`, and `CKF_EC_COMPRESS`. `CKM_EDDSA` supports +`CKF_EC_OID`, `CKF_EC_F_P`, and `CKF_EC_COMPRESS`. + +## Mechanism parameter restrictions + +**`CKM_EDDSA`** +: The `CK_EDDSA_PARAMS` structure is optional. If provided, the following + restrictions apply; violating either returns `CKR_MECHANISM_PARAM_INVALID`: + + - `phFlag` must be `CK_FALSE`: pre-hash mode (HashEdDSA) is not supported. + - `ulContextDataLen` must be `0`: non-empty context data is not supported. + +## Supported ECC curves + +- **ECDSA**: prime256v1 (P-256), secp384r1 (P-384), secp521r1 (P-521) +- **EdDSA**: ED25519, ED448 + +# INITIALIZATION + +When `C_Initialize` 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, `CKR_FUNCTION_FAILED` is returned. + +`C_Initialize` requires `CKF_OS_LOCKING_OK` to be set in the flags of the +`CK_C_INITIALIZE_ARGS` structure when arguments are provided. +`CKF_LIBRARY_CANT_CREATE_OS_THREADS` is not supported and causes +`CKR_ARGUMENTS_BAD` to be returned. + +# USAGE + +To use `zpcpkcs11` with a PKCS#11-aware application, configure the +application to load `zpcpkcs11.so` as its PKCS#11 module. The exact +configuration method depends on the application. + +## p11-kit + +When using `p11-kit`, create a module configuration file: + + [p11-kit-module] + module: /path/to/zpcpkcs11.so + +## p11tool + +Keys available in the token can be enumerated using `p11tool`: + + $ 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 + ... + +# CONFIGURATION + +The library reads its key configuration from: + + /etc/zpcpkcs11/zpcpkcs11.conf + +The path can be overridden with the `ZPCPKCS11_CONFIG` environment variable. +See zpcpkcs11.conf(5) for the full configuration file format. + +# ENVIRONMENT + +**ZPCPKCS11_CONFIG** +: Overrides the default configuration file path. Ignored in privileged + processes (see *secure_getenv*(3)). + +# FILES + +`/etc/zpcpkcs11/zpcpkcs11.conf` +: Default key configuration file. + +`zpcpkcs11.so` +: The PKCS#11 shared library. + +# GLOSSARY + +CEX +: IBM Crypto Express + +CPACF +: CP Assist for Cryptographic Functions + +HBK +: hardware-backed key + +SEL +: IBM Secure Execution for Linux + +ZPC +: IBM Z protected key cryptography + +# SEE ALSO + +zpcpkcs11.conf(5), hbkzpcprovider(7), hbkzpcprovider.conf(5), zpckey(1). diff --git a/man/zpcpkcs11.conf.5 b/man/zpcpkcs11.conf.5 new file mode 100644 index 0000000..ad8ec16 --- /dev/null +++ b/man/zpcpkcs11.conf.5 @@ -0,0 +1,161 @@ +.\" 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.CONF" "5" "2026" "LIBZPC v2" "" +.hy +.SH NAME +.PP +zpcpkcs11.conf - Configuration file for the \f[V]zpcpkcs11\f[R] PKCS#11 +library +.SH DESCRIPTION +.PP +This page documents the format of the configuration file read by the +\f[V]zpcpkcs11\f[R] PKCS#11 library on initialization. +The configuration file maps PKCS#11 key labels to OpenSSL URIs that +reference the corresponding protected-key origin files. +Each entry becomes a PKCS#11 object accessible to applications that load +\f[V]zpcpkcs11.so\f[R] as their PKCS#11 provider. +.SH FILE LOCATION +.PP +The default configuration file path is: +.IP +.nf +\f[C] +/etc/zpcpkcs11/zpcpkcs11.conf +\f[R] +.fi +.PP +The path can be overridden by setting the environment variable +\f[B]ZPCPKCS11_CONFIG\f[R] to an alternative file path. +The environment variable is read using \f[I]secure_getenv\f[R](3), so it +is ignored in set-user-ID and set-group-ID programs. +.SH FILE FORMAT +.PP +The configuration file is a plain-text file. +Each non-empty, non-comment line specifies one key entry with the +following syntax: +.IP +.nf +\f[C] +