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.
11 GOST R 34.10-2001 and GOST R 34.10-2012 - 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.
18 GOST R 34.11-2012 Message digest algorithm. 256- and 512-bit hash values.
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).
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).
31 Really, this algorithm supports from 8 to 64 bits of the MAC value
33 It is implemented as combination of EVP_PKEY type and EVP_MD type.
35 GOST R 34.13–2015 - Symmetric cypher Grasshopper ("Kuznechik")
37 USAGE OF THESE ALGORITHMS
39 This engine is designed to allow usage of this algorithms in the
40 high-level openssl functions, such as PKI, S/MIME and TLS.
42 See RFC 4490 for S/MIME with GOST algorithms and RFC 4491 for PKI.
43 TLS support is implemented according IETF
44 draft-chudov-cryptopro-cptls-03.txt and is compatible with
45 CryptoPro CSP 3.0 and 3.6 as well as with MagPro CSP.
46 GOST ciphersuites implemented in CryptoPro CSP 2.0 are not supported
47 because they use ciphersuite numbers used now by AES ciphersuites.
49 To use the engine you have to load it via openssl configuration
50 file. Applications should read openssl configuration file or provide
51 their own means to load engines. Also, applications which operate with
52 private keys, should use generic EVP_PKEY API instead of using RSA or
53 other algorithm-specific API.
57 Configuration file should include following statement in the global
58 section, i.e. before first bracketed section header (see config(5) for details)
60 openssl_conf = openssl_def
62 where openssl_def is name of the section in configuration file which
63 describes global defaults.
65 This section should contain following statement:
68 engines = engine_section
70 which points to the section which describes list of the engines to be
71 loaded. This section should contain:
76 And section which describes configuration of the engine should contain
80 dynamic_path = /usr/lib/ssl/engines/libgost.so
81 default_algorithms = ALL
82 CRYPT_PARAMS = id-Gost28147-89-CryptoPro-A-ParamSet
84 BouncyCastle cryptoprovider has some problems with private key parsing from PrivateKeyInfo,
85 so if you want to use old private key representation format, which supported by BC,
87 PK_PARAMS = LEGACY_PK_WRAP
90 Where engine_id parameter specifies name of engine (should be "gost").
91 dynamic_path is a location of the loadable shared library implementing the
92 engine. If the engine is compiled statically or is located in the OpenSSL
93 engines directory, this line can be omitted.
94 default_algorithms parameter specifies that all algorithms, provided by
95 engine, should be used.
97 The CRYPT_PARAMS parameter is engine-specific. It allows the user to choose
98 between different parameter sets of symmetric cipher algorithm. RFC 4357
99 specifies several parameters for the GOST 28147-89 algorithm, but OpenSSL
100 doesn't provide user interface to choose one when encrypting. So use engine
101 configuration parameter instead.
103 Value of this parameter can be either short name, defined in OpenSSL
104 obj_dat.h header file or numeric representation of OID, defined in RFC
107 USAGE WITH COMMAND LINE openssl UTILITY
109 1. Generation of private key
111 openssl genpkey -algorithm gost2001 -pkeyopt paramset:A -out seckey.pem
113 Use -algorithm option to specify algorithm.
114 Use -pkeyopt option to pass paramset to algorithm. The following paramsets
116 gost94: 0,A,B,C,D,XA,XB,XC
117 gost2001: 0,A,B,C,XA,XB
118 You can also use numeric representation of OID as to destinate
121 Paramsets starting with X are intended to use for key exchange keys.
122 Paramsets without X are for digital signature keys.
124 Paramset for both algorithms 0 is the test paramset which should be used
125 only for test purposes.
127 There are no algorithm-specific things with generation of certificate
128 request once you have a private key.
130 2. Generation of certificate request along with private/public keypar
132 openssl req -newkey gost2001 -pkeyopt paramset:A
134 Syntax of -pkeyopt parameter is identical with genpkey command.
136 You can also use oldstyle syntax -newkey gost2001:paramfile, but in
137 this case you should create parameter file first.
139 It can be created with
141 openssl genpkey -genparam -algorithm gost2001 -pkeyopt paramset:A\
146 If you want to send encrypted mail using GOST algorithms, don't forget
147 to specify -gost89 as encryption algorithm for OpenSSL smime command.
148 While OpenSSL is clever enough to find out that GOST R 34.11-94 digest
149 must be used for digital signing with GOST private key, it have no way
150 to derive symmetric encryption algorithm from key exchange keys.
154 OpenSSL supports all four ciphersuites defined in the IETF draft.
155 Once you've loaded GOST key and certificate into your TLS server,
156 ciphersuites which use GOST 28147-89 encryption are enabled.
158 Ciphersuites with NULL encryption should be enabled explicitely if
161 GOST2001-GOST89-GOST89 Uses GOST R 34.10-2001 for auth and key exchange
162 GOST 28147-89 for encryption and GOST 28147-89 MAC
163 GOST94-GOST89-GOST89 Uses GOST R 34.10-94 for auth and key exchange
164 GOST 28147-89 for encryption and GOST 28147-89 MAC
165 GOST2001-NULL-GOST94 Uses GOST R 34.10-2001 for auth and key exchange,
166 no encryption and HMAC, based on GOST R 34.11-94
167 GOST94-NULL-GOST94 Uses GOST R 34.10-94 for auth and key exchange,
168 no encryption and HMAC, based on GOST R 34.11-94
170 Gost 94 and gost 2001 keys can be used simultaneously in the TLS server.
171 RSA, DSA and EC keys can be used simultaneously with GOST keys, if
172 server implementation supports loading more than two private
173 key/certificate pairs. In this case ciphersuites which use any of loaded
174 keys would be supported and clients can negotiate ones they wish.
176 This allows creation of TLS servers which use GOST ciphersuites for
177 Russian clients and RSA/DSA ciphersuites for foreign clients.
179 5. Calculation of digests and symmetric encryption
180 OpenSSL provides specific commands (like sha1, aes etc) for calculation
181 of digests and symmetric encryption. Since such commands cannot be
182 added dynamically, no such commands are provided for GOST algorithms.
183 Use generic commands 'dgst' and 'enc'.
185 Calculation of GOST R 34.11-94 message digest
187 openssl dgst -md_gost94 datafile
189 Note that GOST R 34.11-94 specifies that digest value should be
190 interpreted as little-endian number, but OpenSSL outputs just hex dump
193 So, to obtain correct digest value, such as produced by gostsum utility
194 included in the engine distribution, bytes of output should be
197 Calculation of HMAC based on GOST R 34.11-94
199 openssl dgst -md_gost94 -mac hmac -macopt key:<32 bytes of key> datafile
201 (or use hexkey if key contain NUL bytes)
202 Calculation of GOST 28147 MAC
204 openssl dgst -mac gost-mac -macopt key:<32 bytes of key> datafile
206 Note absence of an option that specifies digest algorithm. gost-mac
207 algorithm supports only one digest (which is actually part of
208 implementation of this mac) and OpenSSL is clever enough to find out
211 Following mac options are supported:
213 key:(32 bytes of key)
215 hexkey:(64 hexadecimal digits of key)
217 Engine support calculation of mac with size different from default 32
218 bits. You can set mac size to any value from 1 to 8 bytes using
220 -sigopt size:(number from 1 to 8 - mac size in bytes)
222 (dgst command uses different EVP_PKEY_CTX for initialization and for
223 finalization of MAC. Option of first are set via -macopt, and for
224 second via -sigopt. Key should be set during initialization and size
225 during finalization. If you use API functions
226 EVP_DigestSignInit/EVP_DigestSignFinal, you can set both options at
229 Encryption with GOST 28147 CFB mode
230 openssl enc -gost89 -out encrypted-file -in plain-text-file -k <passphrase>
231 Encryption with GOST 28147 CNT mode
232 openssl enc -gost89-cnt -out encrypted-file -in plain-text-file -k <passphrase>
233 Encryption with GOST 28147 CBC mode
234 openssl enc -gost89-cbc -out encrypted-file -in plain-text-file -k <passphrase>
236 6. Encrypting private keys and PKCS12
238 To produce PKCS12 files compatible with MagPro CSP, you need to use
239 GOST algorithm for encryption of PKCS12 file and also GOST R 34.11-94
240 hash to derive key from password.
242 openssl pksc12 -export -inkey gost.pem -in gost_cert.pem -keypbe gost89\
243 -certpbe gost89 -macalg md_gost94
245 7. Testing speed of symmetric ciphers.
247 To test performance of GOST symmetric ciphers you should use -evp switch
248 of the openssl speed command. Engine-provided ciphers couldn't be
249 accessed by cipher-specific functions, only via generic evp interface
251 openssl speed -evp gost89
252 openssl speed -evp gost89-cnt
253 openssl speed -evp gost89-cbc
256 PROGRAMMING INTERFACES DETAILS
258 Applications never should access engine directly. They only use provided
259 EVP_PKEY API. But there are some details, which should be taken into
262 EVP provides two kinds of API for key exchange:
264 1. EVP_PKEY_encrypt/EVP_PKEY_decrypt functions, intended to use with
265 RSA-like public key encryption algorithms
267 2. EVP_PKEY_derive, intended to use with Diffie-Hellman-like shared key
268 computing algorithms.
270 Although VKO R 34.10 algorithms, described in the RFC 4357 are
271 definitely second case, engine provides BOTH API for GOST R 34.10 keys.
273 EVP_PKEY_derive just invokes appropriate VKO algorithm and computes
274 256 bit shared key. VKO R 34.10-2001 requires 64 bits of random user key
275 material (UKM). This UKM should be transmitted to other party, so it is
276 not generated inside derive function.
278 It should be set by EVP_PKEY_CTX_ctrl function using
279 EVP_PKEY_CTRL_SET_IV command after call of EVP_PKEY_derive_init, but
280 before EVP_PKEY_derive.
281 unsigned char ukm[8];
283 EVP_PKEY_CTX_ctrl(ctx, -1, EVP_PKEY_OP_DERIVE, 8, ukm)
285 EVP_PKEY_encrypt encrypts provided session key with VKO shared key and
286 packs it into GOST key transport structure, described in the RFC 4490.
288 It typically uses ephemeral key pair to compute shared key and packs its
289 public part along with encrypted key. So, for most cases use of
290 EVP_PKEY_encrypt/EVP_PKEY_decrypt with GOST keys is almost same as with
293 However, if peerkey field in the EVP_PKEY_CTX structure is set (using
294 EVP_PKEY_derive_set_peerkey function) to EVP_PKEY structure which has private
295 key and uses same parameters as the public key from which this EVP_PKEY_CTX is
296 created, EVP_PKEY_encrypt will use this private key to compute shared key and
297 set ephemeral key in the GOST_key_transport structure to NULL. In this case
298 pkey and peerkey fields in the EVP_PKEY_CTX are used upside-down.
300 If EVP_PKEY_decrypt encounters GOST_key_transport structure with NULL
301 public key field, it tries to use peerkey field from the context to
302 compute shared key. In this case peerkey field should really contain
305 Encrypt operation supports EVP_PKEY_CTRL_SET_IV operation as well.
306 It can be used when some specific restriction on UKM are imposed by
307 higher level protocol. For instance, description of GOST ciphersuites
308 requires UKM to be derived from shared secret.
310 If UKM is not set by this control command, encrypt operation would
314 This sources include implementation of GOST 28147-89 and GOST R 34.11-94
315 which are completely indepentent from OpenSSL and can be used separately
316 (files gost89.c, gost89.h, gosthash.c, gosthash.h) Utility gostsum (file
317 gostsum.c) is provided as example of such separate usage. This is
318 program, simular to md5sum and sha1sum utilities, but calculates GOST R
321 Makefile doesn't include rule for compiling gostsum.
324 $(CC) -o gostsum gostsum.c gost89.c gosthash.c
325 where $(CC) is name of your C compiler.
327 Implementations of GOST R 34.10-xx, including VKO algorithms heavily
328 depends on OpenSSL BIGNUM and Elliptic Curve libraries.