libsuola OpenSSL Engine

This project aims at developing an OpenSSL engine rigging cryptosystem implementations derived from NaCl into OpenSSL.

The project currently supports three alternative back-end providers:

• libsodium
• HACL*
• donna

More details are available in this paper.

• Project structure
• Installation
  • OpenSSL
  • Back-end provider
    • libsodium
    • HACL
  • libsuola
• Uninstall
• Usage
  • List algorithms
  • Generate private key
  • Generate public key
  • Examine a key
  • Sign data
  • Verify data
  • Generate cert
  • Generate new key and cert
  • Examine a cert
  • ENV variables
• License
• OID crud
  • Ed25519
• Acknowledgments

Project structure

The source code of the project is organized hierarchically.

.
├── debug
├── meths
├── ossl
├── providers
│   ├── _dummy
│   ├── api
│   ├── donna
│   ├── hacl
│   ├── libsodium
│   └── ossl
├── tests
└── suola.c

• suola.c contains the main entry point for loading of the ENGINE;
• meths contains the implementation of the OpenSSL method structures defining the implemented cryptosystems;
• ossl contains code to integrate error codes, messages, NIDs, and OIDs in the OpenSSL abstractions;
• providers contains the code to map the primitives referenced in the meths structures to the actual cryptographic implementation provider:
  • api describes the API that a valid provider module needs to implement;
  • libsodium, hacl and donna map the cryptographic functionality to the corresponding backend implementation;
  • _dummy includes boilerplate code for additional functions (e.g.
    an empty suola_implementation_init() that can be used when the backend provider does not require any initialization before being used);
  • ossl includes boilerplate code for additional functions that are implemented reusing OpenSSL methods rather than a backend implementation (e.g.\ implement suola_randombytes_buf() using OpenSSL RAND module rather then the backend PRNG);
• tests contains code used to automate testing of the ENGINE;
• debug contains definitions used to implement the debug messaging system.

Installation

OpenSSL

git clone https://github.com/openssl/openssl.git openssl-master
cd openssl-master/
export OPENSSL_ROOT_DIR=/usr/local/ssl
./config -d shared --prefix=$OPENSSL_ROOT_DIR --openssldir=$OPENSSL_ROOT_DIR -Wl,-rpath=$OPENSSL_ROOT_DIR/lib
make -j4
make test
sudo checkinstall --strip=no --stripso=no --pkgname=openssl-master-debug --provides=openssl-master-debug --pkgversion=1.1.1 --default make install_sw
alias openssl=$OPENSSL_ROOT_DIR/bin/openssl

Back-end provider

libsodium

git clone https://github.com/jedisct1/libsodium --branch stable
cd libsodium/
LIBSODIUM_PREFIX=/usr/local
./configure --enable-debug --prefix=${LIBSODIUM_PREFIX}
make
make check
sudo checkinstall --strip=no --stripso=no --pkgname=libsodium-debug --provides=libsodium-debug --default
mkdir -p ~/.cmake/Modules
cp contrib/Findsodium.cmake ~/.cmake/Modules/

HACL

git clone https://github.com/mitls/hacl-star
cd hacl-star
make build
cd build
sudo checkinstall --strip=no --stripso=no --pkgname=libhacl-debug --provides=libhacl-debug --default
sudo ldconfig

libsuola

git clone [email protected]:romen/engine_25519.git --branch suola libsuola
cd libsuola
mkdir build
cd build
# -DUSE_DONNA=<ON|OFF> enables/disables the DONNA implementation as the provider backend, which by default is libsodium
# -DUSE_HACL=<ON|OFF> enables/disables HACL as the provider backend, which by default is libsodium
# -DHACL_PREFIX=<path> allows to specify the installation prefix for HACL, by default /usr/local
cmake -DCMAKE_BUILD_TYPE=Debug -DOPENSSL_ROOT_DIR=${OPENSSL_ROOT_DIR} -DUSE_HACL=ON ..
make
make test
#ctest --output-on-failure
#ctest --verbose
sudo checkinstall --strip=no --stripso=no --pkgname=libsuola-debug --provides=libsuola-debug --default

Uninstall

sudo dpkg -r libsuola-debug
sudo dpkg -r libhacl-debug
sudo dpkg -r libsodium-debug
sudo dpkg -r openssl-master-debug

Usage

List algorithms

openssl engine -c libsuola

Generate private key

openssl genpkey -engine libsuola -algorithm Ed25519 -out priv.pem

Generate public key

openssl pkey -engine libsuola -in priv.pem -pubout -out pub.pem

Examine a key

openssl pkey -engine libsuola -in key.pem -text

Sign data

openssl dgst -engine libsuola -sign priv.pem -out lsb-release.sig /etc/lsb-release

Verify data

openssl dgst -engine libsuola -verify pub.pem -signature lsb-release.sig /etc/lsb-release

Generate cert

openssl req -engine libsuola -x509 -config /path/to/openssl.cnf -new -key priv.pem -out cert.pem

Generate new key and cert

openssl req -engine libsuola -x509 -config /usr/lib/ssl/openssl.cnf -nodes -newkey Ed25519 -keyout priv.pem -out cert.pem

Examine a cert

openssl asn1parse -in cert.pem

ENV variables

The verbosity level of libsuola logging output is controlled by the SUOLA_DEBUG environment variable, which can be set to an integer value as detailed in this list:

• 1 (LOG_FATAL)
• 2 (LOG_ERR)
• 3 (LOG_WARN) default
• 4 (LOG_INFO)
• 5 (LOG_DBG)
• 6 (LOG_VRB)
• 10 (LOG_EXTRM)

Example: export SUOLA_DEBUG=5 will setup libsuola to print messages with priority LOG_DBG or higher (highest priority is LOG_FATAL).

Environment variables relevant to the project include those affecting OpenSSL, specifically the following ones:

• OPENSSL_ENGINES sets the directory from which engines are loaded (the default value can be obtained by openssl version -e
• OPENSSL_CONF sets a custom configuration file (the default value is $OPENSSLDIR/openssl.cnf, openssl version -d)

License

libsuola is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

libsuola is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this program. If not, see http://www.gnu.org/licenses/.

The full text of the license is contained in the files COPYING and COPYING.LESSER.

OID crud

• Database

Ed25519

• https://tools.ietf.org/html/rfc8032
• https://tools.ietf.org/html/draft-josefsson-pkix-eddsa-04
• https://tools.ietf.org/html/draft-josefsson-tls-ed25519-00
• https://tools.ietf.org/html/draft-ietf-curdle-pkix-04
• IETF curdle mailing list archive
• https://www.gnu.org/prep/standards/html_node/OID-Allocations.html
• OpenPGP
• str4d/ed25519-java#20

Acknowledgments

• Supported in part by Academy of Finland grant 303814.
• This article is based in part upon work from COST Action IC1403 CRYPTACUS, supported by COST (European Cooperation in Science and Technology).