Skip to content

Latest commit

 

History

History
135 lines (90 loc) · 4.37 KB

INSTALL.md

File metadata and controls

135 lines (90 loc) · 4.37 KB
Raw

Building and Installation

How to Build

To build and install OpenSSL GOST Engine, you will need

  • OpenSSL 3.0 development version
  • an ANSI C compiler
  • CMake (3.0 or newer, 3.18 recommended)

Here is a quick build guide:

$ git clone https://github.com/gost-engine/engine
$ cd engine
$ git submodule update --init
$ mkdir build
$ cd build
$ cmake -DCMAKE_BUILD_TYPE=Release ..
$ cmake --build . --config Release

Instead of Release you can use Debug, RelWithDebInfo or MinSizeRel configuration. See cmake docs for details. You will find built binaries in ../bin directory.

If you want to build against a specific OpenSSL instance (you will need it if you have more than one OpenSSL instance for example), you can use the cmake variable OPENSSL_ROOT_DIR to specify absolute path of the desirable OpenSSL instance:

$ cmake -DOPENSSL_ROOT_DIR=/PATH/TO/OPENSSL/ ..

Building against OpenSSL 3.0 requires openssl detection module (FindOpenSSL.cmake) from CMake 3.18 or higher. More earlier versions may have problems with it.

If you use Visual Studio, you can also set CMAKE_INSTALL_PREFIX variable to set install path, like this:

> cmake -G "Visual Studio 15 Win64" -DCMAKE_PREFIX_PATH=c:\OpenSSL\vc-win64a\ -DCMAKE_INSTALL_PREFIX=c:\OpenSSL\vc-win64a\ ..

Also instead of cmake --build tool you can just open gost-engine.sln in Visual Studio, select configuration and call Build Solution manually.

Instructions how to build OpenSSL 1.1.0 with Microsoft Visual Studio you can find there.

How to Install

To install GOST Engine you can call:

# cmake --build . --target install --config Release

or old plain and Unix only:

# make install

The engine library gost.so should be installed into OpenSSL engine directory.

To ensure that it is installed propery call:

$ openssl version -e
ENGINESDIR: "/usr/lib/i386-linux-gnu/engines-1.1"

Then check that gost.so there

# ls /usr/lib/i386-linux-gnu/engines-1.1

Finally, to start using GOST Engine through OpenSSL, you should edit openssl.cnf configuration file as specified below.

How to Configure

The very minimal example of the configuration file is provided in this distribution and named example.conf.

Configuration file should include following statement in the global section, i.e. before first bracketed section header (see config(5) for details)

openssl_conf = openssl_def

where openssl_def is name of the section in configuration file which describes global defaults.

This section should contain following statement:

[openssl_def]
engines = engine_section

which points to the section which describes list of the engines to be loaded. This section should contain:

[engine_section]
gost = gost_section

And section which describes configuration of the engine should contain

[gost_section]
engine_id = gost
dynamic_path = /usr/lib/ssl/engines/libgost.so
default_algorithms = ALL

Various cryptoproviders (e.g. BouncyCastle) has some problems with private key parsing from PrivateKeyInfo, so if you want to use old private key representation format, which supported by BC, you will have to add:

GOST_PK_FORMAT = LEGACY_PK_WRAP

to [gost_section].

Where engine_id parameter specifies name of engine (should be gost).

dynamic_path is a location of the loadable shared library implementing the engine. If the engine is compiled statically or is located in the OpenSSL engines directory, this line can be omitted.

default_algorithms parameter specifies that all algorithms, provided by engine, should be used.

The CRYPT_PARAMS parameter is engine-specific. It allows the user to choose between different parameter sets of symmetric cipher algorithm. RFC 4357 specifies several parameters for the GOST 28147-89 algorithm, but OpenSSL doesn't provide user interface to choose one when encrypting. So use engine configuration parameter instead. It SHOULD NOT be used nowadays because all the parameters except the default one are deprecated now.

Value of this parameter can be either short name, defined in OpenSSL obj_dat.h header file or numeric representation of OID, defined in RFC 4357.