www.openxpki.org/trunk/src/htdocs/docs/gost-howto.html

   1 <%attr>
   2   title => 'Working with russian (GOST) cryptography'
   3 </%attr>
   4
   5 <h2>Working with russian (GOST) cryptography</h2>
   6 <h3>An example of using OpenXPKI with alternative cryptography</h3>
   7
   8 <p>
   9 Since late summer of 2006 a production branch of OpenSSL version 0.9.9 has a built-in support
  10 for arbitrary asymmetric cryptography, and provides an extended set
  11 of russian national algorithms (GOST) as an example of <em>foreign</em>
  12 cryptography.
  13 Today this OpenSSL-0.9.9 branch is far from the stable state. As soon as it
  14 stabilizes, the OpenXPKI project will surely support it. That is both
  15 classical RSA - DSA cryptography, and GOST cryptography will be supported
  16 simultaneously and by default and out of the box.
  17 </p>
  18 <p>
  19 For those who can not wait, provided here is a patched version of
  20 OpenSSL-0.9.8d equipped with the (same as in ver.0.9.9) set of GOST algorithms.
  21 This collection is called OpenSSL-0.9.8d-gost. It has
  22 full and simultaneous support of both western
  23 and russian cryptography. The recipes that follow have been tested to work with OpenXPKI
  24 at FreeBSD@Intel-32, FreeBSD@AMD-64, Debian@Intel-32 platforms. <em>Tested to work</em>
  25 here means that all built-in tests of the OpenXPKI pass ok, and that no
  26 cryptographic-backend-related errors were found while
  27 working with the OpenXPKI via web interface.
  28 </p>
  29 <p>
  30 Roughly today's procedure to prepare support for GOST in OpenXPKI is as follows:
  31 </p>
  32     <ul>
  33       <li>unzip a regular
  34 <a href="http://www.openssl.org/source/openssl-0.9.8d.tar.gz">OpenSSL-0.9.8d version</a>
  35 </li>
  36       <li>apply
  37 <a href="http://prdownloads.sourceforge.net/openxpki/openssl-asymm-0.9.8d-20061110.diff.gz">
  38 a patch</a>
  39 which enables support of arbitrary asymmetric cryptography,</li>
  40       <li>install thus patched OpenSSL version to a specially dedicated directory
  41            OPENSSL_INSTALLDIR, so that your system's OpenSSL installation is not violated,</li>
  42       <li>configure
  43 <a href="http://prdownloads.sourceforge.net/openxpki/engine-gost-20061110.tar.gz">
  44 engine-gost</a> (which is a set of GOST algoritms)
  45 to work with this OpenSSL and install it,</li>
  46     </ul>
  47 <p>
  48 The details of the above procedure are given in
  49 <a href="openssl-gost.sh">
  50 a shell script</a>.
  51 For simplicity it knows internet references for only one of many
  52 SourceForge mirrors to get tarballs from. To run this script you need to install <tt>wget</tt>.
  53 You may have to edit first lines of the script to match your system and preferences:
  54 </p>
  55     <ul>
  56       <li><tt>OPENSSL_SOURCEDIR</tt> points to the directory to which tarballs will be unzipped.</li>
  57       <li><tt>OPENSSL_INSTALLDIR</tt> points to the directory to which OpenSSL-gost software collection
  58           will be installed. Beware: this directrory will be cleaned before installing.</li>
  59       <li><tt>MAKE</tt> points to your gmake (on Linux it could be named just make).</li>
  60     </ul>
  61
  62 <p>
  63 If the script fails at a download stage, you can help it by downloading 3 needed tarballs
  64 manually from the references above, and placing all of them into <tt>OPENSSL_SOURCEDIR</tt>.
  65 After that re-run the script.
  66 <p>
  67 If successful, the above procedure adds support for the following cryptographic
  68 algorithms (named here as recognized by the OpenSSL library):
  69 </p>
  70     <ul>
  71       <li>md_gost94 message digest algorithm.</li>
  72       <li>gost89 symmetric encryption algorithm with 256 bit key.</li>
  73       <li>gost94 public key algorithm with 1024 bit public key.</li>
  74       <li>gost94cp public key algorithm with 1024 bit public key (CP mode<sup>1</sup>).</li>
  75       <li>gost2001 public key algorithm based on elliptic curves
  76                     with 512 bit public key.</li>
  77       <li>gost2001cp public key algorithm based on elliptic
  78                                         curves with 512 bit public key (CP mode<sup>1</sup>).</li>
  79     </ul>
  80 <p>
  81 To test GOST support at the library level try:
  82 </p>
  83 <pre>    ${OPENSSL_INSTALLDIR}/bin/openssl engine gost -t -c -vvvv
  84 </pre>
  85 </p><p>
  86     You should see something similar to the following:
  87 </p>
  88 <pre>
  89     (gost) GOST engine
  90      [gost89, md_gost94, gost94, gost94cp, gost2001, gost2001cp]
  91          [ available ]
  92 </pre>
  93 <h4>
  94 And do not forget to (re)install OpenXPKI based on the just installed OpenSSL-gost software
  95 collection.
  96 </h4>
  97 <p>
  98 Environment variables:
  99 </p>
 100 <pre>
 101     OPENSSL_PREFIX=${OPENSSL_INSTALLDIR}
 102     GOST_OPENSSL_ENGINE=${OPENSSL_INSTALLDIR}/lib/engines/libgost.so
 103 </pre>
 104 <p>
 105 should be defined while running the following commands related to the OpenXPKI's server:
 106 </p>
 107 <pre>
 108     perl Makefile.PL
 109     make
 110     make test
 111 </pre>
 112 <p>
 113 After that in addition to the usual western cryptography, users and administrators of
 114 OpenXPKI will be able to enjoy the following GOST public key algoritms
 115 (listed in the spelling of OpenXPKI):
 116 </p>
 117     <ul>
 118       <li><b>GOST94</b> (public key algorithm)</li>
 119       <li><b>GOST2001</b> (elliptic curves public key algorithm)</li>
 120       <li><b>GOST94CP</b> (public key algorithm in CP mode<sup>1</sup>)</li>
 121       <li><b>GOST2001CP</b> (elliptic curves public key algorithm in CP mode<sup>1</sup>)</li>
 122     </ul>
 123 <p>
 124 In full accord with X.509 standard, all these GOST* algorithms along with all DSA and RSA
 125 algorithms could be used to cross-sign certificates. Thus  chains of arbitrary algorithms
 126 could be found in certification chains of a given PKI.
 127 </p>
 128 <p>
 129 If environment variable:
 130 </p>
 131 <pre>
 132     GOST_OPENSSL_ENGINE
 133 </pre>
 134 <p>
 135 is UNDEFINED during make procedure for OpenXPKI server,
 136 then GOST-related tests of OpenXPKI are skipped, and support of GOST algorithms in OpenXPKI
 137 is suspended.
 138 This also applies to the case when cryptographic backend #1 is used
 139 (see <a href="crypto-plug.html">Cryptography abstraction concept</a>).
 140 Thus the presence of GOST-related code inside of the OpenXPKI makes no harm to the
 141 customer who does not have GOST-enabled cryptographic backend, or knows nothing about GOST.
 142 </p>
 143
 144 <hr/>
 145 <p>
 146 (<sup>1</sup>)
 147 Digital signature in CP mode has different byte ordering with respect to the
 148 regular mode. Strictly speaking this mode explicitly violates related Russian federal standards for
 149 digital signature. Nonetheless it is widely employed in some of the MSWindows-based applications.
 150 Supported here for compatibility.
 151 </p>
 152
 153
 154