crypto/openssl/engines/ccgost/README.gost

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