]>
Commit | Line | Data |
---|---|---|
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 absence 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 |