README.gost

   1 OPENSSL GOST ENGINE
   2
   3 An implementation of Russian cryptography standards for OpenSSL.
   4
   5 Since v.1.0.0 OpenSSL provides facilities for creating external
   6 dynamically loaded cryptographic engines (OpenSSL should be built
   7 with dynamic engine support to be able to use it).
   8
   9 This engine provides an implementation of various Russian cryptographic
  10 algorithms, known generally as GOST cryptographic algorithms (see detailed
  11 list below). These algorithms, can be used both via OpenSSL command line
  12 tools and via high-level libopenssl calls.
  13
  14 OpenSSL GOST Engine also includes gostsum и gost12sum command line tools,
  15 for generating and checking GOST R34.11-94 and GOST R34.11-2012 hash sums.
  16 They have the same purposes and behavior as well known sha1sum and md5sum
  17 utilities.
  18
  19 ALGORITHMS SUPPORTED
  20
  21 GOST R 34.10-2001 and GOST R 34.10-2012 - digital signature algorithms.
  22    Also support key exchange based on public keys. See RFC 4357 for
  23    details of VKO key exchange algorithm. These algorithms use
  24    256 bit private keys. Public keys are 1024 bit for 94 and 512 bit for
  25    2001 (which is elliptic-curve based). Key exchange algorithms
  26    (VKO R 34.10) are supported on these keys too.
  27
  28 GOST R 34.11-2012  Message digest algorithm. 256- and 512-bit hash values.
  29
  30 GOST 28147-89 - Symmetric cipher  with 256-bit key. Various modes are
  31    defined in the standard, but only CFB and CNT modes are implemented
  32    in the engine. To make statistical analysis more difficult, key
  33    meshing is supported (see RFC 4357).
  34
  35 GOST 28147-89 MAC mode. Message authentication code. While most MAC
  36     algorithms  out there are based on hash functions using HMAC
  37         algorithm, this algoritm is based on symmetric cipher.
  38         It has 256-bit symmetric key and only 32 bits of MAC value
  39         (while HMAC has same key size and value size).
  40
  41         Really, this algorithm supports from 8 to 64 bits of the MAC value
  42
  43         It is implemented as combination of EVP_PKEY type and EVP_MD type.
  44
  45 GOST R 34.13–2015 - Symmetric cypher Grasshopper ("Kuznechik")
  46
  47 USAGE OF THESE ALGORITHMS
  48
  49 This engine is designed to allow usage of this algorithms in the
  50 high-level openssl functions, such as PKI, S/MIME and TLS.
  51
  52 See RFC 4490 for S/MIME with GOST algorithms and RFC 4491 for PKI.
  53 TLS support is implemented according IETF
  54 draft-chudov-cryptopro-cptls-03.txt and is compatible with
  55 CryptoPro CSP 3.0 and 3.6 as well as with MagPro CSP.
  56 GOST ciphersuites implemented in CryptoPro CSP 2.0 are not supported
  57 because they use ciphersuite numbers used now by AES ciphersuites.
  58
  59 To use the engine you have to load it via openssl configuration
  60 file. Applications should read openssl configuration file or provide
  61 their own means to load engines. Also, applications which operate with
  62 private keys, should use generic EVP_PKEY API instead of using RSA or
  63 other algorithm-specific API.
  64
  65 CONFIGURATION FILE
  66
  67 Configuration file should include following statement in the global
  68 section, i.e. before first bracketed section header (see config(5) for details)
  69
  70    openssl_conf = openssl_def
  71
  72 where openssl_def is name of the section in configuration file which
  73 describes global defaults.
  74
  75 This section should contain following statement:
  76
  77    [openssl_def]
  78    engines = engine_section
  79
  80 which points to the section which describes list of the engines to be
  81 loaded. This section should contain:
  82
  83         [engine_section]
  84         gost = gost_section
  85
  86 And section which describes configuration of the engine should contain
  87
  88         [gost_section]
  89         engine_id = gost
  90         dynamic_path = /usr/lib/ssl/engines/libgost.so
  91         default_algorithms = ALL
  92         CRYPT_PARAMS = id-Gost28147-89-CryptoPro-A-ParamSet
  93
  94 BouncyCastle cryptoprovider has some problems with private key parsing from PrivateKeyInfo,
  95 so if you want to use old private key representation format, which supported by BC,
  96 you must add:
  97   PK_PARAMS = LEGACY_PK_WRAP
  98 to [gost_section]
  99
 100 Where engine_id parameter specifies name of engine (should be "gost").
 101 dynamic_path is a location of the loadable shared library implementing the
 102 engine. If the engine is compiled statically or is located in the OpenSSL
 103 engines directory, this line can be omitted.
 104 default_algorithms parameter specifies that all algorithms, provided by
 105 engine, should be used.
 106
 107 The CRYPT_PARAMS parameter is engine-specific. It allows the user to choose
 108 between different parameter sets of symmetric cipher algorithm. RFC 4357
 109 specifies several parameters for the GOST 28147-89 algorithm, but OpenSSL
 110 doesn't provide user interface to choose one when encrypting. So use engine
 111 configuration parameter instead.
 112
 113 Value of this parameter can be either short name, defined in OpenSSL
 114 obj_dat.h header file or numeric representation of OID, defined in RFC
 115 4357.
 116
 117 USAGE WITH COMMAND LINE openssl UTILITY
 118
 119 1. Generation of private key
 120
 121         openssl genpkey -algorithm gost2001 -pkeyopt paramset:A -out seckey.pem
 122
 123   Use -algorithm option to specify algorithm.
 124   Use -pkeyopt option to pass paramset to algorithm. The following paramsets
 125   are supported by
 126         gost94: 0,A,B,C,D,XA,XB,XC
 127         gost2001: 0,A,B,C,XA,XB
 128   You can also use numeric representation of OID as to destinate
 129   paramset.
 130
 131   Paramsets starting with X are intended to use for key exchange keys.
 132   Paramsets without X are for digital signature keys.
 133
 134   Paramset for both algorithms 0 is the test paramset which should be used
 135   only for test purposes.
 136
 137 There are no algorithm-specific things with generation of certificate
 138 request once you have a private key.
 139
 140 2. Generation of certificate request along with private/public keypar
 141
 142    openssl req -newkey gost2001 -pkeyopt paramset:A
 143
 144    Syntax of -pkeyopt parameter is identical with genpkey command.
 145
 146    You can also use oldstyle syntax -newkey gost2001:paramfile, but in
 147    this case you should create parameter file first.
 148
 149    It can be created with
 150
 151    openssl genpkey -genparam -algorithm gost2001 -pkeyopt paramset:A\
 152       -out paramfile.
 153
 154 3. S/MIME operations
 155
 156 If you want to send encrypted mail using GOST algorithms, don't forget
 157 to specify -gost89 as encryption algorithm for OpenSSL smime command.
 158 While OpenSSL is clever enough to find out that GOST R 34.11-94 digest
 159 must be used for digital signing with GOST private key, it have no way
 160 to derive symmetric encryption algorithm from key exchange keys.
 161
 162 4. TLS operations
 163
 164 OpenSSL supports all four ciphersuites defined in the IETF draft.
 165 Once you've loaded GOST key and certificate into your TLS server,
 166 ciphersuites which use GOST 28147-89 encryption are enabled.
 167
 168 Ciphersuites with NULL encryption should be enabled explicitely if
 169 needed.
 170
 171 GOST2001-GOST89-GOST89 Uses GOST R 34.10-2001 for auth and key exchange
 172                 GOST 28147-89 for encryption and GOST 28147-89 MAC
 173 GOST94-GOST89-GOST89 Uses GOST R 34.10-94 for auth and key exchange
 174                 GOST 28147-89 for encryption and GOST 28147-89 MAC
 175 GOST2001-NULL-GOST94 Uses GOST R 34.10-2001 for auth and key exchange,
 176         no encryption and HMAC, based on GOST R 34.11-94
 177 GOST94-NULL-GOST94 Uses GOST R 34.10-94 for auth and key exchange,
 178         no encryption and HMAC, based on GOST R 34.11-94
 179
 180 Gost 94 and gost 2001 keys can be used simultaneously in the TLS server.
 181 RSA, DSA and EC keys can be used simultaneously with GOST keys, if
 182 server implementation supports loading more than two private
 183 key/certificate pairs. In this case ciphersuites which use any of loaded
 184 keys would be supported and clients can negotiate ones they wish.
 185
 186 This allows creation of TLS servers which use GOST ciphersuites for
 187 Russian clients and RSA/DSA ciphersuites for foreign clients.
 188
 189 5. Calculation of digests and symmetric encryption
 190  OpenSSL provides specific commands (like sha1, aes etc) for calculation
 191  of digests and symmetric encryption. Since such commands cannot be
 192  added dynamically, no such commands are provided for GOST algorithms.
 193  Use generic commands 'dgst' and 'enc'.
 194
 195  Calculation of GOST R 34.11-94 message digest
 196
 197  openssl dgst -md_gost94 datafile
 198
 199  Note that GOST R 34.11-94 specifies that digest value should be
 200  interpreted as little-endian number, but OpenSSL outputs just hex dump
 201  of digest value.
 202
 203  So, to obtain correct digest value, such as produced by gostsum utility
 204  included in the engine distribution, bytes of output should be
 205  reversed.
 206
 207  Calculation of HMAC based on GOST R 34.11-94
 208
 209  openssl dgst -md_gost94 -mac hmac -macopt key:<32 bytes of key> datafile
 210
 211   (or use hexkey if key contain NUL bytes)
 212  Calculation of GOST 28147 MAC
 213
 214  openssl dgst -mac gost-mac -macopt key:<32 bytes of key> datafile
 215
 216  Note absence of an option that specifies digest algorithm. gost-mac
 217  algorithm supports only one digest (which is actually part of
 218  implementation of this mac) and OpenSSL is clever enough to find out
 219  this.
 220
 221  Following mac options are supported:
 222
 223  key:(32 bytes of key)
 224
 225  hexkey:(64 hexadecimal digits of key)
 226
 227  Engine support calculation of mac with size different from default 32
 228  bits. You can set mac size to any value from 1 to 8 bytes using
 229
 230  -sigopt size:(number from 1 to 8 - mac size in bytes)
 231
 232  (dgst command uses different EVP_PKEY_CTX for initialization and for
 233   finalization of MAC. Option of first are set via -macopt, and for
 234   second via -sigopt. Key should be set during initialization and size
 235   during finalization. If you use API functions
 236   EVP_DigestSignInit/EVP_DigestSignFinal, you can set both options at
 237   the same time).
 238
 239  Encryption with GOST 28147 CFB mode
 240  openssl enc -gost89 -out encrypted-file -in plain-text-file -k <passphrase>
 241  Encryption with GOST 28147 CNT mode
 242  openssl enc -gost89-cnt -out encrypted-file -in plain-text-file -k <passphrase>
 243  Encryption with GOST 28147 CBC mode
 244  openssl enc -gost89-cbc -out encrypted-file -in plain-text-file -k <passphrase>
 245
 246 6. Encrypting private keys and PKCS12
 247
 248 To produce PKCS12 files compatible with MagPro CSP, you need to use
 249 GOST algorithm for encryption of PKCS12 file and also GOST R 34.11-94
 250 hash to derive key from password.
 251
 252 openssl pksc12 -export -inkey gost.pem -in gost_cert.pem -keypbe gost89\
 253    -certpbe gost89 -macalg md_gost94
 254
 255 7. Testing speed of symmetric ciphers.
 256
 257 To test performance of GOST symmetric ciphers you should use -evp switch
 258 of the openssl speed command. Engine-provided ciphers couldn't be
 259 accessed by cipher-specific functions, only via generic evp interface
 260
 261  openssl speed -evp gost89
 262  openssl speed -evp gost89-cnt
 263  openssl speed -evp gost89-cbc
 264
 265
 266 PROGRAMMING INTERFACES DETAILS
 267
 268 Applications never should access engine directly. They only use provided
 269 EVP_PKEY API. But there are some details, which should be taken into
 270 account.
 271
 272 EVP provides two kinds of API for key exchange:
 273
 274 1. EVP_PKEY_encrypt/EVP_PKEY_decrypt functions, intended to use with
 275         RSA-like public key encryption algorithms
 276
 277 2. EVP_PKEY_derive, intended to use with Diffie-Hellman-like shared key
 278 computing algorithms.
 279
 280 Although VKO R 34.10 algorithms, described in the RFC 4357 are
 281 definitely second case, engine provides BOTH API for GOST R 34.10 keys.
 282
 283 EVP_PKEY_derive just invokes appropriate VKO algorithm and computes
 284 256 bit shared key. VKO R 34.10-2001 requires 64 bits of random user key
 285 material (UKM). This UKM should be transmitted to other party, so it is
 286 not generated inside derive function.
 287
 288 It should be set by EVP_PKEY_CTX_ctrl function using
 289 EVP_PKEY_CTRL_SET_IV command after call of EVP_PKEY_derive_init, but
 290 before EVP_PKEY_derive.
 291         unsigned char ukm[8];
 292         RAND_bytes(ukm,8);
 293    EVP_PKEY_CTX_ctrl(ctx, -1, EVP_PKEY_OP_DERIVE, 8, ukm)
 294
 295 EVP_PKEY_encrypt encrypts provided session key with VKO shared key and
 296 packs it into GOST key transport structure, described in the RFC 4490.
 297
 298 It typically uses ephemeral key pair to compute shared key and packs its
 299 public part along with encrypted key. So, for most cases use of
 300 EVP_PKEY_encrypt/EVP_PKEY_decrypt with GOST keys is almost same as with
 301 RSA.
 302
 303 However, if peerkey field in the EVP_PKEY_CTX structure is set (using
 304 EVP_PKEY_derive_set_peerkey function) to EVP_PKEY structure which has private
 305 key and uses same parameters as the public key from which this EVP_PKEY_CTX is
 306 created, EVP_PKEY_encrypt will use this private key to compute shared key and
 307 set ephemeral key in the GOST_key_transport structure to NULL. In this case
 308 pkey and peerkey fields in the EVP_PKEY_CTX are used upside-down.
 309
 310 If EVP_PKEY_decrypt encounters GOST_key_transport structure with NULL
 311 public key field, it tries to use peerkey field from the context to
 312 compute shared key. In this case peerkey field should really contain
 313 peer public key.
 314
 315 Encrypt operation supports EVP_PKEY_CTRL_SET_IV operation as well.
 316 It can be used when some specific restriction on UKM are imposed by
 317 higher level protocol. For instance, description of GOST ciphersuites
 318 requires UKM to be derived from shared secret.
 319
 320 If UKM is not set by this control command, encrypt operation would
 321 generate random UKM.