search

siemens / gencmpclient

generic CMP [RFC 4210, RFC 9483] client library and CLI, based on CMPforOpenSSL (https://github.com/mpeylo/cmpossl)
Other
10 stars 7 forks source link
client cmp openssl

readme

generic CMP client

This is a generic Certificate Management Protocol (CMP) client library with a high-level API for use with the C and C++ languages and associated CLI-based demo client, tests, and documentation.

Purpose

The purpose of this software is to provide a high-level C-based API on top of the detailed CMP (and CRMF) API of the OpenSSL library since version 3.0.

Until using an OpenSSL version > 3.0 that provides all those new CMP(v3) features needed for a given application, a further use case of this software may be to provide early access to all features of CMP as defined in CMP Updates and the Lightweight CMP Profile (LCMPP). To this end, it may be linked in addition to the intermediate CMP library CMPforOpenSSL, called libcmp below.

The high-level API is on the one hand convenient to use for application programmers and on the other hand complete and flexible enough to cover the major certificate management use cases. The library supports developing CMP clients that adhere to the Lightweight CMP Profile (LCMPP), which is geared towards simple and interoperable industrial use.

The software also provides a command-line interface (CLI) that is handy for interactive exploration of using CMP in a PKI.

Note: An OSS CMP client and registration authority (RA) implementation in Java is available in the form of a generic CMP RA and client component and the [LightweightCmpRa](), which is a demo CLI application using it.

Support model

The maintainers offer two levels of support.

Contributions are appreciated in the form of pull requests.

Status

This software provides all features of CMP version 3 as defined in CMP Updates according to the Lightweight CMP Profile (LCMPP), which has been defined for simple and interoperable industrial use of CMP.

Note: The successor of both RFC 4210 and CMP Updates, called RFC 4210bis, has been submitted to IESG for publication, as well as RFC 6712bis. As of end-2024, the main novelty of RFC 4210bis, which provides KEM support, is not yet implemented here.

Documentation

The Generic CMP client API specification and CLI documentation are available in the doc folder.

The Doxygen documentation of the underlying Security Utilities library is available via a link in its README file.

Prerequisites

This software should work with any flavor of Linux, including MacOS X, Cygwin, also on a virtual machine or the Windows Subsystem for Linux (WSL).

The following network and development tools are needed or recommended.

The following OSS components are used.

Hint: As long as your system provides at least OpenSSL 3.0 and related development header files at a sufficiently new patch level, better not manually install in addition a different OpenSSL version unless you need newer CMP features without using the intermediate CMP library libcmp. Such a manual installation can interfere with the more or less implicit references to the locations of OpenSSL header files and binary library files. So unless you know exactly what you are doing, you may receive version mismatch errors like the one mentioned below.

Linux installation

For instance, on a Debian or Ubuntu system the prerequisites may be installed simply as follows:

sudo apt install cmake libssl-dev libc-dev linux-libc-dev

while sudo apt install git make gcc wget usually is not needed as far as these tools are pre-installed.

You might need to set the variable OPENSSL_DIR first as described below, e.g.,

export OPENSSL_DIR=/usr/local

OS X installation

On a Mac OS X system the prerequisites may be installed by executing the following in a terminal:

brew install git make openssl cmake wget perl

When using gcc (instead of clang) and ccache:

brew install gcc ccache

For making sure that OpenSSL version 3 is installed:

brew uninstall --ignore-dependencies openssl@3
brew install openssl@3
brew --prefix openssl@3

Sanity checks on OpenSSL

As a sanity check whether OpenSSL is usable for building the CMP client, you can execute in a shell on a Unix-like system:

git clone https://github.com/siemens/gencmpclient.git
cd genCMPClient
make -s -f OpenSSL_version.mk 2>/dev/null

This should output on the console something like

OpenSSL 3.0.13 30 Jan 2024 (0x300000d0)

When getting version mismatch errors like

OpenSSL runtime version 0x304000d0 does not match version 0x300000d0 used by compiler

make sure that the system-level configuration for finding header and library files as well as the optional environment variables OPENSSL_DIR and OPENSSL_LIB described below are set up in a consistent way.

When having trouble building, which may be due to unsuitably set environment variables,

make -f OpenSSL_version.mk

can provides useful diagnostics.

Getting the software

For accessing the code repositories on GitHub you may need an SSH client with suitable credentials or an HTTP proxy set up, for instance:

export https_proxy=http://proxy.example.com:8080

You can clone the git repository and its submodules with

git clone https://github.com/siemens/gencmpclient.git
cd genCMPClient
make -f Makefile_v1 get_submodules

This will fetch also the underlying CMPforOpenSSL extension to OpenSSL if needed and the Security Utilities (libsecutils) library.

For using the project as a git submodule, do for instance the following in the directory where you want to integrate it:

git submodule add git@github.com:siemens/gencmpclient.git

When you later want to update your local copy of all relevant repositories it is sufficient to invoke

make update

When switching to a certain commit or version, e.g.

git checkout v2.0

then also execute

git submodule update
make -f Makefile_v1 clean

to bring the submodules in a state consistent with that and remove any previous possibly outdated artifacts.

Configuring

The generic CMP client (as well as its underlying libraries) assumes that OpenSSL is already installed, including the C header files needed for development (as provided by, e.g., the Debian/Ubuntu package libssl-dev).

By default any OpenSSL installation available on the system is used.

Set the optional environment variable OPENSSL_DIR to specify the absolute (or relative to ../) path of the OpenSSL installation to use.

This must point to the location in the file system from which include/openssl is directly accessible with this relative path name.\ In case its libraries are in a different location, set also OPENSSL_LIB.

Linux

Here are examples for Linux:

export OPENSSL_DIR=/usr/local
export OPENSSL_LIB=/lib/x86_64-linux-gnu

The value for OPENSSL_LIB may be obtained by

ldd `which openssl` | grep libcrypto.so | awk '{print $3}' | sed 's#/[^/]*$##'

OS X

On Mac OS X, these lines are suggested to add to ~/.zshrc

export LDFLAGS="-L$(brew --prefix openssl@3)/lib"
export CPPFLAGS="-I$(brew --prefix openssl@3)/include"
export OPENSSL_DIR=$(brew --prefix openssl@3)
export OPENSSL_LIB=$(brew --prefix openssl@3)/lib

After doing so, restart the terminal or copy&paste them there, too.

Common steps

Define the environment variable USE_LIBCMP for using the latest CMP features and fixes, which implies use of the intermediate library libcmp. When using OpenSSL version 1.x, this is ensured automatically. When using OpenSSL versions before 3.5 and USE_LIBCMP is not defined, not all of the CMP features newly defined in CMP Updates and in the Lightweight CMP Profile (LCMPP) are supported.

From the underlying Security Utilities library the following environment variables are inherited.

Since genCMPClient version 2, it is recommended to use CMake to produce the Makefile, for instance as follows:

cmake .

When using CMake, cmake must be (re-)run after setting or unsetting environment variables. By default, CMake builds are in Release mode. This may also be enforced by defining the environment variable NDEBUG. For switching to Debug mode, use cmake with -DCMAKE_BUILD_TYPE=Debug. The chosen mode is remembered in CMakeCache.txt.

For backward compatibility it is also possible to use instead of CMake pre-defined Makefile_v1; to this end symlink it to Makefile:

ln -s Makefile_v1 Makefile

or use for instance make -f Makefile_v1.

By default, builds using Makefile_v1 are in Debug mode. Release mode can be selected by defining the environment variable NDEBUG.

By default Makefile_v1 behaves as if

OPENSSL_DIR=/usr

was given, such that the OpenSSL headers will be searched for in /usr/include and its shared objects in /usr/lib (or /usr/bin for Cygwin).

When using Makefile_v1, you may specify via the environment variable OUT_DIR where the produced libraries (e.g., libgencmp.so*, libcmp.so*, and libsecutils.so*) shall be placed. It defaults to the base directory of the respective library. If the environment variable BIN_DIR is not empty, the the CLI application cmpClient will be built and placed in BIN_DIR. If the variable is unset, . is used by default. For all path variables, relative paths such as . are interpreted relative to the directory of the genCMPClient module. The CC environment variable may be set as needed; it defaults to gcc. It is also possible to statically link with libcmp.a, using STATIC_LIBCMP. For further details on optional environment variables, see the Makefile_v1 and Makefile_src.

Building

Build the software with

make

The result is in, for instance, ./libgencmp.so.2.0. This also builds all required dependencies (such as libsecutils/libsecutils.so.2.0 and cmpossl/libcmp.so.2.0) and an application (./cmpClient) that is intended for demonstration, test, and exploration purposes.

When getting the compiler error: 'openssl/openssl_backport.h' file not found likely include/genericCMPClient_config.h is outdated and contains #define USE_LIBCMP although the environment variable USE_LIBCMP is not set. In such situations, make -f Makefile_v1 clean helps to reset it to a consistent state.

Installing and uninstalling

The software can be installed with, e.g.,

sudo make install

and uninstalled with

sudo make uninstall

The destination is /usr, unless specified otherwise by DESTDIR or ROOTFS.

Cleaning up

make clean removes part of the artifacts, while make clean_all removes everything produced by make and CMake.

Building Debian packages for use also with Ubuntu

This repository can build the following binary and source packages.

The recommended way is to use CPack with the files produced by CMake as follows:

make deb

which requires the file utility.

Alternatively, Makefile_v1 may be used like this:

make -f Makefile_v1 deb

In this case, the resulting packages are placed in the parent directory (../), and requires the following Debian packages: