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.
9 COMPILING AND INSTALLATION
11 This engine is a drop-in replacement of the GOST engine included in openssl
12 1.0.2. The original version does not support GOST2012 algorithms. To compile
13 it, you MUST apply the required patches (from the patches/ folder) to the
14 openssl 1.0.2 source tree and copy all files from the current directory to the
15 openssl/engines/ccgost folder. After that you will be able to configure and
16 build openssl using standard options.
20 GOST R 34.10-2001 and GOST R 34.10-2012 - digital signature algorithms.
21 Also support key exchange based on public keys. See RFC 4357 for
22 details of VKO key exchange algorithm. These algorithms use
23 256 bit private keys. Public keys are 1024 bit for 94 and 512 bit for
24 2001 (which is elliptic-curve based). Key exchange algorithms
25 (VKO R 34.10) are supported on these keys too.
27 GOST R 34.11-2012 Message digest algorithm. 256-bit hash value
29 GOST 28147-89 - Symmetric cipher with 256-bit key. Various modes are
30 defined in the standard, but only CFB and CNT modes are implemented
31 in the engine. To make statistical analysis more difficult, key
32 meshing is supported (see RFC 4357).
34 GOST 28147-89 MAC mode. Message authentication code. While most MAC
35 algorithms out there are based on hash functions using HMAC
36 algorithm, this algoritm is based on symmetric cipher.
37 It has 256-bit symmetric key and only 32 bits of MAC value
38 (while HMAC has same key size and value size).
40 Really, this algorithm supports from 8 to 64 bits of the MAC value
42 It is implemented as combination of EVP_PKEY type and EVP_MD type.
44 USAGE OF THESE ALGORITHMS
46 This engine is designed to allow usage of this algorithms in the
47 high-level openssl functions, such as PKI, S/MIME and TLS.
49 See RFC 4490 for S/MIME with GOST algorithms and RFC 4491 for PKI.
50 TLS support is implemented according IETF
51 draft-chudov-cryptopro-cptls-03.txt and is compatible with
52 CryptoPro CSP 3.0 and 3.6 as well as with MagPro CSP.
53 GOST ciphersuites implemented in CryptoPro CSP 2.0 are not supported
54 because they use ciphersuite numbers used now by AES ciphersuites.
56 To use the engine you have to load it via openssl configuration
57 file. Applications should read openssl configuration file or provide
58 their own means to load engines. Also, applications which operate with
59 private keys, should use generic EVP_PKEY API instead of using RSA or
60 other algorithm-specific API.
64 Configuration file should include following statement in the global
65 section, i.e. before first bracketed section header (see config(5) for details)
67 openssl_conf = openssl_def
69 where openssl_def is name of the section in configuration file which
70 describes global defaults.
72 This section should contain following statement:
75 engines = engine_section
77 which points to the section which describes list of the engines to be
78 loaded. This section should contain:
83 And section which describes configuration of the engine should contain
87 dynamic_path = /usr/lib/ssl/engines/libgost.so
88 default_algorithms = ALL
89 CRYPT_PARAMS = id-Gost28147-89-CryptoPro-A-ParamSet
91 Where engine_id parameter specifies name of engine (should be "gost").
92 dynamic_path is a location of the loadable shared library implementing the
93 engine. If the engine is compiled statically or is located in the OpenSSL
94 engines directory, this line can be omitted.
95 default_algorithms parameter specifies that all algorithms, provided by
96 engine, should be used.
98 The CRYPT_PARAMS parameter is engine-specific. It allows the user to choose
99 between different parameter sets of symmetric cipher algorithm. RFC 4357
100 specifies several parameters for the GOST 28147-89 algorithm, but OpenSSL
101 doesn't provide user interface to choose one when encrypting. So use engine
102 configuration parameter instead.
104 Value of this parameter can be either short name, defined in OpenSSL
105 obj_dat.h header file or numeric representation of OID, defined in RFC
108 USAGE WITH COMMAND LINE openssl UTILITY
110 1. Generation of private key
112 openssl genpkey -algorithm gost2001 -pkeyopt paramset:A -out seckey.pem
114 Use -algorithm option to specify algorithm.
115 Use -pkeyopt option to pass paramset to algorithm. The following paramsets
117 gost94: 0,A,B,C,D,XA,XB,XC
118 gost2001: 0,A,B,C,XA,XB
119 You can also use numeric representation of OID as to destinate
122 Paramsets starting with X are intended to use for key exchange keys.
123 Paramsets without X are for digital signature keys.
125 Paramset for both algorithms 0 is the test paramset which should be used
126 only for test purposes.
128 There are no algorithm-specific things with generation of certificate
129 request once you have a private key.
131 2. Generation of certificate request along with private/public keypar
133 openssl req -newkey gost2001 -pkeyopt paramset:A
135 Syntax of -pkeyopt parameter is identical with genpkey command.
137 You can also use oldstyle syntax -newkey gost2001:paramfile, but in
138 this case you should create parameter file first.
140 It can be created with
142 openssl genpkey -genparam -algorithm gost2001 -pkeyopt paramset:A\
147 If you want to send encrypted mail using GOST algorithms, don't forget
148 to specify -gost89 as encryption algorithm for OpenSSL smime command.
149 While OpenSSL is clever enough to find out that GOST R 34.11-94 digest
150 must be used for digital signing with GOST private key, it have no way
151 to derive symmetric encryption algorithm from key exchange keys.
155 OpenSSL supports all four ciphersuites defined in the IETF draft.
156 Once you've loaded GOST key and certificate into your TLS server,
157 ciphersuites which use GOST 28147-89 encryption are enabled.
159 Ciphersuites with NULL encryption should be enabled explicitely if
162 GOST2001-GOST89-GOST89 Uses GOST R 34.10-2001 for auth and key exchange
163 GOST 28147-89 for encryption and GOST 28147-89 MAC
164 GOST94-GOST89-GOST89 Uses GOST R 34.10-94 for auth and key exchange
165 GOST 28147-89 for encryption and GOST 28147-89 MAC
166 GOST2001-NULL-GOST94 Uses GOST R 34.10-2001 for auth and key exchange,
167 no encryption and HMAC, based on GOST R 34.11-94
168 GOST94-NULL-GOST94 Uses GOST R 34.10-94 for auth and key exchange,
169 no encryption and HMAC, based on GOST R 34.11-94
171 Gost 94 and gost 2001 keys can be used simultaneously in the TLS server.
172 RSA, DSA and EC keys can be used simultaneously with GOST keys, if
173 server implementation supports loading more than two private
174 key/certificate pairs. In this case ciphersuites which use any of loaded
175 keys would be supported and clients can negotiate ones they wish.
177 This allows creation of TLS servers which use GOST ciphersuites for
178 Russian clients and RSA/DSA ciphersuites for foreign clients.
180 5. Calculation of digests and symmetric encryption
181 OpenSSL provides specific commands (like sha1, aes etc) for calculation
182 of digests and symmetric encryption. Since such commands cannot be
183 added dynamically, no such commands are provided for GOST algorithms.
184 Use generic commands 'dgst' and 'enc'.
186 Calculation of GOST R 34.11-94 message digest
188 openssl dgst -md_gost94 datafile
190 Note that GOST R 34.11-94 specifies that digest value should be
191 interpreted as little-endian number, but OpenSSL outputs just hex dump
194 So, to obtain correct digest value, such as produced by gostsum utility
195 included in the engine distribution, bytes of output should be
198 Calculation of HMAC based on GOST R 34.11-94
200 openssl dgst -md_gost94 -mac hmac -macopt key:<32 bytes of key> datafile
202 (or use hexkey if key contain NUL bytes)
203 Calculation of GOST 28147 MAC
205 openssl dgst -mac gost-mac -macopt key:<32 bytes of key> datafile
207 Note absence of an option that specifies digest algorithm. gost-mac
208 algorithm supports only one digest (which is actually part of
209 implementation of this mac) and OpenSSL is clever enough to find out
212 Following mac options are supported:
214 key:(32 bytes of key)
216 hexkey:(64 hexadecimal digits of key)
218 Engine support calculation of mac with size different from default 32
219 bits. You can set mac size to any value from 1 to 8 bytes using
221 -sigopt size:(number from 1 to 8 - mac size in bytes)
223 (dgst command uses different EVP_PKEY_CTX for initialization and for
224 finalization of MAC. Option of first are set via -macopt, and for
225 second via -sigopt. Key should be set during initialization and size
226 during finalization. If you use API functions
227 EVP_DigestSignInit/EVP_DigestSignFinal, you can set both options at
230 Encryption with GOST 28147 CFB mode
231 openssl enc -gost89 -out encrypted-file -in plain-text-file -k <passphrase>
232 Encryption with GOST 28147 CNT mode
233 openssl enc -gost89-cnt -out encrypted-file -in plain-text-file -k <passphrase>
234 Encryption with GOST 28147 CBC mode
235 openssl enc -gost89-cbc -out encrypted-file -in plain-text-file -k <passphrase>
237 6. Encrypting private keys and PKCS12
239 To produce PKCS12 files compatible with MagPro CSP, you need to use
240 GOST algorithm for encryption of PKCS12 file and also GOST R 34.11-94
241 hash to derive key from password.
243 openssl pksc12 -export -inkey gost.pem -in gost_cert.pem -keypbe gost89\
244 -certpbe gost89 -macalg md_gost94
246 7. Testing speed of symmetric ciphers.
248 To test performance of GOST symmetric ciphers you should use -evp switch
249 of the openssl speed command. Engine-provided ciphers couldn't be
250 accessed by cipher-specific functions, only via generic evp interface
252 openssl speed -evp gost89
253 openssl speed -evp gost89-cnt
254 openssl speed -evp gost89-cbc
257 PROGRAMMING INTERFACES DETAILS
259 Applications never should access engine directly. They only use provided
260 EVP_PKEY API. But there are some details, which should be taken into
263 EVP provides two kinds of API for key exchange:
265 1. EVP_PKEY_encrypt/EVP_PKEY_decrypt functions, intended to use with
266 RSA-like public key encryption algorithms
268 2. EVP_PKEY_derive, intended to use with Diffie-Hellman-like shared key
269 computing algorithms.
271 Although VKO R 34.10 algorithms, described in the RFC 4357 are
272 definitely second case, engine provides BOTH API for GOST R 34.10 keys.
274 EVP_PKEY_derive just invokes appropriate VKO algorithm and computes
275 256 bit shared key. VKO R 34.10-2001 requires 64 bits of random user key
276 material (UKM). This UKM should be transmitted to other party, so it is
277 not generated inside derive function.
279 It should be set by EVP_PKEY_CTX_ctrl function using
280 EVP_PKEY_CTRL_SET_IV command after call of EVP_PKEY_derive_init, but
281 before EVP_PKEY_derive.
282 unsigned char ukm[8];
284 EVP_PKEY_CTX_ctrl(ctx, -1, EVP_PKEY_OP_DERIVE, 8, ukm)
286 EVP_PKEY_encrypt encrypts provided session key with VKO shared key and
287 packs it into GOST key transport structure, described in the RFC 4490.
289 It typically uses ephemeral key pair to compute shared key and packs its
290 public part along with encrypted key. So, for most cases use of
291 EVP_PKEY_encrypt/EVP_PKEY_decrypt with GOST keys is almost same as with
294 However, if peerkey field in the EVP_PKEY_CTX structure is set (using
295 EVP_PKEY_derive_set_peerkey function) to EVP_PKEY structure which has private
296 key and uses same parameters as the public key from which this EVP_PKEY_CTX is
297 created, EVP_PKEY_encrypt will use this private key to compute shared key and
298 set ephemeral key in the GOST_key_transport structure to NULL. In this case
299 pkey and peerkey fields in the EVP_PKEY_CTX are used upside-down.
301 If EVP_PKEY_decrypt encounters GOST_key_transport structure with NULL
302 public key field, it tries to use peerkey field from the context to
303 compute shared key. In this case peerkey field should really contain
306 Encrypt operation supports EVP_PKEY_CTRL_SET_IV operation as well.
307 It can be used when some specific restriction on UKM are imposed by
308 higher level protocol. For instance, description of GOST ciphersuites
309 requires UKM to be derived from shared secret.
311 If UKM is not set by this control command, encrypt operation would
315 This sources include implementation of GOST 28147-89 and GOST R 34.11-94
316 which are completely indepentent from OpenSSL and can be used separately
317 (files gost89.c, gost89.h, gosthash.c, gosthash.h) Utility gostsum (file
318 gostsum.c) is provided as example of such separate usage. This is
319 program, simular to md5sum and sha1sum utilities, but calculates GOST R
322 Makefile doesn't include rule for compiling gostsum.
325 $(CC) -o gostsum gostsum.c gost89.c gosthash.c
326 where $(CC) is name of your C compiler.
328 Implementations of GOST R 34.10-xx, including VKO algorithms heavily
329 depends on OpenSSL BIGNUM and Elliptic Curve libraries.