OLD | NEW |
(Empty) | |
| 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 absense 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 |
OLD | NEW |