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.*
  10 * an ANSI C compiler
  11 * CMake (2.8 or newer)
  12
  13 Here is a quick build guide:
  14
  15     $ mkdir build
  16     $ cd build
  17     $ cmake ..
  18     $ make
  19
  20 You will find built binaries in `../bin` directory.
  21
  22 If you want to build against a specific OpenSSL instance (you will need it
  23 if you have more than one OpenSSL instance for example), you can use
  24 the `cmake` variable `CMAKE_C_FLAGS` to specify path to include files and
  25 shared libraries of the desirable OpenSSL instance
  26
  27     $ cmake -DCMAKE_C_FLAGS='-I/PATH/TO/OPENSSL/include -L/PATH/TO/OPENSSL/lib' ..
  28
  29 If you use Visual Studio, see READMEWIN.txt for details.
  30
  31 How to Install
  32 --------------
  33
  34 For now OpenSSL GOST Engine does not have an installation script, so you have to
  35 do it manually.
  36
  37 Copy `gostsum` and `gost12sum` binaries to your binary directory. For example
  38 `/usr/local/bin`:
  39
  40     # cd ../bin
  41     # cp gostsum gost12sum /usr/local/bin
  42
  43 Then, if you like to install man files properly, you can do it as follows:
  44
  45     # cd ..
  46     # mkdir -p /usr/local/man/man1
  47     # cp gost12sum.1 gostsum.1 /usr/local/man/man1
  48
  49 The engine library `gost.so` should be installed into OpenSSL engine directory.
  50 Use the following command to get its name:
  51
  52     $ openssl version -e
  53     ENGINESDIR: "/usr/lib/i386-linux-gnu/engines-1.1"
  54
  55 Then simply copy `gost.so` there
  56
  57     # cp bin/gost.so /usr/lib/i386-linux-gnu/engines-1.1
  58
  59
  60 Finally, to start using GOST Engine through OpenSSL, you should edit
  61 `openssl.cnf` configuration file as specified below.
  62
  63
  64 How to Configure
  65 ----------------
  66
  67 The very minimal example of the configuration file is provided in this
  68 distribution and named `example.conf`.
  69
  70 Configuration file should include following statement in the global
  71 section, i.e. before first bracketed section header (see config(5) for details)
  72
  73     openssl_conf = openssl_def
  74
  75 where `openssl_def` is name of the section in configuration file which
  76 describes global defaults.
  77
  78 This section should contain following statement:
  79
  80     [openssl_def]
  81     engines = engine_section
  82
  83 which points to the section which describes list of the engines to be
  84 loaded. This section should contain:
  85
  86     [engine_section]
  87     gost = gost_section
  88
  89 And section which describes configuration of the engine should contain
  90
  91     [gost_section]
  92     engine_id = gost
  93     dynamic_path = /usr/lib/ssl/engines/libgost.so
  94     default_algorithms = ALL
  95     CRYPT_PARAMS = id-Gost28147-89-CryptoPro-A-ParamSet
  96
  97 BouncyCastle cryptoprovider has some problems with private key parsing from
  98 PrivateKeyInfo, so if you want to use old private key representation format,
  99 which supported by BC, you must add:
 100
 101     PK_PARAMS = LEGACY_PK_WRAP
 102
 103 to `[gost_section]`.
 104
 105 Where `engine_id` parameter specifies name of engine (should be `gost`).
 106
 107 `dynamic_path is` a location of the loadable shared library implementing the
 108 engine. If the engine is compiled statically or is located in the OpenSSL
 109 engines directory, this line can be omitted.
 110
 111 `default_algorithms` parameter specifies that all algorithms, provided by
 112 engine, should be used.
 113
 114 The `CRYPT_PARAMS` parameter is engine-specific. It allows the user to choose
 115 between different parameter sets of symmetric cipher algorithm. [RFC 4357][1]
 116 specifies several parameters for the GOST 28147-89 algorithm, but OpenSSL
 117 doesn't provide user interface to choose one when encrypting. So use engine
 118 configuration parameter instead.
 119
 120 Value of this parameter can be either short name, defined in OpenSSL
 121 `obj_dat.h` header file or numeric representation of OID, defined in
 122 [RFC 4357][1].
 123
 124 [1]:https://tools.ietf.org/html/rfc4357 "RFC 4357"