3 An implementation of Russian cryptography standards for OpenSSL.
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.
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.
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.
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.
29 GOST R 34.11-94 Message digest algorithm. 256-bit hash value.
31 GOST R 34.11-2012 Message digest algorithm. 256- and 512-bit hash values.
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).
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.
45 GOST R 34.13–2015 - Symmetric cypher Grasshopper ("Kuznechik")
47 USAGE OF GOST ALGORITHMS
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.
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+.
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.
65 The very minimal example of the configuration file is provided in this
66 distribution and named 'example.conf'.
68 Configuration file should include following statement in the global
69 section, i.e. before first bracketed section header (see config(5) for details)
71 openssl_conf = openssl_def
73 where openssl_def is name of the section in configuration file which
74 describes global defaults.
76 This section should contain following statement:
79 engines = engine_section
81 which points to the section which describes list of the engines to be
82 loaded. This section should contain:
87 And section which describes configuration of the engine should contain
91 dynamic_path = /usr/lib/ssl/engines/libgost.so
92 default_algorithms = ALL
93 CRYPT_PARAMS = id-Gost28147-89-CryptoPro-A-ParamSet
95 BouncyCastle cryptoprovider has some problems with private key parsing from PrivateKeyInfo,
96 so if you want to use old private key representation format, which supported by BC,
98 PK_PARAMS = LEGACY_PK_WRAP
102 Where engine_id parameter specifies name of engine (should be "gost").
103 dynamic_path is a location of the loadable shared library implementing the
104 engine. If the engine is compiled statically or is located in the OpenSSL
105 engines directory, this line can be omitted.
106 default_algorithms parameter specifies that all algorithms, provided by
107 engine, should be used.
109 The CRYPT_PARAMS parameter is engine-specific. It allows the user to choose
110 between different parameter sets of symmetric cipher algorithm. RFC 4357
111 specifies several parameters for the GOST 28147-89 algorithm, but OpenSSL
112 doesn't provide user interface to choose one when encrypting. So use engine
113 configuration parameter instead.
115 Value of this parameter can be either short name, defined in OpenSSL
116 obj_dat.h header file or numeric representation of OID, defined in RFC
119 USAGE WITH COMMAND LINE openssl UTILITY
121 1. Generation of private key
123 openssl genpkey -algorithm gost2001 -pkeyopt paramset:A -out seckey.pem
125 Use -algorithm option to specify algorithm.
126 Use -pkeyopt option to pass paramset to algorithm. The following paramsets
128 gost2001: 0,A,B,C,XA,XB
129 gost2012_256: 0,A,B,C,XA,XB
131 You can also use numeric representation of OID as to destinate
134 Paramsets starting with X are intended to use for key exchange keys.
135 Paramsets without X are for digital signature keys.
137 Paramset for both algorithms 0 is the test paramset which should be used
138 only for test purposes.
140 There are no algorithm-specific things with generation of certificate
141 request once you have a private key.
143 2. Generation of certificate request along with private/public keypar
145 openssl req -newkey gost2001 -pkeyopt paramset:A
147 Syntax of -pkeyopt parameter is identical with genpkey command.
149 You can also use oldstyle syntax -newkey gost2001:paramfile, but in
150 this case you should create parameter file first.
152 It can be created with
154 openssl genpkey -genparam -algorithm gost2001 -pkeyopt paramset:A\
159 If you want to send encrypted mail using GOST algorithms, don't forget
160 to specify -gost89 as encryption algorithm for OpenSSL smime command.
161 While OpenSSL is clever enough to find out that GOST R 34.11-94 digest
162 must be used for digital signing with GOST private key, it have no way
163 to derive symmetric encryption algorithm from key exchange keys.
167 OpenSSL supports all four ciphersuites defined in the IETF draft.
168 Once you've loaded GOST key and certificate into your TLS server,
169 ciphersuites which use GOST 28147-89 encryption are enabled.
171 Ciphersuites with NULL encryption should be enabled explicitely if
174 GOST2001-GOST89-GOST89 Uses GOST R 34.10-2001 for auth and key exchange,
175 GOST 28147-89 for encryption and GOST 28147-89 MAC
176 GOST2001-NULL-GOST94 Uses GOST R 34.10-2001 for auth and key exchange,
177 no encryption and HMAC, based on GOST R 34.11-94
178 GOST2012-GOST8912-GOST8912 Uses GOST R 34.10-2001 or 2012 for auth and key exchange,
179 GOST 28147-89 with paramset Z for encryption and GOST 28147-89 MAC with paramset Z
180 GOST2012-NULL-GOST1 Uses GOST R 34.10-2001 or 2012 for auth and key exchange,
181 no encryption and HMAC, based on GOST R 34.11-2012 256-bit.
183 RSA, DSA and EC keys can be used simultaneously with GOST keys, if
184 server implementation supports loading more than two private
185 key/certificate pairs. In this case ciphersuites which use any of loaded
186 keys would be supported and clients can negotiate ones they wish.
188 This allows creation of TLS servers which use GOST ciphersuites for
189 Russian clients and RSA/DSA ciphersuites for foreign clients.
191 5. Calculation of digests and symmetric encryption
192 OpenSSL provides specific commands (like sha1, aes etc) for calculation
193 of digests and symmetric encryption. Since such commands cannot be
194 added dynamically, no such commands are provided for GOST algorithms.
195 Use generic commands 'dgst' and 'enc'.
197 Calculation of GOST R 34.11-94 message digest
199 openssl dgst -md_gost94 datafile
201 Note that GOST R 34.11-94 specifies that digest value should be
202 interpreted as little-endian number, but OpenSSL outputs just hex dump
205 So, to obtain correct digest value, such as produced by gostsum utility
206 included in the engine distribution, bytes of output should be
209 Calculation of HMAC based on GOST R 34.11-94
211 openssl dgst -md_gost94 -mac hmac -macopt key:<32 bytes of key> datafile
213 (or use hexkey if key contain NUL bytes)
214 Calculation of GOST 28147 MAC
216 openssl dgst -mac gost-mac -macopt key:<32 bytes of key> datafile
218 Note absence of an option that specifies digest algorithm. gost-mac
219 algorithm supports only one digest (which is actually part of
220 implementation of this mac) and OpenSSL is clever enough to find out
223 Following mac options are supported:
225 key:(32 bytes of key)
227 hexkey:(64 hexadecimal digits of key)
229 Engine support calculation of mac with size different from default 32
230 bits. You can set mac size to any value from 1 to 8 bytes using
232 -sigopt size:(number from 1 to 8 - mac size in bytes)
234 (dgst command uses different EVP_PKEY_CTX for initialization and for
235 finalization of MAC. Option of first are set via -macopt, and for
236 second via -sigopt. Key should be set during initialization and size
237 during finalization. If you use API functions
238 EVP_DigestSignInit/EVP_DigestSignFinal, you can set both options at
241 Encryption with GOST 28147 CFB mode
242 openssl enc -gost89 -out encrypted-file -in plain-text-file -k <passphrase>
243 Encryption with GOST 28147 CNT mode
244 openssl enc -gost89-cnt -out encrypted-file -in plain-text-file -k <passphrase>
245 Encryption with GOST 28147 CBC mode
246 openssl enc -gost89-cbc -out encrypted-file -in plain-text-file -k <passphrase>
248 6. Encrypting private keys and PKCS12
250 To produce PKCS12 files compatible with MagPro CSP, you need to use
251 GOST algorithm for encryption of PKCS12 file and also GOST R 34.11-94
252 hash to derive key from password.
254 openssl pksc12 -export -inkey gost.pem -in gost_cert.pem -keypbe gost89\
255 -certpbe gost89 -macalg md_gost94
257 7. Testing speed of symmetric ciphers.
259 To test performance of GOST symmetric ciphers you should use -evp switch
260 of the openssl speed command. Engine-provided ciphers couldn't be
261 accessed by cipher-specific functions, only via generic evp interface
263 openssl speed -evp gost89
264 openssl speed -evp gost89-cnt
265 openssl speed -evp gost89-cbc
268 PROGRAMMING INTERFACES DETAILS
270 Applications never should access engine directly. They only use provided
271 EVP_PKEY API. But there are some details, which should be taken into
274 EVP provides two kinds of API for key exchange:
276 1. EVP_PKEY_encrypt/EVP_PKEY_decrypt functions, intended to use with
277 RSA-like public key encryption algorithms
279 2. EVP_PKEY_derive, intended to use with Diffie-Hellman-like shared key
280 computing algorithms.
282 Although VKO R 34.10 algorithms, described in the RFC 4357 are
283 definitely second case, engine provides BOTH API for GOST R 34.10 keys.
285 EVP_PKEY_derive just invokes appropriate VKO algorithm and computes
286 256 bit shared key. VKO R 34.10-2001 requires 64 bits of random user key
287 material (UKM). This UKM should be transmitted to other party, so it is
288 not generated inside derive function.
290 It should be set by EVP_PKEY_CTX_ctrl function using
291 EVP_PKEY_CTRL_SET_IV command after call of EVP_PKEY_derive_init, but
292 before EVP_PKEY_derive.
293 unsigned char ukm[8];
295 EVP_PKEY_CTX_ctrl(ctx, -1, EVP_PKEY_OP_DERIVE, 8, ukm)
297 EVP_PKEY_encrypt encrypts provided session key with VKO shared key and
298 packs it into GOST key transport structure, described in the RFC 4490.
300 It typically uses ephemeral key pair to compute shared key and packs its
301 public part along with encrypted key. So, for most cases use of
302 EVP_PKEY_encrypt/EVP_PKEY_decrypt with GOST keys is almost same as with
305 However, if peerkey field in the EVP_PKEY_CTX structure is set (using
306 EVP_PKEY_derive_set_peerkey function) to EVP_PKEY structure which has private
307 key and uses same parameters as the public key from which this EVP_PKEY_CTX is
308 created, EVP_PKEY_encrypt will use this private key to compute shared key and
309 set ephemeral key in the GOST_key_transport structure to NULL. In this case
310 pkey and peerkey fields in the EVP_PKEY_CTX are used upside-down.
312 If EVP_PKEY_decrypt encounters GOST_key_transport structure with NULL
313 public key field, it tries to use peerkey field from the context to
314 compute shared key. In this case peerkey field should really contain
317 Encrypt operation supports EVP_PKEY_CTRL_SET_IV operation as well.
318 It can be used when some specific restriction on UKM are imposed by
319 higher level protocol. For instance, description of GOST ciphersuites
320 requires UKM to be derived from shared secret.
322 If UKM is not set by this control command, encrypt operation would