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