1GOST ENGINE 2 3This engine provides implementation of Russian cryptography standard. 4This is also an example of adding new cryptoalgorithms into OpenSSL 5without changing its core. If OpenSSL is compiled with dynamic engine 6support, new algorithms can be added even without recompilation of 7OpenSSL and applications which use it. 8 9ALGORITHMS SUPPORTED 10 11GOST 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 18GOST R 34.11-94 Message digest algorithm. 256-bit hash value 19 20GOST 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 25GOST 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 33USAGE OF THESE ALGORITHMS 34 35This engine is designed to allow usage of this algorithms in the 36high-level openssl functions, such as PKI, S/MIME and TLS. 37 38See RFC 4490 for S/MIME with GOST algorithms and RFC 4491 for PKI. 39TLS support is implemented according IETF 40draft-chudov-cryptopro-cptls-03.txt and is compatible with 41CryptoPro CSP 3.0 and 3.6 as well as with MagPro CSP. 42GOST ciphersuites implemented in CryptoPro CSP 2.0 are not supported 43because they use ciphersuite numbers used now by AES ciphersuites. 44 45To use the engine you have to load it via openssl configuration 46file. Applications should read openssl configuration file or provide 47their own means to load engines. Also, applications which operate with 48private keys, should use generic EVP_PKEY API instead of using RSA or 49other algorithm-specific API. 50 51CONFIGURATION FILE 52 53Configuration file should include following statement in the global 54section, i.e. before first bracketed section header (see config(5) for details) 55 56 openssl_conf = openssl_def 57 58where openssl_def is name of the section in configuration file which 59describes global defaults. 60 61This section should contain following statement: 62 63 [openssl_def] 64 engines = engine_section 65 66which points to the section which describes list of the engines to be 67loaded. This section should contain: 68 69 [engine_section] 70 gost = gost_section 71 72And 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 80Where engine_id parameter specifies name of engine (should be "gost"). 81dynamic_path is a location of the loadable shared library implementing the 82engine. If the engine is compiled statically or is located in the OpenSSL 83engines directory, this line can be omitted. 84default_algorithms parameter specifies that all algorithms, provided by 85engine, should be used. 86 87The CRYPT_PARAMS parameter is engine-specific. It allows the user to choose 88between different parameter sets of symmetric cipher algorithm. RFC 4357 89specifies several parameters for the GOST 28147-89 algorithm, but OpenSSL 90doesn't provide user interface to choose one when encrypting. So use engine 91configuration parameter instead. 92 93Value of this parameter can be either short name, defined in OpenSSL 94obj_dat.h header file or numeric representation of OID, defined in RFC 954357. 96 97USAGE WITH COMMAND LINE openssl UTILITY 98 991. 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 117There are no algorithm-specific things with generation of certificate 118request once you have a private key. 119 1202. 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 1343. S/MIME operations 135 136If you want to send encrypted mail using GOST algorithms, don't forget 137to specify -gost89 as encryption algorithm for OpenSSL smime command. 138While OpenSSL is clever enough to find out that GOST R 34.11-94 digest 139must be used for digital signing with GOST private key, it have no way 140to derive symmetric encryption algorithm from key exchange keys. 141 1424. TLS operations 143 144OpenSSL supports all four ciphersuites defined in the IETF draft. 145Once you've loaded GOST key and certificate into your TLS server, 146ciphersuites which use GOST 28147-89 encryption are enabled. 147 148Ciphersuites with NULL encryption should be enabled explicitely if 149needed. 150 151GOST2001-GOST89-GOST89 Uses GOST R 34.10-2001 for auth and key exchange 152 GOST 28147-89 for encryption and GOST 28147-89 MAC 153GOST94-GOST89-GOST89 Uses GOST R 34.10-94 for auth and key exchange 154 GOST 28147-89 for encryption and GOST 28147-89 MAC 155GOST2001-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 157GOST94-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 160Gost 94 and gost 2001 keys can be used simultaneously in the TLS server. 161RSA, DSA and EC keys can be used simultaneously with GOST keys, if 162server implementation supports loading more than two private 163key/certificate pairs. In this case ciphersuites which use any of loaded 164keys would be supported and clients can negotiate ones they wish. 165 166This allows creation of TLS servers which use GOST ciphersuites for 167Russian clients and RSA/DSA ciphersuites for foreign clients. 168 1695. 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 2076. Encrypting private keys and PKCS12 208 209To produce PKCS12 files compatible with MagPro CSP, you need to use 210GOST algorithm for encryption of PKCS12 file and also GOST R 34.11-94 211hash to derive key from password. 212 213openssl pksc12 -export -inkey gost.pem -in gost_cert.pem -keypbe gost89\ 214 -certpbe gost89 -macalg md_gost94 215 2167. Testing speed of symmetric ciphers. 217 218To test performance of GOST symmetric ciphers you should use -evp switch 219of the openssl speed command. Engine-provided ciphers couldn't be 220accessed by cipher-specific functions, only via generic evp interface 221 222 openssl speed -evp gost89 223 openssl speed -evp gost89-cnt 224 225 226PROGRAMMING INTERFACES DETAILS 227 228Applications never should access engine directly. They only use provided 229EVP_PKEY API. But there are some details, which should be taken into 230account. 231 232EVP provides two kinds of API for key exchange: 233 2341. EVP_PKEY_encrypt/EVP_PKEY_decrypt functions, intended to use with 235 RSA-like public key encryption algorithms 236 2372. EVP_PKEY_derive, intended to use with Diffie-Hellman-like shared key 238computing algorithms. 239 240Although VKO R 34.10 algorithms, described in the RFC 4357 are 241definitely second case, engine provides BOTH API for GOST R 34.10 keys. 242 243EVP_PKEY_derive just invokes appropriate VKO algorithm and computes 244256 bit shared key. VKO R 34.10-2001 requires 64 bits of random user key 245material (UKM). This UKM should be transmitted to other party, so it is 246not generated inside derive function. 247 248It should be set by EVP_PKEY_CTX_ctrl function using 249EVP_PKEY_CTRL_SET_IV command after call of EVP_PKEY_derive_init, but 250before 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 255EVP_PKEY_encrypt encrypts provided session key with VKO shared key and 256packs it into GOST key transport structure, described in the RFC 4490. 257 258It typically uses ephemeral key pair to compute shared key and packs its 259public part along with encrypted key. So, for most cases use of 260EVP_PKEY_encrypt/EVP_PKEY_decrypt with GOST keys is almost same as with 261RSA. 262 263However, if peerkey field in the EVP_PKEY_CTX structure is set (using 264EVP_PKEY_derive_set_peerkey function) to EVP_PKEY structure which has private 265key and uses same parameters as the public key from which this EVP_PKEY_CTX is 266created, EVP_PKEY_encrypt will use this private key to compute shared key and 267set ephemeral key in the GOST_key_transport structure to NULL. In this case 268pkey and peerkey fields in the EVP_PKEY_CTX are used upside-down. 269 270If EVP_PKEY_decrypt encounters GOST_key_transport structure with NULL 271public key field, it tries to use peerkey field from the context to 272compute shared key. In this case peerkey field should really contain 273peer public key. 274 275Encrypt operation supports EVP_PKEY_CTRL_SET_IV operation as well. 276It can be used when some specific restriction on UKM are imposed by 277higher level protocol. For instance, description of GOST ciphersuites 278requires UKM to be derived from shared secret. 279 280If UKM is not set by this control command, encrypt operation would 281generate random UKM. 282 283 284This sources include implementation of GOST 28147-89 and GOST R 34.11-94 285which are completely indepentent from OpenSSL and can be used separately 286(files gost89.c, gost89.h, gosthash.c, gosthash.h) Utility gostsum (file 287gostsum.c) is provided as example of such separate usage. This is 288program, simular to md5sum and sha1sum utilities, but calculates GOST R 28934.11-94 hash. 290 291Makefile doesn't include rule for compiling gostsum. 292Use command 293 294$(CC) -o gostsum gostsum.c gost89.c gosthash.c 295where $(CC) is name of your C compiler. 296 297Implementations of GOST R 34.10-xx, including VKO algorithms heavily 298depends on OpenSSL BIGNUM and Elliptic Curve libraries. 299 300 301