README.gost

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