Switch to pre-built man-pages

.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

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

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/<man-page-name>.<section>.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
 -------------------------------------
 

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
 

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\-\-\-\-\-
+[... <BASE64\-encoded data> ...]
+\-\-\-\-\-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).

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).