300 lines
12 KiB
Text
300 lines
12 KiB
Text
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.
|
|
|
|
|