www.texi

   1 \input texinfo
   2 @documentencoding UTF-8
   3 @settitle PyGOST
   4
   5 @copying
   6 Copyright @copyright{} 2015-2016 @email{stargrave@@stargrave.org, Sergey Matveev}
   7 @end copying
   8
   9 @node Top
  10 @top PyGOST
  11
  12 PyGOST is pure Python 2.7/3.x GOST cryptographic functions library.
  13 GOST is GOvernment STandard of Russian Federation (and Soviet Union).
  14 It is
  15 @url{https://www.gnu.org/philosophy/pragmatic.html, copylefted}
  16 @url{https://www.gnu.org/philosophy/free-sw.html, free software}:
  17 licenced under @url{https://www.gnu.org/licenses/gpl-3.0.html, GPLv3+}.
  18 You can read about GOST algorithms @url{http://www.cypherpunks.ru/gost/, more}.
  19
  20 Currently supported algorithms are:
  21
  22 @itemize
  23 @item GOST 28147-89 (@url{https://tools.ietf.org/html/rfc5830.html, RFC 5830})
  24     block cipher with ECB, CNT (CTR), CFB, MAC,
  25     CBC (@url{https://tools.ietf.org/html/rfc4357.html, RFC 4357})
  26     modes of operation
  27 @item various 28147-89-related S-boxes included
  28 @item GOST R 34.11-94 hash function
  29     (@url{https://tools.ietf.org/html/rfc5831.html, RFC 5831})
  30 @item GOST R 34.11-94 based @url{https://en.wikipedia.org/wiki/PBKDF2, PBKDF2} function
  31 @item GOST R 34.11-2012 Стрибог (Streebog) hash function
  32     (@url{https://tools.ietf.org/html/rfc6986.html, RFC 6986})
  33 @item GOST R 34.10-2001
  34     (@url{https://tools.ietf.org/html/rfc5832.html, RFC 5832})
  35     public key signature function
  36 @item GOST R 34.10-2012
  37     (@url{https://tools.ietf.org/html/rfc7091.html, RFC 7091})
  38     public key signature function
  39 @item various 34.10 curve parameters included
  40 @item VKO GOST R 34.10-2001 Diffie-Hellman function
  41     (@url{https://tools.ietf.org/html/rfc4357.html, RFC 4357})
  42 @item VKO GOST R 34.10-2012 Diffie-Hellman function
  43     (@url{https://tools.ietf.org/html/rfc7836.html, RFC 7836})
  44 @item 28147-89 and CryptoPro key wrapping
  45     (@url{https://tools.ietf.org/html/rfc4357.html, RFC 4357})
  46 @item 28147-89 CryptoPro key meshing for CFB mode
  47     (@url{https://tools.ietf.org/html/rfc4357.html, RFC 4357})
  48 @item @url{https://tools.ietf.org/html/rfc4491.html, RFC 4491}
  49     (using GOST algorithms with X.509) compatibility helpers
  50 @item GOST R 34.12-2015 128-bit block cipher Кузнечик (Kuznechik)
  51     (@url{https://tools.ietf.org/html/rfc7801.html, RFC 7801})
  52 @item GOST R 34.13-2015 padding methods
  53 @item PEP247-compatible hash/MAC functions
  54 @end itemize
  55
  56 Example 34.10-2012 keypair generation, signing and verifying:
  57
  58 @verbatim
  59 >>> from pygost.gost3410 import CURVE_PARAMS
  60 >>> from pygost.gost3410 import GOST3410Curve
  61 >>> curve = GOST3410Curve(*CURVE_PARAMS["GostR3410_2012_TC26_ParamSetA"])
  62 >>> from os import urandom
  63 >>> prv_raw = urandom(32)
  64 >>> from pygost.gost3410 import prv_unmarshal
  65 >>> prv = prv_unmarshal(prv_raw)
  66 >>> from pygost.gost3410 import public_key
  67 >>> pub = public_key(curve, prv)
  68 >>> from pygost.gost3410 import pub_marshal
  69 >>> from pygost.utils import hexenc
  70 >>> print "Public key is:", hexenc(pub_marshal(pub))
  71 >>> from pygost import gost34112012256
  72 >>> data_for_signing = b"some data"
  73 >>> dgst = gost34112012256.new(data_for_signing).digest()
  74 >>> from pygost.gost3410 import sign
  75 >>> signature = sign(curve, prv, dgst, mode=2012)
  76 >>> from pygost.gost3410 import verify
  77 >>> verify(curve, pub, dgst, signature, mode=2012)
  78 True
  79 @end verbatim
  80
  81 Please send questions, bug reports and patches to
  82 @url{https://lists.cypherpunks.ru/mailman/listinfo/gost, gost}
  83 mailing list. Announcements also go to this mailing list.
  84
  85 @insertcopying
  86
  87 @node News
  88 @unnumbered News
  89
  90 @table @strong
  91 @item 3.0
  92     @itemize
  93     @item @code{gost3411_94} renamed to @code{gost341194}
  94     @item @code{gost3411_2012} renamed and split to
  95         @code{gost34112012256}, @code{gost34112012512}
  96     @item @code{GOST34112012} split to
  97         @code{GOST34112012256}, @code{GOST34112012512}
  98     @item @code{gost3410.kek} moved to separate
  99         @code{gost3410_vko.kek_34102001}
 100     @item VKO GOST R 34.10-2012 appeared in @code{gost3410_vko},
 101         with test vectors
 102     @item 34.11-94 digest is reversed, to be compatible with HMAC and
 103         PBKDF2 test vectors describe in TC26 documents
 104     @item 34.11-94 PBKDF2 test vectors added
 105     @item @code{gost3410.prv_unmarshal},
 106         @code{gost3410.pub_marshal},
 107         @code{gost3410.pub_unmarshal}
 108         helpers added, removing the need of @code{x509} module at all
 109     @item @code{gost3410.verify} requires @code{(pubX, pubY)} tuple,
 110         instead of two separate @code{pubX}, @code{pubY} arguments
 111     @item 34.11-94 based PBKDF2 function added
 112     @end itemize
 113
 114 @item 2.4
 115 Fixed 34.13 mypy stub.
 116
 117 @item 2.3
 118 Typo and pylint fixes.
 119
 120 @item 2.2
 121 GOST R 34.13-2015 padding methods
 122
 123 @item 2.1
 124 Documentation and supplementary files refactoring.
 125
 126 @item 2.0
 127 PEP-0247 compatible hashers and MAC.
 128
 129 @item 1.0
 130     @itemize
 131     @item Ability to specify curve in pygost.x509 module
 132     @item Ability to use 34.10-2012 in pygost.x509 functions
 133     @end itemize
 134
 135     Renamed classes and modules:
 136
 137     @itemize
 138     @item pygost.gost3410.SIZE_34100 -> pygost.gost3410.SIZE_3410_2001
 139     @item pygost.gost3410.SIZE_34112 -> pygost.gost3410.SIZE_3410_2012
 140     @item pygost.gost3411_12.GOST341112 -> pygost.gost3411_2012.GOST34112012
 141     @end itemize
 142
 143 @item 0.16
 144 34.10-2012 TC26 curve parameters.
 145
 146 @item 0.15
 147 PEP-0484 static typing hints.
 148
 149 @item 0.14
 150 34.10-2012 workability fix.
 151
 152 @item 0.13
 153 Python3 compatibility.
 154
 155 @item 0.11
 156 GOST R 34.12-2015 Кузнечик (Kuznechik) implementation.
 157
 158 @item 0.10
 159 CryptoPro and GOST key wrapping, CryptoPro key meshing.
 160 @end table
 161
 162 @node Download
 163 @unnumbered Download
 164
 165 No additional dependencies except Python 2.7/3.x interpreter are required.
 166
 167 Preferable way is to download tarball with the signature:
 168
 169 @verbatim
 170 % wget http://www.cypherpunks.ru/pygost/pygost-2.3.tar.xz
 171 % wget http://www.cypherpunks.ru/pygost/pygost-2.3.tar.xz.sig
 172 % gpg --verify pygost-2.3.tar.xz.sig pygost-2.3.tar.xz
 173 % xz -d < pygost-2.3.tar.xz | tar xf -
 174 % cd pygost-2.3
 175 % python setup.py install
 176 @end verbatim
 177
 178 @multitable {XXXXX} {XXXX KiB} {link sign} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
 179 @headitem Version @tab Size @tab Tarball @tab SHA256 checksum @tab Streebog-256 checksum
 180
 181 @item 3.0 @tab 39 KiB
 182 @tab @url{pygost-3.0.tar.xz, link} @url{pygost-3.0.tar.xz.sig, sign}
 183 @tab @code{0AB10703 6960962D 30BD1646 ACC8D44B E9CBD8A8 4F25DF25 91F26383 DE28875F}
 184 @tab @code{ef4729df62b4f615a154a9c35ccffaf6bb614a23067f4dd49d2993ec93bb6665}
 185
 186 @item 2.4 @tab 37 KiB
 187 @tab @url{pygost-2.4.tar.xz, link} @url{pygost-2.4.tar.xz.sig, sign}
 188 @tab @code{94D14E99 3CF63973 6C8E78D0 5EBD0838 09A47624 C05A9878 11136301 C0A07264}
 189 @tab @code{b107b5ba043a2e4c30d9348e222b92218b8dff9d672964ffd04259c5261bc5a7}
 190
 191 @item 2.3 @tab 37 KiB
 192 @tab @url{pygost-2.3.tar.xz, link} @url{pygost-2.3.tar.xz.sig, sign}
 193 @tab @code{FF2C7E78 F3677B45 EB472DC6 1837C72C 0BD72387 AB0A9DC7 AD88AD11 59589732}
 194 @tab @code{42cfd0cdf357997a909a9114ca14391b4c5e8b62e298675f899b80a8a26d690f}
 195
 196 @end multitable
 197
 198 But also you can use PIP (@strong{no} authentication is performed!):
 199
 200 @verbatim
 201 % pip install pygost==2.3
 202 @end verbatim
 203
 204 You @strong{have to} verify downloaded tarballs integrity and
 205 authenticity to be sure that you retrieved trusted and untampered
 206 software. @url{https://www.gnupg.org/, The GNU Privacy Guard} is used
 207 for that purpose.
 208
 209 For the very first time it it necessary to get signing public key and
 210 import it. It is provided below, but you should check alternative
 211 resources.
 212
 213 @verbatim
 214 pub   rsa2048/0xE6FD1269CD0C009E 2016-09-13
 215       F55A 7619 3A0C 323A A031  0E6B E6FD 1269 CD0C 009E
 216 uid   PyGOST releases <pygost at cypherpunks dot ru>
 217 @end verbatim
 218
 219 @itemize
 220
 221 @item @url{https://lists.cypherpunks.ru/mailman/listinfo/gost, gost} maillist
 222
 223 @item
 224 @verbatim
 225 % gpg --keyserver hkp://keys.gnupg.net/ --recv-keys 0xE6FD1269CD0C009E
 226 % gpg --auto-key-locate dane --locate-keys pygost at cypherpunks dot ru
 227 % gpg --auto-key-locate wkd --locate-keys pygost at cypherpunks dot ru
 228 % gpg --auto-key-locate pka --locate-keys pygost at cypherpunks dot ru
 229 @end verbatim
 230
 231 @item
 232 @verbatiminclude PUBKEY.asc
 233
 234 @end itemize
 235
 236 You can obtain development source code by cloning
 237 @url{http://git-scm.com/, Git}
 238 @url{https://git.cypherpunks.ru/cgit.cgi/pygost.git/}.
 239
 240 @bye