+++ /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.
-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.
-
-
projects / cassiopeia.git / blobdiff