1 Building and Installation
2 =========================
7 To build and install OpenSSL GOST Engine, you will need
9 * OpenSSL 3.0 development version
11 * CMake (3.0 or newer, 3.18 recommended)
13 Here is a quick build guide:
15 $ git clone https://github.com/gost-engine/engine
17 $ git submodule update --init
20 $ cmake -DCMAKE_BUILD_TYPE=Release ..
21 $ cmake --build . --config Release
23 Instead of `Release` you can use `Debug`, `RelWithDebInfo` or `MinSizeRel` configuration.
24 See [cmake docs](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html) for details.
25 You will find built binaries in `../bin` directory.
27 If you want to build against a specific OpenSSL instance (you will need it if
28 you have more than one OpenSSL instance for example), you can use the `cmake`
29 variable `OPENSSL_ROOT_DIR` to specify absolute path of the desirable OpenSSL
32 $ cmake -DOPENSSL_ROOT_DIR=/PATH/TO/OPENSSL/ ..
34 Building against OpenSSL 3.0 requires openssl detection module
35 (FindOpenSSL.cmake) from CMake 3.18 or higher. More earlier versions may have
38 If you use Visual Studio, you can also set `CMAKE_INSTALL_PREFIX` variable
39 to set install path, like this:
41 > cmake -G "Visual Studio 15 Win64" -DCMAKE_PREFIX_PATH=c:\OpenSSL\vc-win64a\ -DCMAKE_INSTALL_PREFIX=c:\OpenSSL\vc-win64a\ ..
43 Also instead of `cmake --build` tool you can just open `gost-engine.sln`
44 in Visual Studio, select configuration and call `Build Solution` manually.
46 Instructions how to build OpenSSL 1.1.0 with Microsoft Visual Studio
47 you can find [there](https://gist.github.com/terrillmoore/995421ea6171a9aa50552f6aa4be0998).
52 To install GOST Engine you can call:
54 # cmake --build . --target install --config Release
56 or old plain and Unix only:
60 The engine library `gost.so` should be installed into OpenSSL engine directory.
62 To ensure that it is installed propery call:
65 ENGINESDIR: "/usr/lib/i386-linux-gnu/engines-1.1"
67 Then check that `gost.so` there
69 # ls /usr/lib/i386-linux-gnu/engines-1.1
71 Finally, to start using GOST Engine through OpenSSL, you should edit
72 `openssl.cnf` configuration file as specified below.
78 The very minimal example of the configuration file is provided in this
79 distribution and named `example.conf`.
81 Configuration file should include following statement in the global
82 section, i.e. before first bracketed section header (see config(5) for details)
84 openssl_conf = openssl_def
86 where `openssl_def` is name of the section in configuration file which
87 describes global defaults.
89 This section should contain following statement:
92 engines = engine_section
94 which points to the section which describes list of the engines to be
95 loaded. This section should contain:
100 And section which describes configuration of the engine should contain
104 dynamic_path = /usr/lib/ssl/engines/libgost.so
105 default_algorithms = ALL
107 Various cryptoproviders (e.g. BouncyCastle) has some problems with private key
108 parsing from PrivateKeyInfo, so if you want to use old private key
109 representation format, which supported by BC, you will have to add:
111 GOST_PK_FORMAT = LEGACY_PK_WRAP
115 Where `engine_id` parameter specifies name of engine (should be `gost`).
117 `dynamic_path is` a location of the loadable shared library implementing the
118 engine. If the engine is compiled statically or is located in the OpenSSL
119 engines directory, this line can be omitted.
121 `default_algorithms` parameter specifies that all algorithms, provided by
122 engine, should be used.
124 The `CRYPT_PARAMS` parameter is engine-specific. It allows the user to choose
125 between different parameter sets of symmetric cipher algorithm. [RFC 4357][1]
126 specifies several parameters for the GOST 28147-89 algorithm, but OpenSSL
127 doesn't provide user interface to choose one when encrypting. So use engine
128 configuration parameter instead. It SHOULD NOT be used nowadays because all
129 the parameters except the default one are deprecated now.
131 Value of this parameter can be either short name, defined in OpenSSL
132 `obj_dat.h` header file or numeric representation of OID, defined in
135 [1]:https://tools.ietf.org/html/rfc4357 "RFC 4357"