Bee2evp: an OpenSSL engine

What is Bee2evp?

Bee2evp is a cryptographic library which encapsulates Bee2 into OpenSSL. Bee2evp provides cryptographic services using the EVP interface. Bee2evp is organized as an OpenSSL engine.

Build

[git submodule update --init]
mkdir build
cd build
cmake [-DCMAKE_BUILD_TYPE={Release|Debug|Coverage|ASan|ASanDbg|MemSan|MemSanDbg|Check}] ..
cmake --build . [--config={Release|Debug}]
[cmake --install .]

Build types (Release by default):

• Coverage -- test coverage;
• ASan, ASanDbg -- address sanitizer;
• MemSan, MemSanDbg -- memory sanitizer;
• Check -- strict compile rules.

Preparations

Before building Bee2evp, it is necessary to build and configure Bee2 and OpenSSL. Bee2evp requires OpenSSL version 1.1.1 or higher.

Building Bee2

See instructions in github.com/agievich/bee2.

Building OpenSSL

1. Download the latest source files from openssl.org/source.
2. Unpack files into some directory, for example, openssl-1.1.1.
3. Go to this directory.
4. Run the following commands:

   mkdir build
   cd build
   ../config 
   make
   make install
   

By default, OpenSSL {headers|binaries|libraries} will be installed in the directory /usr/local/{include|bin|lib}.

Configuring OpenSSL

1. Rename /usr/local/ssl/openssl.cnf.dist -> /usr/local/lib/openssl.cnf.
2. Open /usr/local/lib/openssl.cnf.
3. Add the following lines (before the [new_oids] section):

   openssl_conf = openssl_init
   [openssl_init]
   engines = engine_section
   [engine_section]
   bee2evp = bee2evp_section
   [bee2evp_section]
   engine_id = bee2evp
   dynamic_path = /usr/local/lib/libbee2evp.so
   default_algorithms = ALL
   

4. Make sure LD_LIBRARY_PATH includes /usr/local/lib.

Listing the capabilities

openssl engine -c -t bee2evp

BTLS

In this folder, patches for different versions of OpenSSL are provided. These patches support the following ciphersuites defined in STB 34.101.65 (Btls, see apmi.bsu.by/resources/std.html):

• DHE-BIGN-WITH-BELT-CTR-MAC-HBELT;
• DHE-BIGN-WITH-BELT-DWP-HBELT;
• DHT-BIGN-WITH-BELT-CTR-MAC-HBELT;
• DHT-BIGN-WITH-BELT-DWP-HBELT;
• DHE-PSK-BIGN-WITH-BELT-CTR-MAC-HBELT;
• DHE-PSK-BIGN-WITH-BELT-DWP-HBELT;
• DHT-PSK-BIGN-WITH-BELT-CTR-MAC-HBELT;
• DHT-PSK-BIGN-WITH-BELT-DWP-HBELT.

Build script

Bash script can be used for OpenSSL downloading, patching, configuring and building, Bee2 and Bee2evp building and tests running.

bash scripts/build.sh [-s -b -t] <OPENSSL_TAG>

Available values for OPENSSL_TAG are patch names in directory btls/patch. Supported OS are Linux, MacOS and Windows (via MSYS). The script requires GNU binutils and GNU sed to be available via PATH environment variable (additional packages can be installed on MacOS).

Build in Docker

# OpenSSL 1.1.1 + Bee2evp engine
docker build --progress="plain" -f dockerfiles/debian.Dockerfile \
   -t bcrypto/bee2evp:1.1.1 --build-arg OPENSSL_TAG=OpenSSL_1_1_1i .
# OpenSSL 3.3.1 + Bee2evp engine
docker build --progress="plain" -f dockerfiles/debian.Dockerfile \
   -t bcrypto/bee2evp:3.3.1 --build-arg OPENSSL_TAG=openssl-3.3.1 . 

Run bash on prepared docker image:

docker run --rm -it -v .:/usr/src  bcrypto/bee2evp:1.1.1 bash

License

Bee2evp is distributed under the Apache License version 2.0. See Apache 2.0 or LICENSE for details.

Automated tools

Platforms:

• Github Actions;
• Travis CI (archived).

Code coverage:

• CodeCov.