"Fossies" - the Fresh Open Source Software Archive

Member "openssl-1.0.2q/engines/ccgost/README.gost" (20 Nov 2018, 11850 Bytes) of package /linux/misc/openssl-1.0.2q.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "README.gost": 1.0.2n_vs_1.0.2o.

    1 GOST ENGINE
    2 
    3 This engine provides implementation of Russian cryptography standard.
    4 This is also an example of adding new cryptoalgorithms into OpenSSL
    5 without changing its core. If OpenSSL is compiled with dynamic engine
    6 support, new algorithms can be added even without recompilation of
    7 OpenSSL and applications which use it.
    8 
    9 ALGORITHMS SUPPORTED
   10 
   11 GOST R 34.10-94 and GOST R 34.10-2001 - digital signature algorithms.
   12    Also support key exchange based on public keys. See RFC 4357 for
   13    details of VKO key exchange algorithm. These algorithms use
   14    256 bit private keys. Public keys are 1024 bit for 94 and 512 bit for
   15    2001 (which is elliptic-curve based). Key exchange algorithms
   16    (VKO R 34.10) are supported on these keys too.
   17    
   18 GOST R 34.11-94  Message digest algorithm. 256-bit hash value
   19 
   20 GOST 28147-89 - Symmetric cipher  with 256-bit key. Various modes are
   21    defined in the standard, but only CFB and CNT modes are implemented
   22    in the engine. To make statistical analysis more difficult, key
   23    meshing is supported (see RFC 4357).
   24 
   25 GOST 28147-89 MAC mode. Message authentication code. While most MAC
   26     algorithms  out there are based on hash functions using HMAC
   27 	algorithm, this algoritm is based on symmetric cipher. 
   28 	It has 256-bit symmetric key and only 32 bits of MAC value
   29 	(while HMAC has same key size and value size). 
   30 
   31 	It is implemented as combination of EVP_PKEY type and EVP_MD type.
   32 
   33 USAGE OF THESE ALGORITHMS
   34 
   35 This engine is designed to allow usage of this algorithms in the
   36 high-level openssl functions, such as PKI, S/MIME and TLS.
   37 
   38 See RFC 4490 for S/MIME with GOST algorithms and RFC 4491 for PKI.
   39 TLS support is implemented according IETF
   40 draft-chudov-cryptopro-cptls-03.txt and is compatible with
   41 CryptoPro CSP 3.0 and 3.6 as well as with MagPro CSP. 
   42 GOST ciphersuites implemented in CryptoPro CSP 2.0 are not supported
   43 because they use ciphersuite numbers used now by AES ciphersuites.
   44 
   45 To use the engine you have to load it via openssl configuration
   46 file. Applications should read openssl configuration file or provide
   47 their own means to load engines. Also, applications which operate with
   48 private keys, should use generic EVP_PKEY API instead of using RSA or
   49 other algorithm-specific API.
   50 
   51 CONFIGURATION FILE
   52 
   53 Configuration file should include following statement in the global
   54 section, i.e. before first bracketed section header (see config(5) for details)
   55 
   56    openssl_conf = openssl_def
   57 
   58 where openssl_def is name of the section in configuration file which
   59 describes global defaults.
   60 
   61 This section should contain following statement:
   62 
   63    [openssl_def]
   64    engines = engine_section
   65 
   66 which points to the section which describes list of the engines to be
   67 loaded. This section should contain:
   68 
   69 	[engine_section]
   70 	gost = gost_section
   71 
   72 And section which describes configuration of the engine should contain
   73 
   74 	[gost_section]
   75 	engine_id = gost
   76 	dynamic_path = /usr/lib/ssl/engines/libgost.so
   77 	default_algorithms = ALL
   78 	CRYPT_PARAMS = id-Gost28147-89-CryptoPro-A-ParamSet
   79 
   80 Where engine_id parameter specifies name of engine (should be "gost").
   81 dynamic_path is a location of the loadable shared library implementing the
   82 engine. If the engine is compiled statically or is located in the OpenSSL
   83 engines directory, this line can be omitted. 
   84 default_algorithms parameter specifies that all algorithms, provided by
   85 engine, should be used.
   86 
   87 The CRYPT_PARAMS parameter is engine-specific. It allows the user to choose
   88 between different parameter sets of symmetric cipher algorithm. RFC 4357
   89 specifies several parameters for the GOST 28147-89 algorithm, but OpenSSL
   90 doesn't provide user interface to choose one when encrypting. So use engine
   91 configuration parameter instead.
   92 
   93 Value of this parameter can be either short name, defined in OpenSSL
   94 obj_dat.h header file or numeric representation of OID, defined in RFC
   95 4357. 
   96 
   97 USAGE WITH COMMAND LINE openssl UTILITY
   98 
   99 1. Generation of private key
  100 
  101 	openssl genpkey -algorithm gost2001 -pkeyopt paramset:A -out seckey.pem
  102 
  103   Use -algorithm option to specify algorithm.
  104   Use -pkeyopt option to pass paramset to algorithm. The following paramsets
  105   are supported by 
  106   	gost94: 0,A,B,C,D,XA,XB,XC
  107 	gost2001: 0,A,B,C,XA,XB
  108   You can also use numeric representation of OID as to destinate
  109   paramset.
  110 
  111   Paramsets starting with X are intended to use for key exchange keys.
  112   Paramsets without X are for digital signature keys.
  113 
  114   Paramset for both algorithms 0 is the test paramset which should be used
  115   only for test purposes.
  116 
  117 There are no algorithm-specific things with generation of certificate
  118 request once you have a private key.
  119 
  120 2. Generation of certificate request along with private/public keypar
  121 
  122    openssl req -newkey gost2001 -pkeyopt paramset:A
  123 
  124    Syntax of -pkeyopt parameter is identical with genpkey command.
  125 
  126    You can also use oldstyle syntax -newkey gost2001:paramfile, but in
  127    this case you should create parameter file first. 
  128 
  129    It can be created with
  130 
  131    openssl genpkey -genparam -algorithm gost2001 -pkeyopt paramset:A\
  132       -out paramfile.
  133 
  134 3. S/MIME operations
  135 
  136 If you want to send encrypted mail using GOST algorithms, don't forget
  137 to specify -gost89 as encryption algorithm for OpenSSL smime command.
  138 While OpenSSL is clever enough to find out that GOST R 34.11-94 digest
  139 must be used for digital signing with GOST private key, it have no way
  140 to derive symmetric encryption algorithm from key exchange keys.
  141 
  142 4. TLS operations
  143 
  144 OpenSSL supports all four ciphersuites defined in the IETF draft.
  145 Once you've loaded GOST key and certificate into your TLS server,
  146 ciphersuites which use GOST 28147-89 encryption are enabled.
  147 
  148 Ciphersuites with NULL encryption should be enabled explicitely if
  149 needed.
  150 
  151 GOST2001-GOST89-GOST89 Uses GOST R 34.10-2001 for auth and key exchange
  152 		GOST 28147-89 for encryption and GOST 28147-89 MAC
  153 GOST94-GOST89-GOST89 Uses GOST R 34.10-94 for auth and key exchange
  154 		GOST 28147-89 for encryption and GOST 28147-89 MAC
  155 GOST2001-NULL-GOST94 Uses GOST R 34.10-2001 for auth and key exchange,
  156         no encryption and HMAC, based on GOST R 34.11-94
  157 GOST94-NULL-GOST94 Uses GOST R 34.10-94 for auth and key exchange,
  158         no encryption and HMAC, based on GOST R 34.11-94
  159 
  160 Gost 94 and gost 2001 keys can be used simultaneously in the TLS server.
  161 RSA, DSA and EC keys can be used simultaneously with GOST keys, if
  162 server implementation supports loading more than two private
  163 key/certificate pairs. In this case ciphersuites which use any of loaded
  164 keys would be supported and clients can negotiate ones they wish.
  165 
  166 This allows creation of TLS servers which use GOST ciphersuites for
  167 Russian clients and RSA/DSA ciphersuites for foreign clients.
  168 
  169 5. Calculation of digests and symmetric encryption
  170  OpenSSL provides specific commands (like sha1, aes etc) for calculation
  171  of digests and symmetric encryption. Since such commands cannot be
  172  added dynamically, no such commands are provided for GOST algorithms.
  173  Use generic commands 'dgst' and 'enc'.
  174 
  175  Calculation of GOST R 34.11-94 message digest
  176 
  177  openssl dgst -md_gost94 datafile
  178 
  179  Note that GOST R 34.11-94 specifies that digest value should be
  180  interpreted as little-endian number, but OpenSSL outputs just hex dump
  181  of digest value.
  182 
  183  So, to obtain correct digest value, such as produced by gostsum utility
  184  included in the engine distribution, bytes of output should be
  185  reversed.
  186  
  187  Calculation of HMAC based on GOST R 34.11-94
  188 
  189  openssl dgst -md_gost94 -mac hmac -macopt key:<32 bytes of key> datafile
  190   
  191   (or use hexkey if key contain NUL bytes)
  192  Calculation of GOST 28147 MAC
  193 
  194  openssl dgst -mac gost-mac -macopt key:<32 bytes of key> datafile
  195 
  196  Note absence of an option that specifies digest algorithm. gost-mac
  197  algorithm supports only one digest (which is actually part of
  198  implementation of this mac) and OpenSSL is clever enough to find out
  199  this.
  200 
  201  Encryption with GOST 28147 CFB mode
  202  openssl enc -gost89 -out encrypted-file -in plain-text-file -k <passphrase>  
  203  Encryption with GOST 28147 CNT mode
  204  openssl enc -gost89-cnt -out encrypted-file -in plain-text-file -k <passphrase>
  205 
  206 
  207 6. Encrypting private keys and PKCS12
  208 
  209 To produce PKCS12 files compatible with MagPro CSP, you need to use
  210 GOST algorithm for encryption of PKCS12 file and also GOST R 34.11-94
  211 hash to derive key from password.
  212 
  213 openssl pksc12 -export -inkey gost.pem -in gost_cert.pem -keypbe gost89\
  214    -certpbe gost89 -macalg md_gost94
  215  
  216 7. Testing speed of symmetric ciphers.
  217    
  218 To test performance of GOST symmetric ciphers you should use -evp switch
  219 of the openssl speed command. Engine-provided ciphers can be accessed only via
  220 generic evp interface and not by cipher-specific functions.
  221 
  222  openssl speed -evp gost89
  223  openssl speed -evp gost89-cnt
  224 
  225 
  226 PROGRAMMING INTERFACES DETAILS
  227 
  228 Applications should never access engine directly. They should only use provided
  229 EVP_PKEY API. But there are some details, which should be taken into
  230 account.
  231 
  232 EVP provides two kinds of API for key exchange:
  233 
  234 1. EVP_PKEY_encrypt/EVP_PKEY_decrypt functions, intended to use with
  235 	RSA-like public key encryption algorithms
  236 
  237 2. EVP_PKEY_derive, intended to use with Diffie-Hellman-like shared key
  238 computing algorithms.
  239 
  240 Although VKO R 34.10 algorithms, described in the RFC 4357 are
  241 definitely second case, engine provides BOTH API for GOST R 34.10 keys.
  242 
  243 EVP_PKEY_derive just invokes appropriate VKO algorithm and computes
  244 256 bit shared key. VKO R 34.10-2001 requires 64 bits of random user key
  245 material (UKM). This UKM should be transmitted to other party, so it is
  246 not generated inside derive function.
  247 
  248 It should be set by EVP_PKEY_CTX_ctrl function using
  249 EVP_PKEY_CTRL_SET_IV command after call of EVP_PKEY_derive_init, but
  250 before EVP_PKEY_derive.
  251 	unsigned char ukm[8];
  252 	RAND_bytes(ukm,8);
  253    EVP_PKEY_CTX_ctrl(ctx, -1, EVP_PKEY_OP_DERIVE, 8, ukm)
  254 
  255 EVP_PKEY_encrypt encrypts provided session key with VKO shared key and
  256 packs it into GOST key transport structure, described in the RFC 4490.
  257 
  258 It typically uses ephemeral key pair to compute shared key and packs its
  259 public part along with encrypted key. So, for most cases use of 
  260 EVP_PKEY_encrypt/EVP_PKEY_decrypt with GOST keys is almost same as with
  261 RSA.
  262 
  263 However, if peerkey field in the EVP_PKEY_CTX structure is set (using
  264 EVP_PKEY_derive_set_peerkey function) to EVP_PKEY structure which has private
  265 key and uses same parameters as the public key from which this EVP_PKEY_CTX is
  266 created, EVP_PKEY_encrypt will use this private key to compute shared key and
  267 set ephemeral key in the GOST_key_transport structure to NULL. In this case
  268 pkey and peerkey fields in the EVP_PKEY_CTX are used upside-down.
  269 
  270 If EVP_PKEY_decrypt encounters GOST_key_transport structure with NULL
  271 public key field, it tries to use peerkey field from the context to
  272 compute shared key. In this case peerkey field should really contain
  273 peer public key.
  274 
  275 Encrypt operation supports EVP_PKEY_CTRL_SET_IV operation as well.
  276 It can be used when some specific restriction on UKM are imposed by
  277 higher level protocol. For instance, description of GOST ciphersuites
  278 requires UKM to be derived from shared secret. 
  279 
  280 If UKM is not set by this control command, encrypt operation would
  281 generate random UKM.
  282 
  283 
  284 These sources include implementation of GOST 28147-89 and GOST R 34.11-94
  285 which are completely independent from OpenSSL and can be used separately
  286 (files gost89.c, gost89.h, gosthash.c, gosthash.h). Utility gostsum (file
  287 gostsum.c) is provided as an example of such separate usage. This program is
  288 similar to md5sum and sha1sum utilities, but calculates GOST R 34.11-94 hash.
  289 
  290 Makefile doesn't include rule for compiling gostsum.
  291 Use command
  292 
  293 $(CC) -o gostsum gostsum.c gost89.c gosthash.c
  294 where $(CC) is name of your C compiler.
  295 
  296 Implementations of GOST R 34.10-xx, including VKO algorithms heavily
  297 depends on OpenSSL BIGNUM and Elliptic Curve libraries.
  298 
  299