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