GOST ENGINE information.
This commit is contained in:
Dr. Stephen Henson
parent
0e1dba934f
commit
37210fe7e2
280
engines/ccgost/README.gost
Normal file
280
engines/ccgost/README.gost
Normal file
@ -0,0 +1,280 @@
|
||||
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.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user