This is an intermediate CMP, CRMF, and HTTP version abstraction library based on OpenSSL. It is needed as long as required CMP features are not yet (fully) available in the OpenSSL version being used.
Note that this library does not provide a CLI. In case you need a CLI or want to use a more high-level C API for CMP, take advantage of the Generic CMP Client, which can be built on top of this library or on OpenSSL 3.0 or later.
The purpose of this software is to provide a uniform interim CMP and HTTP client API and implementation library that links with all current OpenSSL versions.
Since version 3.0, OpenSSL includes an implementation of CMP version 2 and CRMF, as well as a lean HTTP client. Software that is based on earlier OpenSSL versions can make use of this library in order to use CMP and/or the HTTP client capabilities also with OpenSSL 1.x.
As of June 2023, the standardization of CMP version 3, see Certificate Management Protocol (CMP) Updates , is completed and is awaiting release at the IETF. Along with this document the Lightweight CMP Profile (LCMPP) has been defined for simple and interoperable industrial use of CMP.
This library meanwhile implements all features of CMP version 3 as defined in CMP Updates and detailed in the LCMPP .
Upstream contribution of the latest CMP features to OpenSSL is ongoing.
API documentation is available in the doc/man3
folder.
This software should work with any flavor of Linux, including Cygwin, also on a virtual machine or the Windows Subsystem for Linux (WSL), and with MacOS.
The following network and development tools are needed or recommended.
CMakeLists.txt
, tested with versions 3.18.4, 3.26.3, 3.27.7)The following OSS components are used.
For instance, on a Debian system the prerequisites may be installed simply as follows:
sudo apt install libssl-dev libc-dev linux-libc-dev
while apt install git make gcc
usually is not needed as far as these tools are pre-installed.
As a sanity check you can execute in a shell:
git clone git@github.com:mpeylo/cmpossl.git --depth 1
cd cmpossl
make -f OpenSSL_version.mk
This should output on the console something like
cc [...] OpenSSL_version.c -lcrypto -o OpenSSL_version
OpenSSL 3.0.8 7 Feb 2023 (0x30000080)
You might need to set the variable OPENSSL_DIR
first as described below, e.g.,
export OPENSSL_DIR=/usr/local
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.my-company.com:8080
You can clone the git repository with
git clone git@github.com:mpeylo/cmpossl.git --depth 1
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:mpeylo/cmpossl.git
When you later want to update your local copy of all relevant repositories it is sufficient to invoke
make update
The library 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, e.g.:
export OPENSSL_DIR=/usr/local
In case its libraries are in a different location, set also OPENSSL_LIB
, e.g.:
export OPENSSL_LIB=$OPENSSL_DIR/lib
Since 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 the
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
,
both a dynamic and a static library (libcmp.a
) are produced,
and there are some extra options.
You may specify using the environment variable OUT_DIR
where the produced library files (e.g., libcmp.so.2.0
) shall be placed.
By default, the current directory (.
) is used.\
The environment variable CC
may be set as needed; it defaults to gcc
.\
For further details on optional environment variables,
see the Makefile_v1
.
Build the software with
make
The result is in, for instance, ./libcmp.so.2.0
.
For compiling applications using the library,
you will need to add the directory include/cmp
to your C headers path.
For linking you will need to refer the linker to the library, e.g., -lcmp
and add the directory (e.g., with the linker option -L
) where it can be found.
See also the environment variable OUT_DIR
.
For helping the Linux loader to find the libraries at run time,
it is recommended to set also linker options like -Wl,-rpath=.
.
Also make sure that the OpenSSL libraries (typically referred to via -lssl -lcrypto
) are in your library path and
(the version) of the libraries found there by the linker match the header files found by the compiler.
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
.
make clean
removes part of the artifacts, while
make clean_all
removes everything produced by make
and CMake
.
This repository can build the following Debian and source packages.
libcmp
-- the shared librarylibcmp-dev
-- development headers and documentationlibcmp*Source.tar.gz
-- source tarballThe recommended way is to use CPack with files produced by CMake, for instance as follows:
make deb
The recommended way is to use CPack with the files produced by CMake as follows:
make deb
which requries 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:
debhelper
(needed for dh
)devscripts
(needed for debuild
)libssl-dev
The Debian packages may be installed for instance as follows:
sudo dpkg -i libcmp*deb
This software including associated documentation is provided ‘as is’. Effort has been spent on quality assurance, but there are no guarantees.
This work is licensed under the terms of the Apache Software License 2.0. See the LICENSE.txt file in the top-level directory.
SPDX-License-Identifier: Apache-2.0