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