diff --git a/.travis.yml b/.travis.yml index f029fcc3..4e825062 100644 --- a/.travis.yml +++ b/.travis.yml @@ -12,7 +12,7 @@ compiler: before_install: - sudo apt-get update -qq - - sudo apt-get install -y cmake pandoc clang-format libjson-c-dev libssl-dev + - sudo apt-get install -y cmake clang-format libjson-c-dev libssl-dev script: - set -o pipefail diff --git a/CMakeLists.txt b/CMakeLists.txt index 7cf64453..74e36846 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -327,12 +327,12 @@ install( ) install( - FILES ${CMAKE_BINARY_DIR}/hbkzpcprovider.conf.5 + FILES ${CMAKE_SOURCE_DIR}/man/hbkzpcprovider.conf.5 DESTINATION ${CMAKE_INSTALL_MANDIR}/man5 ) install( - FILES ${CMAKE_BINARY_DIR}/hbkzpcprovider.7 + FILES ${CMAKE_SOURCE_DIR}/man/hbkzpcprovider.7 DESTINATION ${CMAKE_INSTALL_MANDIR}/man7 ) @@ -383,7 +383,7 @@ install( ) install( - FILES ${CMAKE_BINARY_DIR}/zpckey.1 + FILES ${CMAKE_SOURCE_DIR}/man/zpckey.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1 ) @@ -751,8 +751,9 @@ find_program(PANDOC pandoc) if (PANDOC) add_custom_target( - man ALL - COMMAND ${CMAKE_SOURCE_DIR}/conv_man.sh "${CMAKE_SOURCE_DIR}/man" "${CMAKE_BINARY_DIR}" + update-man ALL + COMMAND ${CMAKE_SOURCE_DIR}/misc/update-man ${CMAKE_SOURCE_DIR}/man/ ${CMAKE_SOURCE_DIR}/man/ + VERBATIM ) endif () # PANDOC_FOUND diff --git a/README.md b/README.md index 02d569bb..632f3af9 100644 --- a/README.md +++ b/README.md @@ -39,9 +39,6 @@ Additional prerequisites for building the internal test program: - libjson-c devel package >= 0.13 - internet connection -Additional prerequisites for building the man-pages: -- pandoc - Additional prerequisites for building the internal html and latex doc: - doxygen >= 1.8.17 - latex, bibtex @@ -74,6 +71,22 @@ Custom compile options can also be passed to `cmake` via the `CFLAGS` and `CXXFLAGS` environment variables in the usual way. +Man-Pages +--------- + +The man-pages are generated from the related markdown sources. To +update one of the man-pages, make the changes to the markdown-file, +and use the `update-man` build target to update the pre-built man-page +files (troff format). After updating the pre-built man-pages, commit +them in a separate patch to the repository. + + # make changes to man/.
.md + cmake --build --target update-man # or + make -C build update-man + git add man/*.[157] + git commit -s -m "man: Update pre-built man-pages" + + Cross-Building for s390x architecture ------------------------------------- diff --git a/libzpc.spec b/libzpc.spec index ae30f1d0..3700e375 100644 --- a/libzpc.spec +++ b/libzpc.spec @@ -14,7 +14,6 @@ BuildRequires: gcc BuildRequires: g++ BuildRequires: make BuildRequires: clang-tools-extra -BuildRequires: pandoc BuildRequires: json-c-devel BuildRequires: openssl-devel >= 3.0.7 diff --git a/man/hbkzpcprovider.7 b/man/hbkzpcprovider.7 new file mode 100644 index 00000000..78ba542d --- /dev/null +++ b/man/hbkzpcprovider.7 @@ -0,0 +1,176 @@ +.\" Automatically generated by Pandoc 3.7.0.2 +.\" +.TH "HBKZPCPROVIDER" "7" "2026" "LIBZPC v2" +.SH NAME +\f[CR]hbkzpc provider\f[R] \- An OpenSSL provider that provides an +interface to the hardware\-backed key cryptographic operations, +available on IBM Z and IBM LinuxONE. +.SH DESCRIPTION +IBM Z and IBM LinuxONE systems offer several types of hardware assists +with different features, including the CP Assist for Cryptographic +Functions (\f[I]CPACF\f[R]) and the IBM Crypto Express (\f[I]CEX\f[R]) +features. +.PP +The \f[CR]hbkzpc provider\f[R] enables applications using the OpenSSL +crypto library API to exploit the protected key cryptography +(\f[I]ZPC\f[R]) functions, provided by CPACF on IBM Z and IBM LinuxONE. +.PP +To use the \f[CR]hbkzpc provider\f[R] via the OpenSSL crypto library +API, it must be referenced in the OpenSSL configuration. +For more details, see hbkzpcprovider.conf(5). +.SS Hardware\-backed keys +Hardware\-backed keys (\f[I]HBK\f[R]) are a generic concept, where the +secret information of cryptographic keys is never exposed to the main +memory, but cryptographic operations with such keys are still possible. +Instead of the raw secret key information, opaque key objects are +exposed to the applications. +The internals of these opaque key objects (key slot reference, wrapped +key blob, etc.) +depends on the concrete implementation of the generic concept. +It is essential, that the knowledge of the opaque key object does not +expose any information about the real secret information of the key. +.SS IBM Z protected key cryptography +The IBM Z protected key cryptography is the implementation of the +generic hardware\-backed key concept on IBM Z and IBM LinuxONE. +The platform uses IBM Crypto Express (\f[I]CEX\f[R]) adapters (or often +called: feature) or the IBM Secure Execution for Linux ultravisor to +securely store secret key material and securely export them to the +firmware. +The \f[CR]hbkzpc provider\f[R] can handle opaque key objects (protected +key origins), which describe and reference these secure keys. +.PP +ZPC provides many cryptographic functions with protected keys. +The \f[CR]hbkzpc provider\f[R] supports ECDSA/EdDSA sign/verify +operations for a list of ECC\-curves. +See section \f[I]Provider functions\f[R] for more details. +.SS Protected key origins +A protected key origin for the \f[CR]hbkzpc provider\f[R] is used to +internally export the referenced secure key to the firmware. +While the resulting protected keys are volatile and can become invalid +at any time, the protected key origins are persistent and can be stored +without exposing any secret information. +.PP +A protected key origin is specified by a HBKZPC unified resource +identifier (URI). +These URIs can be encoded to protected key origin files. +The \f[CR]hbkzpc provider\f[R] can handle either URIs directly or URIs +which are encoded and stored in files (DER or PEM). +See section \f[I]URI\f[R] for more details. +.PP +The \f[CR]zpckey\f[R] tool supports composing such protected key +origins. +See zpckey(1) for more details. +.PP +The \f[CR]hbkzpc provider\f[R] supports protected key origins for +retrievable secrets in IBM Secure Execution for Linux (SEL) ultravisor. +.SS Provider functions +The \f[CR]hbkzpc provider\f[R] plugs into the OpenSSL provider API and +provides the following functions: +.IP \(bu 2 +signature\-algorithms for ECDSA and EdDSA +.IP \(bu 2 +key\-manager for provider\-specific keys +.IP \(bu 2 +store\-loader for provider\-specific key URIs +.IP \(bu 2 +decoder for DER/PEM encoded provider\-specific key URI files +.SS Supported ECC curves +The \f[CR]hbkzpc provider\f[R] supports the following ECC\-curves for +ECDSA and EdDSA respectively: +.IP \(bu 2 +prime256v1 +.IP \(bu 2 +secp384r1 +.IP \(bu 2 +secp521r1 +.IP \(bu 2 +ED25519 +.IP \(bu 2 +ED448 +.SH URI +The HBKZPC unified resource identifier (URI) specifies all information +of the protected key origins, which is required for the provider to +derive the related protected key. +The URI has the following syntax (ABNF representation): +.IP +.EX +hbkzpc\-URI = \(dqhbkzpc:\(dq hbkzpc\-param +hbkzpc\-param = [ hbkzpc\-pattr *(\(dq;\(dq hbkzpc\-pattr) ] + +hbkzpc\-pattr = origin\-type / origin\-alg / origin\-blob / + origin\-pubkey / comment + +origin\-type = \(dqorigin\-type\(dq \(dq=\(dq *pchar +origin\-alg = \(dqorigin\-alg\(dq \(dq=\(dq oid / *(pchar) +origin\-blob = \(dqorigin\-blob\(dq \(dq=\(dq hex\-string +origin\-pubkey = \(dqorigin\-pubkey\(dq \(dq=\(dq hex\-string +comment = \(dqcomment\(dq \(dq=\(dq *pchar\-pct + +oid = DIGIT *(\(dq.\(dq DIGIT) + +hex\-byte = 2*HEXDIG +hex\-string = [ hex\-byte *(hex\-byte) ] + +pchar\-pct = pchar / pct\-encoded +pchar = unreserved / res\-avail +res\-avail = \(dq:\(dq / \(dq[\(dq / \(dq]\(dq / \(dq\(at\(dq / \(dq!\(dq / \(dq$\(dq / + \(dq\(aq\(dq / \(dq(\(dq / \(dq)\(dq / \(dq*\(dq / \(dq+\(dq / \(dq,\(dq / \(dq=\(dq + +pct\-encoded = [ \(dq%\(dq 2*HEXDIG ] +unreserved = ALPHA / DIGIT / \(dq\-\(dq / \(dq.\(dq / \(dq_\(dq / \(dq\(ti\(dq +.EE +.SH ENCODING +The URI can also be encoded and stored to a file. +Supported encoding formats are DER and PEM. +.SS DER encoding +For the DER encoding, the HBKZPC URI is encapsulated with a ASN.1 +structure. +Each DER file contains one structure in binary form. +The structure has the following syntax: +.IP +.EX +HardwareBackedKeyZPCFormat DEFINITIONS ::= BEGIN + HBKZPC ::= SEQUENCE { + desc [0] EXPLICIT VisibleString, + uri [1] EXPLICIT UTF8String, + } +END +.EE +.PP +The DER decoder of the \f[CR]hbkzpc provider\f[R] only handles DER files +with a description (\f[I]desc\f[R]) of \f[I]HBKZPC Provider URI +v1.0\f[R]. +.SS PEM encoding +The PEM encoding is a base64\-encoded DER structure. +The encoded data is surrounded by a start and end tag. +A PEM encoded file has the following form: +.IP +.EX +\-\-\-\-\-BEGIN HARDWARE BACKED KEY ZPC\-\-\-\-\- +[... ...] +\-\-\-\-\-END HARDWARE BACKED KEY ZPC\-\-\-\-\- +.EE +.PP +The PEM decoder of the \f[CR]hbkzpc provider\f[R] only handles PEM files +with the label \f[I]HARDWARE BACKED KEY ZPC\f[R]. +.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 +URI +unified resource identifier +.TP +ZPC +IBM Z protected key cryptography +.SH SEE ALSO +zpckey(1), hbkzpcprovider.conf(5), provider(7SSL). diff --git a/man/hbkzpcprovider.conf.5 b/man/hbkzpcprovider.conf.5 new file mode 100644 index 00000000..537c21b4 --- /dev/null +++ b/man/hbkzpcprovider.conf.5 @@ -0,0 +1,134 @@ +.\" Automatically generated by Pandoc 3.7.0.2 +.\" +.TH "HBKZPCPROVIDER.CNF" "5" "2026" "LIBZPC v2" +.SH NAME +hbkzpcprovider.conf \- Configuration syntax for the +\f[CR]hbkzpc provider\f[R] +.SH DESCRIPTION +This page documents the syntax of the OpenSSL configuration file for the +\f[CR]hbkzpc provider\f[R]. +It is a sub\-set of the OpenSSL configuration file format, described in +config(5SSL). +.SH CONFIGURATION +.SS OpenSSL Configuration +The \f[CR]hbkzpc provider\f[R] can be configured application\-specific +or system\-wide. +In both cases, the configuration file needs to define and reference a +section for the \f[CR]hbkzpc provider\f[R], following the OpenSSL +configuration syntax (config(5SSL)). +.PP +The provider section for the \f[CR]hbkzpc provider\f[R] specifies the +shared library of the provider (mandatory) and an activation flag +(optional). +.PP +Since OpenSSL configuration supports drop\-ins (keyword +\f[CR].inlcude\f[R]), the configuration for the +\f[CR]hbkzpc provider\f[R] can also be placed in a separate +configuration file. +.SS Provider Section +A provider section in the OpenSSL configuration defines generic +parameters, as well as provider\-specific parameters. +Each provider section must be referenced in the global providers +sections (\f[I]provider_sect\f[R]) of the OpenSSL configuration file. +The \f[CR]hbkzpc provider\f[R] supports no provider\-specific +parameters, but the provider section for the \f[CR]hbkzpc provider\f[R] +must specify at least the generic provider section parameter +\f[I]module\f[R]. +For more details about the generic provider parameters, see +config(5SSL). +.TP +module (mandatory) +This parameter takes a path to the provider shared object file. +For the \f[CR]hbkzpc provider\f[R], use the absolute path to the +installation location of \f[CR]zpcprovider.so\f[R] or the relative path +to the OpenSSL modules directory. +.TP +activate (optional) +If present and set to \f[CR]1\f[R], then the associated provider is +activated. +Conversely, setting this value to \f[CR]0\f[R] or not specifying the +parameter at all prevents the provider from being activated (default: +\f[CR]0\f[R]). +.PP +The \f[I]identity\f[R] parameter may be used in the provider section, +but it has no impact to the registration of the +\f[CR]hbkzpc provider\f[R]. +It will always register itself with \(lqprovider=hbkzpc\(rq. +Multiple instances of this provider may work but are not supported. +.SH EXAMPLES +The following drop\-in example specifies the \f[CR]hbkzpc provider\f[R] +module and activates it. +.IP +.EX +[provider_sect] +hbkzpc = hbkzpc_sect + +[hbkzpc_sect] +module = zpcprovider.so +activate = 1 +.EE +.PP +The drop\-in file needs to be included in the main OpenSSL +configuration, either by specifying the drop\-in file or the drop\-in +directory (for example \f[CR]/etc/pki/tls/openssl.d/\f[R] on Fedora). +.IP +.EX +\&.include /path/to/drop\-in\-directory +.EE +.PP +The following configuration example covers a complete minimal OpenSSL +configuration. +It can be used for example as a temporary replacement for the +system\-wide OpenSSL configuration. +.IP +.EX +HOME = . + +openssl_conf = openssl_init + +[openssl_init] +providers = provider_sect +alg_section = evp_properties + +[provider_sect] +default = default_sect +base = base_sect +hbkzpc = hbkzpc_sect + +[evp_properties] + +[base_sect] +activate = 1 + +[default_sect] +activate = 1 + +[hbkzpc_sect] +module = /path/to/zpcprovider.so +activate = 1 +.EE +.PP +To use this configuration example for an application, store it to a file +(e.g.\ my\-openssl.conf) and reference this file in the environment +variable \f[CR]OPENSSL_CONF\f[R]. +The following command lists all configured providers: base, default and +hbkzpc. +.IP +.EX +$ env OPENSSL_CONF=my\-openssl.conf openssl list \-providers +Providers: + base + name: OpenSSL Base Provider + version: 4.0.0 + status: active + default + name: OpenSSL Default Provider + version: 4.0.0 + status: active + hbkzpc + name: hbkzpc + version: 2.0.0 + status: active +.EE +.SH SEE ALSO +hbkzpcprovider(7), config(5SSL). diff --git a/man/zpckey.1 b/man/zpckey.1 new file mode 100644 index 00000000..877a5924 --- /dev/null +++ b/man/zpckey.1 @@ -0,0 +1,106 @@ +.\" Automatically generated by Pandoc 3.7.0.2 +.\" +.TH "ZPCKEY" "1" "2026" "LIBZPC v2" +.SH NAME +zpckey \- A key management tooling for protected key origins, used by +the OpenSSL provider for protected keys (\f[CR]hbkzpc provider\f[R]). +.SH SYNOPSIS +zpckey [\-h|\(enhelp] [\-V|\(enversion] +.PP +zpckey compose [] +.PP +zpckey show [] +.SH DESCRIPTION +The zpckey command provides key management functions for protected key +origins, used by the \f[CR]hbkzpc provider\f[R] (hbkzpcprovider(7)). +IBM Z and IBM LinuxONE offer different types of cryptographic hardware +with different features, including the CP Assist for Cryptographic +Functions (CPACF) and the IBM Crypto Express (CEX) features. +.PP +The CPACF provides functions to perform cryptographic operations with a +kind of hardware\-backed keys, the so called protected keys. +.PP +The CEX cards provide secure key generation and storage (secure keys), +as well as cryptographic operations with these keys. +.SH OPTIONS +.TP +\-V, \-\-version +Show version +.TP +\-h, \-\-help +Show short help +.SH ZPCKEY COMPOSE +The \f[I]compose\f[R] command supports the composition of protected key +origins, which can be used for the \f[CR]hbkzpc provider\f[R]. +.SS Required Arguments: +.TP +\-t, \-\-origin\-type +Protected key origin type +.TP +\-a, \-\-origin\-alg +Protected key origin algorithm +.SS Protected key origin types (): +.IP \(bu 2 +uv: Ultravisor retrievable secrets +.SS Protected key origin algorithms (): +.IP \(bu 2 +prime256v1 (alt.: 1.2.840.10045.3.1.7) +.IP \(bu 2 +secp384r1 (alt.: 1.3.132.0.34) +.IP \(bu 2 +secp521r1 (alt.: 1.3.132.0.35) +.IP \(bu 2 +ED25519 (alt.: 1.3.101.112) +.IP \(bu 2 +ED448 (alt.: 1.3.101.113) +.IP \(bu 2 +AES\-128 +.IP \(bu 2 +AES\-192 +.IP \(bu 2 +AES\-256 +.IP \(bu 2 +AES\-128\-XTS +.IP \(bu 2 +AES\-256\-XTS +.SS Optional Arguments: +.TP +\-p, \-\-pubkey +Public key file +.TP +\-o, \-\-out +Output file +.TP +\-\-outform +Output file format URI, DER or PEM (default: PEM) +.TP +\-c, \-\-comment +Comment (metadata) +.TP +\-h, \-\-help +Show short help +.SS Origin Arguments: +.TP +For = \f[I]uv\f[R], one out of the following must be specified: +.TP +\-\-uv\-secret\-id +UV secret ID +.TP +\-\-uv\-secret\-name +UV secret name +.SH ZPCKEY SHOW +The \f[I]show\f[R] command prints information about the key file to +stdout. +.SS Required Arguments: +.TP +\-i, \-\-in +Input file +.SS Optional Arguments: +.TP +\-\-inform +Input file format PEM or DER (default: PEM) +.TP +\-h, \-\-help +Show short help +.SH SEE ALSO +hbkzpcprovider.conf(5), hbkzpcprovider(7) diff --git a/conv_man.sh b/misc/update-man similarity index 79% rename from conv_man.sh rename to misc/update-man index 992e1477..ca15a72a 100755 --- a/conv_man.sh +++ b/misc/update-man @@ -2,10 +2,11 @@ # SPDX-License-Identifier: MIT # Copyright contributors to the libzpc project -SRCDIR=${1} -DSTDIR=${2} +SRCDIR=${1:-"./man/"} +DSTDIR=${2:-"./man/"} [ -z "${SRCDIR}" ] || [ -z "${DSTDIR}" ] && exit 1 +[ ! -d "${SRCDIR}" ] || [ ! -d "${DSTDIR}" ] && exit 1 command -v pandoc >/dev/null 2>&1 || exit 1 for MD in "${SRCDIR}"/*.md; do