GOST ENGINE information.
[openssl.git] / engines / ccgost / README.gost
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. But as of October 2007 there is
84 some bug in OpenSSL engine initialization code which prevents engine from
85 correct initialization if it is loaded without explicit dynamic_path.
86 default_algorithms parameter specifies that all algorithms, provided by
87 engine, should be used.
88
89 The crypt_params parameter is engine-specific. It allows the user to choose
90 between different parameter sets of symmetric cipher algorithm. RFC 4357
91 specifies several parameters for the GOST 28147-89 algorithm, but OpenSSL
92 doesn't provide user interface to choose one when encrypting. So use engine
93 configuration parameter instead.
94
95 Value of this parameter can be either short name, defined in OpenSSL
96 obj_dat.h header file or numeric representation of OID, defined in RFC
97 4357. 
98
99 USAGE WITH COMMAND LINE openssl UTILITY
100
101 1. Generation of private key
102
103         openssl genpkey -algorithm gost2001 -pkeyopt paramset:A -out seckey.pem
104
105   Use -algorithm option to specify algorithm.
106   Use -pkeyopt option to pass paramset to algorithm. The following paramsets
107   are supported by 
108         gost94: 0,A,B,C,D,XA,XB,XC
109         gost2001: 0,A,B,C,XA,XB
110   You can also use numeric representation of OID as to destinate
111   paramset.
112
113   Paramsets starting with X are intended to use for key exchange keys.
114   Paramsets without X are for digital signature keys.
115
116   Paramset for both algorithms 0 is the test paramset which should be used
117   only for test purposes.
118
119 There are no algorithm-specific things with generation of certificate
120 request once you have a private key.
121
122 2. S/MIME operations
123
124 If you want to send encrypted mail using GOST algorithms, don't forget
125 to specify -gost89 as encryption algorithm for OpenSSL smime command.
126 While OpenSSL is clever enough to find out that GOST R 34.11-94 digest
127 must be used for digital signing with GOST private key, it have no way
128 to derive symmetric encryption algorithm from key exchange keys.
129
130 3. TLS operations
131
132 OpenSSL supports all four ciphersuites defined in the IETF draft.
133 Once you've loaded GOST key and certificate into your TLS server,
134 ciphersuites which use GOST 28147-89 encryption are enabled.
135
136 Ciphersuites with NULL encryption should be enabled explicitely if
137 needed.
138
139 GOST2001-GOST89-GOST89 Uses GOST R 34.10-2001 for auth and key exchange
140                 GOST 28147-89 for encryption and GOST 28147-89 MAC
141 GOST94-GOST89-GOST89 Uses GOST R 34.10-94 for auth and key exchange
142                 GOST 28147-89 for encryption and GOST 28147-89 MAC
143 GOST2001-NULL-GOST94 Uses GOST R 34.10-2001 for auth and key exchange,
144         no encryption and HMAC, based on GOST R 34.11-94
145 GOST94-NULL-GOST94 Uses GOST R 34.10-94 for auth and key exchange,
146         no encryption and HMAC, based on GOST R 34.11-94
147
148 Gost 94 and gost 2001 keys can be used simultaneously in the TLS server.
149 RSA, DSA and EC keys can be used simultaneously with GOST keys, if
150 server implementation supports loading more than two private
151 key/certificate pairs. In this case ciphersuites which use any of loaded
152 keys would be supported and clients can negotiate ones they wish.
153
154 This allows creation of TLS servers which use GOST ciphersuites for
155 Russian clients and RSA/DSA ciphersuites for foreign clients.
156
157 4. Calculation of digests and symmetric encryption
158  OpenSSL provides specific commands (like sha1, aes etc) for calculation
159  of digests and symmetric encryption. Since such commands cannot be
160  added dynamically, no such commands are provided for GOST algorithms.
161  Use generic commands 'dgst' and 'enc'.
162
163  Calculation of GOST R 34.11-94 message digest
164
165  openssl dgst -md_gost94 datafile
166
167  Note that GOST R 34.11-94 specifies that digest value should be
168  interpreted as little-endian number, but OpenSSL outputs just hex dump
169  of digest value.
170
171  So, to obtain correct digest value, such as produced by gostsum utility
172  included in the engine distribution, bytes of output should be
173  reversed.
174  
175  Calculation of HMAC based on GOST R 34.11-94
176
177  openssl dgst -md_gost94 -mac hmac -macopt key:<32 bytes of key> datafile
178   
179   (or use hexkey if key contain NUL bytes)
180  Calculation of GOST 28147 MAC
181
182  openssl dgst -mac gost-mac -macopt key:<32 bytes of key> datafile
183
184  Note absense of an option that specifies digest algorithm. gost-mac
185  algorithm supports only one digest (which is actually part of
186  implementation of this mac) and OpenSSL is clever enough to find out
187  this.
188
189  Encryption with GOST 28147 CFB mode
190  openssl enc -gost89 -out encrypted-file -in plain-text-file -k <passphrase>  
191  Encryption with GOST 28147 CNT mode
192  openssl enc -gost89-cnt -out encrypted-file -in plain-text-file -k <passphrase>
193
194
195 5. Encrypting private keys and PKCS12
196
197 To produce PKCS12 files compatible with MagPro CSP, you need to use
198 GOST algorithm for encryption of PKCS12 file and also GOST R 34.11-94
199 hash to derive key from password.
200
201 openssl pksc12 -export -inkey gost.pem -in gost_cert.pem -keypbe gost89\
202    -certpbe gost89 -macalg md_gost94
203  
204  
205
206 PROGRAMMING INTERFACES DETAILS
207
208 Applications never should access engine directly. They only use provided
209 EVP_PKEY API. But there are some details, which should be taken into
210 account.
211
212 EVP provides two kinds of API for key exchange:
213
214 1. EVP_PKEY_encrypt/EVP_PKEY_decrypt functions, intended to use with
215         RSA-like public key encryption algorithms
216
217 2. EVP_PKEY_derive, intended to use with Diffie-Hellman-like shared key
218 computing algorithms.
219
220 Although VKO R 34.10 algorithms, described in the RFC 4357 are
221 definitely second case, engine provides BOTH API for GOST R 34.10 keys.
222
223 EVP_PKEY_derive just invokes appropriate VKO algorithm and computes
224 256 bit shared key. VKO R 34.10-2001 requires 64 bits of random user key
225 material (UKM). This UKM should be transmitted to other party, so it is
226 not generated inside derive function.
227
228 It should be set by EVP_PKEY_CTX_ctrl function using
229 EVP_PKEY_CTRL_SET_IV command after call of EVP_PKEY_derive_init, but
230 before EVP_PKEY_derive.
231         unsigned char ukm[8];
232         RAND_bytes(ukm,8);
233    EVP_PKEY_CTX_ctrl(ctx, -1, EVP_PKEY_OP_DERIVE, 8, ukm)
234
235 EVP_PKEY_encrypt encrypts provided session key with VKO shared key and
236 packs it into GOST key transport structure, described in the RFC 4490.
237
238 It typically uses ephemeral key pair to compute shared key and packs its
239 public part along with encrypted key. So, for most cases use of 
240 EVP_PKEY_encrypt/EVP_PKEY_decrypt with GOST keys is almost same as with
241 RSA.
242
243 However, if peerkey field in the EVP_PKEY_CTX structure is set (using
244 EVP_PKEY_derive_set_peerkey function) to EVP_PKEY structure which has private
245 key and uses same parameters as the public key from which this EVP_PKEY_CTX is
246 created, EVP_PKEY_encrypt will use this private key to compute shared key and
247 set ephemeral key in the GOST_key_transport structure to NULL. In this case
248 pkey and peerkey fields in the EVP_PKEY_CTX are used upside-down.
249
250 If EVP_PKEY_decrypt encounters GOST_key_transport structure with NULL
251 public key field, it tries to use peerkey field from the context to
252 compute shared key. In this case peerkey field should really contain
253 peer public key.
254
255 Encrypt operation supports EVP_PKEY_CTRL_SET_IV operation as well.
256 It can be used when some specific restriction on UKM are imposed by
257 higher level protocol. For instance, description of GOST ciphersuites
258 requires UKM to be derived from shared secret. 
259
260 If UKM is not set by this control command, encrypt operation would
261 generate random UKM.
262
263
264 This sources include implementation of GOST 28147-89 and GOST R 34.11-94
265 which are completely indepentent from OpenSSL and can be used separately
266 (files gost89.c, gost89.h, gosthash.c, gosthash.h) Utility gostsum (file
267 gostsum.c) is provided as example of such separate usage. This is
268 program, simular to md5sum and sha1sum utilities, but calculates GOST R
269 34.11-94 hash.
270
271 Makefile doesn't include rule for compiling gostsum.
272 Use command
273
274 $(CC) -o gostsum gostsum.c gost89.c gosthash.c
275 where $(CC) is name of your C compiler.
276
277 Implementations of GOST R 34.10-xx, including VKO algorithms heavily
278 depends on OpenSSL BIGNUM and Elliptic Curve libraries.
279
280