From 6aa35b5f59ab0ba91bada082f4c4698bb92dfcee Mon Sep 17 00:00:00 2001 From: "Dr. David von Oheimb" Date: Thu, 14 Nov 2024 19:10:13 +0100 Subject: [PATCH 1/3] README.md: update on the role of libcmp (cmpossl); further improvements --- README.md | 98 +++++++++++++++++++++++++++++++++++++++++-------------- cmpossl | 2 +- 2 files changed, 74 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 73ff4db..2a3c8d1 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,22 @@ # generic CMP client This is a generic Certificate Management Protocol (CMP) client library -with a high-level API +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 API -on top of the detailed CMP (and CRMF) API of -[OpenSSL](https://www.openssl.org/) since version 3.0. -It can be used with OpenSSL and optionally the intermediate CMP library -[CMPforOpenSSL](https://github.com/mpeylo/cmpossl), called `libcmp` below, -providing the CMPv3 features defined in -[CMP Updates](https://www.rfc-editor.org/rfc/rfc9480). +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](https://www.openssl-library.org/) 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](https://www.rfc-editor.org/rfc/rfc9480) +and the [Lightweight CMP Profile (LCMPP)](https://www.rfc-editor.org/rfc/rfc9483). +To this end, it may be linked in addition to the intermediate CMP library +[CMPforOpenSSL](https://github.com/mpeylo/cmpossl), 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 @@ -20,9 +24,16 @@ to cover the major certificate management use cases. The library supports developing CMP clients that adhere to the [Lightweight CMP Profile (LCMPP)](https://www.rfc-editor.org/rfc/rfc9483), 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](https://github.com/siemens/cmp-ra-component) +and the [LightweightCmpRa](), which is a demo CLI application using it. + + ## Support model The [maintainers](MAINTAINERS) offer two levels of support. @@ -35,14 +46,34 @@ The [maintainers](MAINTAINERS) offer two levels of support. in the form of [pull requests](../../pulls). -## Status and changelog +## Status -See the [CHANGELOG.md](CHANGELOG.md) file in the top-level directory. +This software provides all features of CMP version 3 +as defined in [CMP Updates](https://www.rfc-editor.org/rfc/rfc9480) according +to the [Lightweight CMP Profile (LCMPP)](https://www.rfc-editor.org/rfc/rfc9483), +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](https://datatracker.ietf.org/doc/draft-ietf-lamps-rfc4210bis/), +has been submitted to IESG for publication, as well as +[RFC 6712bis](https://datatracker.ietf.org/doc/draft-ietf-lamps-rfc6712bis/). +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`](doc/) folder. +The Generic CMP client API specification and CLI documentation +are available in the [`doc`](doc/) folder. The Doxygen documentation of the underlying Security Utilities library is available via a link in its [README file](https://github.com/siemens/libsecutils/blob/master/README.md). @@ -50,9 +81,9 @@ via a link in its [README file](https://github.com/siemens/libsecutils/blob/mast ## Prerequisites -This software should work with any flavor of Linux, including [Cygwin](https://www.cygwin.com/), -also on a virtual machine or the Windows Subsystem for Linux ([WSL](https://docs.microsoft.com/windows/wsl/about)), -and with MacOS X. +This software should work with any flavor of Linux, +including MacOS X, [Cygwin](https://www.cygwin.com/), also on a virtual machine or +the Windows Subsystem for Linux ([WSL](https://docs.microsoft.com/windows/wsl/about)). The following network and development tools are needed or recommended. * Git (for getting the software, tested with versions 2.7.2, 2.11.0, 2.20, 2.30.2, 2.39.2) @@ -77,7 +108,7 @@ 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 libary files. +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](#sanity-checks-on-openssl). @@ -89,7 +120,8 @@ For instance, on a Debian or Ubuntu system the prerequisites may be installed si ``` 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. +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., ``` @@ -161,7 +193,8 @@ cd genCMPClient make -f Makefile_v1 get_submodules ``` -This will fetch also the underlying [CMPforOpenSSL extension to OpenSSL](https://github.com/mpeylo/cmpossl) if needed and +This will fetch also the underlying +[CMPforOpenSSL extension to OpenSSL](https://github.com/mpeylo/cmpossl) if needed and the [Security Utilities (libsecutils)](https://github.com/siemens/libsecutils) library. For using the project as a git submodule, @@ -305,7 +338,8 @@ 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 Makfile_v1 clean` helps to reset it to a consistent state. +is not set. +In such situations, `make -f Makefile_v1 clean` helps to reset it to a consistent state. ### Installing and uninstalling @@ -340,7 +374,7 @@ The recommended way is to use CPack with the files produced by CMake as follows: ``` make deb ``` -which requries the `file` utility. +which requires the `file` utility. Alternatively, [`Makefile_v1`](Makefile_v1) may be used like this: ``` @@ -411,7 +445,7 @@ make -f Makefile_v1 test_Insta where the PROXY environment variable may be used to override the default in order to reach the Insta Demo CA. -In order to obain a trace of the HTTP messages being sent and received, +In order to obtain a trace of the HTTP messages being sent and received, build the genCMPClient with `USE_LIBCMP=1` and set the environment variable `OPENSSL_TRACE` to contain the string `"HTTP"`. For instance: @@ -419,7 +453,7 @@ For instance: OPENSSL_TRACE=HTTP ./cmpClient imprint -section Insta ``` -To select a specific CMP profile on the cloudCA server, set the environment +To select a specific CMP profile on the CloudCA server, set the environment variable `CMP_PROFILE` to the profile name. For instance: ``` @@ -438,9 +472,11 @@ for instance as given in the example outer [`Makefile.mk`](Makefile.mk). For compiling applications using the library, you will need to `#include` the header file [`genericCMPClient.h`](include/genericCMPClient.h) and add the directories [`include`](include/) and -[`libsecutils/include`](https://github.com/siemens/libsecutils/blob/master/include/) to your C headers path. +[`libsecutils/include`]( +https://github.com/siemens/libsecutils/blob/master/include/) to your C headers path. When the intermediate library `libcmp` is used, you need to -add also the directory [`cmpossl/include/cmp`](https://github.com/mpeylo/cmpossl/tree/cmp/include/cmp/), +add also the directory [`cmpossl/include/cmp`]( +https://github.com/mpeylo/cmpossl/tree/cmp/include/cmp/), define the C macro `USE_LIBCMP`, and make sure that any OpenSSL header files included have the same version as the one used to build `libcmp`. @@ -456,9 +492,10 @@ for helping the Linux loader find the libraries at run time. 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 version of) the libraries found there by the linker +match the header files found by the compiler. -All this is already done for the cmp client application. +All this is already done for the CMP client application `cmpClient`. ## Disclaimer @@ -473,3 +510,14 @@ This work is licensed under the terms of the Apache Software License 2.0. See the [LICENSE.txt](LICENSE.txt) file in the top-level directory. SPDX-License-Identifier: Apache-2.0 + + diff --git a/cmpossl b/cmpossl index 6d7df0b..90e58ce 160000 --- a/cmpossl +++ b/cmpossl @@ -1 +1 @@ -Subproject commit 6d7df0bb90c4c1895222f76b5f5f96780871d855 +Subproject commit 90e58ce2043d41b8c79f62537c5af78c3790642a From 5c524eef2b2e868483054c1b97f9efd7ed7b0eb8 Mon Sep 17 00:00:00 2001 From: "Dr. David von Oheimb" Date: Fri, 15 Nov 2024 09:50:41 +0100 Subject: [PATCH 2/3] CHANGELOG.md: add entry for release of 2.0 --- CHANGELOG.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c52a5e..be965fa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,11 @@ genCMPClient changes ==================== +genCMPClient 2.0 +---------------- + +* Released on Wed, 12 Apr 2023 23:04:14 +0200 + genCMPClient 1.0 ---------------- From 9f3416f1001e12be6ad11ef8a3eeae28ee9827ea Mon Sep 17 00:00:00 2001 From: "Dr. David von Oheimb" Date: Fri, 15 Nov 2024 09:51:21 +0100 Subject: [PATCH 3/3] cmpossl cmp_msg.c: fix corner case calling add_extensions() with non-NULL but empty extensions list --- cmpossl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cmpossl b/cmpossl index 90e58ce..5eac6d5 160000 --- a/cmpossl +++ b/cmpossl @@ -1 +1 @@ -Subproject commit 90e58ce2043d41b8c79f62537c5af78c3790642a +Subproject commit 5eac6d579b098ca4d489dd250a5f36fa5f9be3f8