engines/ccgost/README.gost - third_party/openssl - Git at Google

 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 absence 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.
	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 absence 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.