Prerequisites

This pages describes the prerequisites for setting up OpenSSL for usage with a Primus HSM using an OpenSSL provider.

You will need:

• A Securosys Primus HSM or CloudHSM
• A machine with OpenSSL and the Primus PKCS#11 API Provider installed (see below)

tip

For a wizard-like experience, use the installation script instead of the manual install. The script guides you through the process of installing and configuring the Primus PKCS#11 Provider and (optionally) integrates OpenSSL via PKCS#11.

Install the Primus PKCS#11 API Provider

OpenSSL communicates with the Primus HSM over the HSM's PKCS#11 API. Therefore, please install and configure the Primus PKCS#11 API Provider on your target machine.

Install OpenSSL 3.x (or later)

The easiest way to install OpenSSL is through your distribution's package manager. All recent versions of the major distributions include OpenSSL 3.x.

Package Manager

Installation using the package manager

On Debian 12 and Ubuntu 22.04 (and newer):

sudo apt install openssl

On Red Hat Enterprise Linux 9, CentOS 9, and Fedora 38 (or newer):

sudo dnf install openssl

On SUSE-15 SP4 (or newer):

sudo zypper install openssl-3

From Source

Build From Source

If a prebuilt version of OpenSSL is not available from your distribution, or you want to use a customized version of OpenSSL, you can compile from source.

Debian/Ubuntu

Install Build Dependencies With apt-get

On Debian/Ubuntu based distribution the following dependencies have to be installed:

apt-get -q update;
apt-get -yq install perl autoconf-archive automake libtool make gcc curl tar gzip;

RHEL

Install Dependencies With yum

On RHEL based distribution the following dependencies have to be installed:

yum install -y --skip-broken perl-core autoconf automake libtool make gcc curl tar gzip;

Container

It is possible to build OpenSSL 3 for your target system inside a docker container. Most Linux distributions offer an official docker image.

You can download the script to build OpenSSL 3 in a docker container here:

• containerized-openssl-3-builder-debian.sh
• containerized-openssl-3-builder-rhel.sh

In the script the code shown in [Build OpenSSL][#build-openssl] below is executed inside a container. The command used in the script to create the container is this:

docker run --rm \
	--env IUSER="$(id -u)" \
	--env IGRP="$(id -g)" \
	--env OPENSSL_VERSION  \
	--volume "$(pwd)/openssl-${OPENSSL_VERSION}-bin:/tmp/out" \
	"${DISTRO_IMAGE_NAME}" bash -ce \
	...

A docker container using the image ${DISTRO_IMAGE_NAME} this variable is set near the top of the script. This can be changed to use a container image that fits best your target system. The following images have been successfully tested (on 2024-02-05):

• With the Debian script: "debian:10", "debian:11", "ubuntu:18.04", "ubuntu:20.04"

• With the RHEL script: "centos:7" "rockylinux:8" "redhat/ubi8" "fedora:37"

The script creates a new directory openssl-${OPENSSL_VERSION}-bin. It is mounted as a volume inside the container. The output will be placed in that directory. In order to fix the ownership of the produced file, the uid and gid of the current user are passed to the container as well.

Build OpenSSL

warning

The script below creates binaries with their openssldir set to /opt/openssl-${OPENSSL_VERSION}/ssl. This means, that the default openssl configuration is /opt/openssl-${OPENSSL_VERSION}/ssl/openssl.cnf.

This is necessary to avoid collisions with the OpenSSL version distributed by the package manager.

OPENSSL_VERSION=3.2.1;

TMPDIR=$(realpath "${TMPDIR:-/tmp}");

echo "-- Downloading openssl-${OPENSSL_VERSION}";
curl -L "https://github.com/openssl/openssl/releases/download/openssl-${OPENSSL_VERSION}/openssl-${OPENSSL_VERSION}.tar.gz" -o "${TMPDIR}/openssl-${OPENSSL_VERSION}.tar.gz";
cd "${TMPDIR}";

echo "-- Extracting openssl-${OPENSSL_VERSION}";
tar xf "openssl-${OPENSSL_VERSION}.tar.gz";
mkdir -p "${TMPDIR}/build" "${TMPDIR}/inst" "${TMPDIR}/out";
cd "${TMPDIR}/build";

echo "-- Configuring openssl-${OPENSSL_VERSION}";
"../openssl-${OPENSSL_VERSION}/Configure" --libdir=lib --prefix="/opt/openssl-${OPENSSL_VERSION}" --openssldir="/opt/openssl-${OPENSSL_VERSION}/ssl";

echo "-- Compiling  openssl-${OPENSSL_VERSION}  (this may take a while)";
p="$(getconf _NPROCESSORS_ONLN)";
make --silent -j "${p}" -l "${p}" build_sw;
make --silent -j "${p}" -l "${p}" test;
make --silent -j "${p}" -l "${p}" install_sw install_ssldirs DESTDIR="${TMPDIR}/inst";

echo "-- Zipping binary openssl-${OPENSSL_VERSION}";
cd "${TMPDIR}/inst/opt/";
tar czf "${TMPDIR}/out/openssl-${OPENSSL_VERSION}.bin.tgz" .;
chown "root:root" "${TMPDIR}/out/openssl-${OPENSSL_VERSION}.bin.tgz";

echo "-- Build complete";
echo "-- To install OpenSSL on this system execute:";
echo "-- Untarring into /opt with sudo";
cd /opt && sudo tar -xf  "${TMPDIR}/out/openssl-${OPENSSL_VERSION}.bin.tgz .";

Post Build

Point your LD_LIBRARY_PATH to use the library of the sourced OpenSSL. Otherwise the applications try to use the system libraries.

export LD_LIBRARY_PATH=/opt/openssl-${OPENSSL_VERSION}/lib

Expected output when performing openssl version -a with OpenSSL v 3.0.15

openssl version -a

OpenSSL 3.0.2 15 Mar 2022 (Library: OpenSSL 3.0.15 3 Sep 2024)
built on: Wed Oct 30 08:49:28 2024 UTC
platform: linux-x86_64
options:  bn(64,64)
compiler: gcc -fPIC -pthread -m64 -Wa,--noexecstack -Wall -O3 -DOPENSSL_USE_NODELETE -DL_ENDIAN -DOPENSSL_PIC -DOPENSSL_BUILDING_OPENSSL -DNDEBUG
OPENSSLDIR: "/opt/openssl-3.0.15/ssl"
ENGINESDIR: "/opt/openssl-3.0.15/lib/engines-3"
MODULESDIR: "/opt/openssl-3.0.15/lib/ossl-modules"
Seeding source: os-specific
CPUINFO: OPENSSL_ia32cap=0xc2da2203478bffff:0x20842509