The library provides easier access to some of the functions provided by OpenSSL. It does not attempt to wrap its data types but adds some functionality for file access, file protection, configuration handling, HTTP and TLS connections, certificate verification and status checking with CRLs and/or OCSP, and logging. The Unified Trust Anchor (UTA) library can be used for enhanced file protection.
Clone the git repository, e.g., with
git clone [email protected]:siemens/libsecutils.git
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.
- Git (for getting the software, tested with versions 2.7.2, 2.11.0, 2.20, 2.30.2, 2.39.2)
- CMake (for using
CMakeLists.txt
, tested with versions 3.18.4, 3.26.3, 3.27.7) - GNU make (tested with versions 3.81, 4.1, 4.2.1, 4.3)
- GNU C compiler (gcc, tested with versions 5.4.0, 7.3.0, 8.3.0, 10.0.1, 10.2.1) or clang (tested with version 14.0.3 and 17.0.3)
The following OSS components are used.
-
OpenSSL development edition, at least version 1.1.1. Tested, among others, with 1.0.2u, 1.1.0f, 1.1.0g, 1.1.1d, 1.1.1i, 1.1.1l, and 3.0.0.
Warning: OpenSSL 1.1.1 (on Mint 19) contains a bug where used cipher suite (level 3) is empty (1.1.1d on Buster works correctly) -
optionally: github.com/siemens/libuta
For instance, on a Debian system the prerequisites may be installed simply as follows:
sudo apt install cmake 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.
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
Use of the UTA library can be enabled
by setting the environment variable SECUTILS_USE_UTA
.
When SECUTILS_USE_ICV
is set, configuration files are expected
to be integrity protected with an Integrity Check Value (ICV),
which may be produced using icvutil
.
The TLS-related functions may be disabled by setting SECUTILS_NO_TLS
.
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
,
you may also specify using the environment variable OUT_DIR
where the produced library files (e.g., libsecutils.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,
./libsecutils.so
(when using Makefile_v1
on Linux)
or src/libsecutils/libsecutils.dylib
(when using CMake on MacOS).
When getting the linker error: Undefined symbols: _uta_init_v1
,
likely src/libsecutils/include/secutils/secutils_static_config.h
is outdated.
In such situations, make clean
can be called to removes it,
and then the configuration can be done again to obtain a consistent state.
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
.
This repository can build the following Debian and source packages.
libsecutils
-- the shared librarylibsecutils-dev
-- development headers and documentationlibsecutils-bin
-- helper binaries; so far, there is onlyicvutil
, in caseSECUTILS_USE_UTA
is setlibsecutils*Source.tar.gz
-- source tarball
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 fordh
)devscripts
(needed fordebuild
)libssl-dev
libuta-dev
(from github.com/siemens/libuta) ifSECUTILS_USE_UTA
is set
The Debian packages may be installed for instance as follows:
sudo dpkg -i libsecutils*deb
To build the documentation, the following dependencies need to be installed:
doxygen
graphviz
latex
, in case LaTeX output is desired; if so, comment out inDoxyfile
:GENERATE_LATEX = NO
The documentation is built by
make doc
or
make -f Makefile_v1 doc
make clean
removes part of the artifacts, while
make clean_all
removes everything produced by make
and CMake
.
Most functions of the library can be used directly without specific context.
A few functions that make use of the UTA library require a uta_ctx
pointer,
which may be non-NULL
only if SECUTILS_USE_UTA
is set.
You may have a look at util/icvutil.c
for a simple example.
The library functionality is organized by topic:
- certstatus
- validate certificates, optionally with status checks using CRLs and/or OCSP
- config
- OpenSSL configuration files
- connections
- HTTP and/or TLS
- credentials
- credentials consisting of a symmetric key or private key and the corresponding certificate
- crypto
- AES-256-GCM en-/decryption
- storage
- protected files, e.g. to store a private key in a PEM file encrypted with a hardware-bound password
- util
- Utilities used also within in the library, e.g. for logging
Copyright (c) Siemens Mobility GmbH, 2021-2023
This work is licensed under the terms of the Apache Software License 2.0. See the COPYING file in the top-level directory.
SPDX-License-Identifier: Apache-2.0