--- /dev/null
+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. But as of October 2007 there is
+some bug in OpenSSL engine initialization code which prevents engine from
+correct initialization if it is loaded without explicit dynamic_path.
+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. 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.
+
+3. 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.
+
+4. 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>
+
+
+5. 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
+
+
+
+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.
+
+
projects / openssl.git / blobdiff