INSTALL.md

   1 Building and Installation
   2 =========================
   3
   4 How to Build
   5 ------------
   6
   7 To build and install OpenSSL GOST Engine, you will need
   8
   9 * OpenSSL 3.0 development version
  10 * an ANSI C compiler
  11 * CMake (3.0 or newer, 3.18 recommended)
  12
  13 Here is a quick build guide:
  14
  15     $ git clone https://github.com/gost-engine/engine
  16     $ cd engine
  17     $ git submodule update --init
  18     $ mkdir build
  19     $ cd build
  20     $ cmake -DCMAKE_BUILD_TYPE=Release ..
  21     $ cmake --build . --config Release
  22
  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.
  26
  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
  30 instance:
  31
  32     $ cmake -DOPENSSL_ROOT_DIR=/PATH/TO/OPENSSL/ ..
  33
  34 Building against OpenSSL 3.0 requires openssl detection module
  35 (FindOpenSSL.cmake) from CMake 3.18 or higher. More earlier versions may have
  36 problems with it.
  37
  38 If you use Visual Studio, you can also set `CMAKE_INSTALL_PREFIX` variable
  39 to set install path, like this:
  40
  41     > cmake -G "Visual Studio 15 Win64" -DCMAKE_PREFIX_PATH=c:\OpenSSL\vc-win64a\ -DCMAKE_INSTALL_PREFIX=c:\OpenSSL\vc-win64a\ ..
  42
  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.
  45
  46 Instructions how to build OpenSSL 1.1.0 with Microsoft Visual Studio
  47 you can find [there](https://gist.github.com/terrillmoore/995421ea6171a9aa50552f6aa4be0998).
  48
  49 How to Install
  50 --------------
  51
  52 To install GOST Engine you can call:
  53
  54     # cmake --build . --target install --config Release
  55
  56 or old plain and Unix only:
  57
  58     # make install
  59
  60 The engine library `gost.so` should be installed into OpenSSL engine directory.
  61
  62 To ensure that it is installed propery call:
  63
  64     $ openssl version -e
  65     ENGINESDIR: "/usr/lib/i386-linux-gnu/engines-1.1"
  66
  67 Then check that `gost.so` there
  68
  69     # ls /usr/lib/i386-linux-gnu/engines-1.1
  70
  71 Finally, to start using GOST Engine through OpenSSL, you should edit
  72 `openssl.cnf` configuration file as specified below.
  73
  74
  75 How to Configure
  76 ----------------
  77
  78 The very minimal example of the configuration file is provided in this
  79 distribution and named `example.conf`.
  80
  81 Configuration file should include following statement in the global
  82 section, i.e. before first bracketed section header (see config(5) for details)
  83
  84     openssl_conf = openssl_def
  85
  86 where `openssl_def` is name of the section in configuration file which
  87 describes global defaults.
  88
  89 This section should contain following statement:
  90
  91     [openssl_def]
  92     engines = engine_section
  93
  94 which points to the section which describes list of the engines to be
  95 loaded. This section should contain:
  96
  97     [engine_section]
  98     gost = gost_section
  99
 100 And section which describes configuration of the engine should contain
 101
 102     [gost_section]
 103     engine_id = gost
 104     dynamic_path = /usr/lib/ssl/engines/libgost.so
 105     default_algorithms = ALL
 106
 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:
 110
 111     GOST_PK_FORMAT = LEGACY_PK_WRAP
 112
 113 to `[gost_section]`.
 114
 115 Where `engine_id` parameter specifies name of engine (should be `gost`).
 116
 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.
 120
 121 `default_algorithms` parameter specifies that all algorithms, provided by
 122 engine, should be used.
 123
 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.
 130
 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
 133 [RFC 4357][1].
 134
 135 [1]:https://tools.ietf.org/html/rfc4357 "RFC 4357"