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)
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
25 if you have more than one OpenSSL instance for example), you can use
26 the `cmake` variable `OPENSSL_ROOT_DIR` to specify path of the desirable
29 $ cmake -DOPENSSL_ROOT_DIR=/PATH/TO/OPENSSL/ ..
31 If you use Visual Studio, you can also set `CMAKE_INSTALL_PREFIX` variable
32 to set install path, like this:
34 > cmake -G "Visual Studio 15 Win64" -DCMAKE_PREFIX_PATH=c:\OpenSSL\vc-win64a\ -DCMAKE_INSTALL_PREFIX=c:\OpenSSL\vc-win64a\ ..
36 Also instead of `cmake --build` tool you can just open `gost-engine.sln`
37 in Visual Studio, select configuration and call `Build Solution` manually.
39 Instructions how to build OpenSSL 1.1.0 with Microsoft Visual Studio
40 you can find [there](https://gist.github.com/terrillmoore/995421ea6171a9aa50552f6aa4be0998).
45 To install GOST Engine you can call:
47 # cmake --build . --target install --config Release
49 or old plain and Unix only:
53 The engine library `gost.so` should be installed into OpenSSL engine directory.
55 To ensure that it is installed propery call:
58 ENGINESDIR: "/usr/lib/i386-linux-gnu/engines-1.1"
60 Then check that `gost.so` there
62 # ls /usr/lib/i386-linux-gnu/engines-1.1
64 Finally, to start using GOST Engine through OpenSSL, you should edit
65 `openssl.cnf` configuration file as specified below.
71 The very minimal example of the configuration file is provided in this
72 distribution and named `example.conf`.
74 Configuration file should include following statement in the global
75 section, i.e. before first bracketed section header (see config(5) for details)
77 openssl_conf = openssl_def
79 where `openssl_def` is name of the section in configuration file which
80 describes global defaults.
82 This section should contain following statement:
85 engines = engine_section
87 which points to the section which describes list of the engines to be
88 loaded. This section should contain:
93 And section which describes configuration of the engine should contain
97 dynamic_path = /usr/lib/ssl/engines/libgost.so
98 default_algorithms = ALL
100 Various cryptoproviders (e.g. BouncyCastle) has some problems with private key
101 parsing from PrivateKeyInfo, so if you want to use old private key
102 representation format, which supported by BC, you will have to add:
104 GOST_PK_FORMAT = LEGACY_PK_WRAP
108 Where `engine_id` parameter specifies name of engine (should be `gost`).
110 `dynamic_path is` a location of the loadable shared library implementing the
111 engine. If the engine is compiled statically or is located in the OpenSSL
112 engines directory, this line can be omitted.
114 `default_algorithms` parameter specifies that all algorithms, provided by
115 engine, should be used.
117 The `CRYPT_PARAMS` parameter is engine-specific. It allows the user to choose
118 between different parameter sets of symmetric cipher algorithm. [RFC 4357][1]
119 specifies several parameters for the GOST 28147-89 algorithm, but OpenSSL
120 doesn't provide user interface to choose one when encrypting. So use engine
121 configuration parameter instead. It SHOULD NOT be used nowadays because all
122 the parameters except the default one are deprecated now.
124 Value of this parameter can be either short name, defined in OpenSSL
125 `obj_dat.h` header file or numeric representation of OID, defined in
128 [1]:https://tools.ietf.org/html/rfc4357 "RFC 4357"