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