Index: openssl/engines/ccgost/README.gost |
=================================================================== |
--- openssl/engines/ccgost/README.gost (revision 0) |
+++ openssl/engines/ccgost/README.gost (revision 0) |
@@ -0,0 +1,300 @@ |
+GOST ENGINE |
+ |
+This engine provides implementation of Russian cryptography standard. |
+This is also an example of adding new cryptoalgorithms into OpenSSL |
+without changing its core. If OpenSSL is compiled with dynamic engine |
+support, new algorithms can be added even without recompilation of |
+OpenSSL and applications which use it. |
+ |
+ALGORITHMS SUPPORTED |
+ |
+GOST R 34.10-94 and GOST R 34.10-2001 - digital signature algorithms. |
+ Also support key exchange based on public keys. See RFC 4357 for |
+ details of VKO key exchange algorithm. These algorithms use |
+ 256 bit private keys. Public keys are 1024 bit for 94 and 512 bit for |
+ 2001 (which is elliptic-curve based). Key exchange algorithms |
+ (VKO R 34.10) are supported on these keys too. |
+ |
+GOST R 34.11-94 Message digest algorithm. 256-bit hash value |
+ |
+GOST 28147-89 - Symmetric cipher with 256-bit key. Various modes are |
+ defined in the standard, but only CFB and CNT modes are implemented |
+ in the engine. To make statistical analysis more difficult, key |
+ meshing is supported (see RFC 4357). |
+ |
+GOST 28147-89 MAC mode. Message authentication code. While most MAC |
+ algorithms out there are based on hash functions using HMAC |
+ algorithm, this algoritm is based on symmetric cipher. |
+ It has 256-bit symmetric key and only 32 bits of MAC value |
+ (while HMAC has same key size and value size). |
+ |
+ It is implemented as combination of EVP_PKEY type and EVP_MD type. |
+ |
+USAGE OF THESE ALGORITHMS |
+ |
+This engine is designed to allow usage of this algorithms in the |
+high-level openssl functions, such as PKI, S/MIME and TLS. |
+ |
+See RFC 4490 for S/MIME with GOST algorithms and RFC 4491 for PKI. |
+TLS support is implemented according IETF |
+draft-chudov-cryptopro-cptls-03.txt and is compatible with |
+CryptoPro CSP 3.0 and 3.6 as well as with MagPro CSP. |
+GOST ciphersuites implemented in CryptoPro CSP 2.0 are not supported |
+because they use ciphersuite numbers used now by AES ciphersuites. |
+ |
+To use the engine you have to load it via openssl configuration |
+file. Applications should read openssl configuration file or provide |
+their own means to load engines. Also, applications which operate with |
+private keys, should use generic EVP_PKEY API instead of using RSA or |
+other algorithm-specific API. |
+ |
+CONFIGURATION FILE |
+ |
+Configuration file should include following statement in the global |
+section, i.e. before first bracketed section header (see config(5) for details) |
+ |
+ openssl_conf = openssl_def |
+ |
+where openssl_def is name of the section in configuration file which |
+describes global defaults. |
+ |
+This section should contain following statement: |
+ |
+ [openssl_def] |
+ engines = engine_section |
+ |
+which points to the section which describes list of the engines to be |
+loaded. This section should contain: |
+ |
+ [engine_section] |
+ gost = gost_section |
+ |
+And section which describes configuration of the engine should contain |
+ |
+ [gost_section] |
+ engine_id = gost |
+ dynamic_path = /usr/lib/ssl/engines/libgost.so |
+ default_algorithms = ALL |
+ CRYPT_PARAMS = id-Gost28147-89-CryptoPro-A-ParamSet |
+ |
+Where engine_id parameter specifies name of engine (should be "gost"). |
+dynamic_path is a location of the loadable shared library implementing the |
+engine. If the engine is compiled statically or is located in the OpenSSL |
+engines directory, this line can be omitted. |
+default_algorithms parameter specifies that all algorithms, provided by |
+engine, should be used. |
+ |
+The CRYPT_PARAMS parameter is engine-specific. It allows the user to choose |
+between different parameter sets of symmetric cipher algorithm. RFC 4357 |
+specifies several parameters for the GOST 28147-89 algorithm, but OpenSSL |
+doesn't provide user interface to choose one when encrypting. So use engine |
+configuration parameter instead. |
+ |
+Value of this parameter can be either short name, defined in OpenSSL |
+obj_dat.h header file or numeric representation of OID, defined in RFC |
+4357. |
+ |
+USAGE WITH COMMAND LINE openssl UTILITY |
+ |
+1. Generation of private key |
+ |
+ openssl genpkey -algorithm gost2001 -pkeyopt paramset:A -out seckey.pem |
+ |
+ Use -algorithm option to specify algorithm. |
+ Use -pkeyopt option to pass paramset to algorithm. The following paramsets |
+ are supported by |
+ gost94: 0,A,B,C,D,XA,XB,XC |
+ gost2001: 0,A,B,C,XA,XB |
+ You can also use numeric representation of OID as to destinate |
+ paramset. |
+ |
+ Paramsets starting with X are intended to use for key exchange keys. |
+ Paramsets without X are for digital signature keys. |
+ |
+ Paramset for both algorithms 0 is the test paramset which should be used |
+ only for test purposes. |
+ |
+There are no algorithm-specific things with generation of certificate |
+request once you have a private key. |
+ |
+2. Generation of certificate request along with private/public keypar |
+ |
+ openssl req -newkey gost2001 -pkeyopt paramset:A |
+ |
+ Syntax of -pkeyopt parameter is identical with genpkey command. |
+ |
+ You can also use oldstyle syntax -newkey gost2001:paramfile, but in |
+ this case you should create parameter file first. |
+ |
+ It can be created with |
+ |
+ openssl genpkey -genparam -algorithm gost2001 -pkeyopt paramset:A\ |
+ -out paramfile. |
+ |
+3. S/MIME operations |
+ |
+If you want to send encrypted mail using GOST algorithms, don't forget |
+to specify -gost89 as encryption algorithm for OpenSSL smime command. |
+While OpenSSL is clever enough to find out that GOST R 34.11-94 digest |
+must be used for digital signing with GOST private key, it have no way |
+to derive symmetric encryption algorithm from key exchange keys. |
+ |
+4. TLS operations |
+ |
+OpenSSL supports all four ciphersuites defined in the IETF draft. |
+Once you've loaded GOST key and certificate into your TLS server, |
+ciphersuites which use GOST 28147-89 encryption are enabled. |
+ |
+Ciphersuites with NULL encryption should be enabled explicitely if |
+needed. |
+ |
+GOST2001-GOST89-GOST89 Uses GOST R 34.10-2001 for auth and key exchange |
+ GOST 28147-89 for encryption and GOST 28147-89 MAC |
+GOST94-GOST89-GOST89 Uses GOST R 34.10-94 for auth and key exchange |
+ GOST 28147-89 for encryption and GOST 28147-89 MAC |
+GOST2001-NULL-GOST94 Uses GOST R 34.10-2001 for auth and key exchange, |
+ no encryption and HMAC, based on GOST R 34.11-94 |
+GOST94-NULL-GOST94 Uses GOST R 34.10-94 for auth and key exchange, |
+ no encryption and HMAC, based on GOST R 34.11-94 |
+ |
+Gost 94 and gost 2001 keys can be used simultaneously in the TLS server. |
+RSA, DSA and EC keys can be used simultaneously with GOST keys, if |
+server implementation supports loading more than two private |
+key/certificate pairs. In this case ciphersuites which use any of loaded |
+keys would be supported and clients can negotiate ones they wish. |
+ |
+This allows creation of TLS servers which use GOST ciphersuites for |
+Russian clients and RSA/DSA ciphersuites for foreign clients. |
+ |
+5. Calculation of digests and symmetric encryption |
+ OpenSSL provides specific commands (like sha1, aes etc) for calculation |
+ of digests and symmetric encryption. Since such commands cannot be |
+ added dynamically, no such commands are provided for GOST algorithms. |
+ Use generic commands 'dgst' and 'enc'. |
+ |
+ Calculation of GOST R 34.11-94 message digest |
+ |
+ openssl dgst -md_gost94 datafile |
+ |
+ Note that GOST R 34.11-94 specifies that digest value should be |
+ interpreted as little-endian number, but OpenSSL outputs just hex dump |
+ of digest value. |
+ |
+ So, to obtain correct digest value, such as produced by gostsum utility |
+ included in the engine distribution, bytes of output should be |
+ reversed. |
+ |
+ Calculation of HMAC based on GOST R 34.11-94 |
+ |
+ openssl dgst -md_gost94 -mac hmac -macopt key:<32 bytes of key> datafile |
+ |
+ (or use hexkey if key contain NUL bytes) |
+ Calculation of GOST 28147 MAC |
+ |
+ openssl dgst -mac gost-mac -macopt key:<32 bytes of key> datafile |
+ |
+ Note absense of an option that specifies digest algorithm. gost-mac |
+ algorithm supports only one digest (which is actually part of |
+ implementation of this mac) and OpenSSL is clever enough to find out |
+ this. |
+ |
+ Encryption with GOST 28147 CFB mode |
+ openssl enc -gost89 -out encrypted-file -in plain-text-file -k <passphrase> |
+ Encryption with GOST 28147 CNT mode |
+ openssl enc -gost89-cnt -out encrypted-file -in plain-text-file -k <passphrase> |
+ |
+ |
+6. Encrypting private keys and PKCS12 |
+ |
+To produce PKCS12 files compatible with MagPro CSP, you need to use |
+GOST algorithm for encryption of PKCS12 file and also GOST R 34.11-94 |
+hash to derive key from password. |
+ |
+openssl pksc12 -export -inkey gost.pem -in gost_cert.pem -keypbe gost89\ |
+ -certpbe gost89 -macalg md_gost94 |
+ |
+7. Testing speed of symmetric ciphers. |
+ |
+To test performance of GOST symmetric ciphers you should use -evp switch |
+of the openssl speed command. Engine-provided ciphers couldn't be |
+accessed by cipher-specific functions, only via generic evp interface |
+ |
+ openssl speed -evp gost89 |
+ openssl speed -evp gost89-cnt |
+ |
+ |
+PROGRAMMING INTERFACES DETAILS |
+ |
+Applications never should access engine directly. They only use provided |
+EVP_PKEY API. But there are some details, which should be taken into |
+account. |
+ |
+EVP provides two kinds of API for key exchange: |
+ |
+1. EVP_PKEY_encrypt/EVP_PKEY_decrypt functions, intended to use with |
+ RSA-like public key encryption algorithms |
+ |
+2. EVP_PKEY_derive, intended to use with Diffie-Hellman-like shared key |
+computing algorithms. |
+ |
+Although VKO R 34.10 algorithms, described in the RFC 4357 are |
+definitely second case, engine provides BOTH API for GOST R 34.10 keys. |
+ |
+EVP_PKEY_derive just invokes appropriate VKO algorithm and computes |
+256 bit shared key. VKO R 34.10-2001 requires 64 bits of random user key |
+material (UKM). This UKM should be transmitted to other party, so it is |
+not generated inside derive function. |
+ |
+It should be set by EVP_PKEY_CTX_ctrl function using |
+EVP_PKEY_CTRL_SET_IV command after call of EVP_PKEY_derive_init, but |
+before EVP_PKEY_derive. |
+ unsigned char ukm[8]; |
+ RAND_bytes(ukm,8); |
+ EVP_PKEY_CTX_ctrl(ctx, -1, EVP_PKEY_OP_DERIVE, 8, ukm) |
+ |
+EVP_PKEY_encrypt encrypts provided session key with VKO shared key and |
+packs it into GOST key transport structure, described in the RFC 4490. |
+ |
+It typically uses ephemeral key pair to compute shared key and packs its |
+public part along with encrypted key. So, for most cases use of |
+EVP_PKEY_encrypt/EVP_PKEY_decrypt with GOST keys is almost same as with |
+RSA. |
+ |
+However, if peerkey field in the EVP_PKEY_CTX structure is set (using |
+EVP_PKEY_derive_set_peerkey function) to EVP_PKEY structure which has private |
+key and uses same parameters as the public key from which this EVP_PKEY_CTX is |
+created, EVP_PKEY_encrypt will use this private key to compute shared key and |
+set ephemeral key in the GOST_key_transport structure to NULL. In this case |
+pkey and peerkey fields in the EVP_PKEY_CTX are used upside-down. |
+ |
+If EVP_PKEY_decrypt encounters GOST_key_transport structure with NULL |
+public key field, it tries to use peerkey field from the context to |
+compute shared key. In this case peerkey field should really contain |
+peer public key. |
+ |
+Encrypt operation supports EVP_PKEY_CTRL_SET_IV operation as well. |
+It can be used when some specific restriction on UKM are imposed by |
+higher level protocol. For instance, description of GOST ciphersuites |
+requires UKM to be derived from shared secret. |
+ |
+If UKM is not set by this control command, encrypt operation would |
+generate random UKM. |
+ |
+ |
+This sources include implementation of GOST 28147-89 and GOST R 34.11-94 |
+which are completely indepentent from OpenSSL and can be used separately |
+(files gost89.c, gost89.h, gosthash.c, gosthash.h) Utility gostsum (file |
+gostsum.c) is provided as example of such separate usage. This is |
+program, simular to md5sum and sha1sum utilities, but calculates GOST R |
+34.11-94 hash. |
+ |
+Makefile doesn't include rule for compiling gostsum. |
+Use command |
+ |
+$(CC) -o gostsum gostsum.c gost89.c gosthash.c |
+where $(CC) is name of your C compiler. |
+ |
+Implementations of GOST R 34.10-xx, including VKO algorithms heavily |
+depends on OpenSSL BIGNUM and Elliptic Curve libraries. |
+ |
+ |