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 1.1.1
  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
  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
  27 OpenSSL 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     CRYPT_PARAMS = id-Gost28147-89-CryptoPro-A-ParamSet
 100
 101 BouncyCastle cryptoprovider has some problems with private key parsing from
 102 PrivateKeyInfo, so if you want to use old private key representation format,
 103 which supported by BC, you must add:
 104
 105     PK_PARAMS = LEGACY_PK_WRAP
 106
 107 to `[gost_section]`.
 108
 109 Where `engine_id` parameter specifies name of engine (should be `gost`).
 110
 111 `dynamic_path is` a location of the loadable shared library implementing the
 112 engine. If the engine is compiled statically or is located in the OpenSSL
 113 engines directory, this line can be omitted.
 114
 115 `default_algorithms` parameter specifies that all algorithms, provided by
 116 engine, should be used.
 117
 118 The `CRYPT_PARAMS` parameter is engine-specific. It allows the user to choose
 119 between different parameter sets of symmetric cipher algorithm. [RFC 4357][1]
 120 specifies several parameters for the GOST 28147-89 algorithm, but OpenSSL
 121 doesn't provide user interface to choose one when encrypting. So use engine
 122 configuration parameter instead.
 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"