www.texi

   1 \input texinfo
   2 @documentencoding UTF-8
   3 @settitle PyGOST
   4
   5 @copying
   6 Copyright @copyright{} 2015-2018 @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://gost.cypherpunks.ru/, 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 key agreement function
  41     (@url{https://tools.ietf.org/html/rfc4357.html, RFC 4357})
  42 @item VKO GOST R 34.10-2012 key agreement 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.12-2015 64-bit block cipher Магма (Magma)
  53 @item GOST R 34.13-2015 padding methods and block cipher modes of operation
  54       (ECB, CTR, OFB, CBC, CFB, MAC)
  55 @item PEP247-compatible hash/MAC functions
  56 @end itemize
  57
  58 Example 34.10-2012 keypair generation, signing and verifying:
  59
  60 @verbatim
  61 >>> from pygost.gost3410 import CURVE_PARAMS
  62 >>> from pygost.gost3410 import GOST3410Curve
  63 >>> curve = GOST3410Curve(*CURVE_PARAMS["GostR3410_2012_TC26_ParamSetA"])
  64 >>> from os import urandom
  65 >>> prv_raw = urandom(32)
  66 >>> from pygost.gost3410 import prv_unmarshal
  67 >>> prv = prv_unmarshal(prv_raw)
  68 >>> from pygost.gost3410 import public_key
  69 >>> pub = public_key(curve, prv)
  70 >>> from pygost.gost3410 import pub_marshal
  71 >>> from pygost.utils import hexenc
  72 >>> print "Public key is:", hexenc(pub_marshal(pub))
  73 >>> from pygost import gost34112012256
  74 >>> data_for_signing = b"some data"
  75 >>> dgst = gost34112012256.new(data_for_signing).digest()
  76 >>> from pygost.gost3410 import sign
  77 >>> signature = sign(curve, prv, dgst, mode=2012)
  78 >>> from pygost.gost3410 import verify
  79 >>> verify(curve, pub, dgst, signature, mode=2012)
  80 True
  81 @end verbatim
  82
  83 Please send questions, bug reports and patches to
  84 @url{https://lists.cypherpunks.ru/mailman/listinfo/gost, gost}
  85 mailing list. Announcements also go to this mailing list.
  86
  87 @insertcopying
  88
  89 @node News
  90 @unnumbered News
  91
  92 @table @strong
  93 @item 3.7
  94 Fixed 34.13-2015 OFB bug with IVs longer than 2 blocks.
  95
  96 @item 3.6
  97 Fixed source files installation during @command{setup.py install} invocation.
  98
  99 @item 3.5
 100 Dummy release: added long description in package metadata.
 101
 102 @item 3.4
 103 Small mypy stubs related fixes.
 104
 105 @item 3.3
 106     @itemize
 107     @item @code{GOST3412Kuz} renamed to @code{GOST3412Kuznechik}
 108     @item @code{GOST3412Magma} implements GOST R 34.12-2015 Magma 64-bit
 109         block cipher
 110     @end itemize
 111
 112 @item 3.2
 113 34.13-2015 block cipher modes of operation implementations.
 114
 115 @item 3.1
 116 Fixed mypy stubs related to PEP247-successors.
 117
 118 @item 3.0
 119     @itemize
 120     @item @code{gost3411_94} renamed to @code{gost341194}
 121     @item @code{gost3411_2012} renamed and split to
 122         @code{gost34112012256}, @code{gost34112012512}
 123     @item @code{GOST34112012} split to
 124         @code{GOST34112012256}, @code{GOST34112012512}
 125     @item @code{gost3410.kek} moved to separate
 126         @code{gost3410_vko.kek_34102001}
 127     @item VKO GOST R 34.10-2012 appeared in @code{gost3410_vko},
 128         with test vectors
 129     @item 34.11-94 digest is reversed, to be compatible with HMAC and
 130         PBKDF2 test vectors describe in TC26 documents
 131     @item 34.11-94 PBKDF2 test vectors added
 132     @item @code{gost3410.prv_unmarshal},
 133         @code{gost3410.pub_marshal},
 134         @code{gost3410.pub_unmarshal}
 135         helpers added, removing the need of @code{x509} module at all
 136     @item @code{gost3410.verify} requires @code{(pubX, pubY)} tuple,
 137         instead of two separate @code{pubX}, @code{pubY} arguments
 138     @item 34.11-94 based PBKDF2 function added
 139     @end itemize
 140
 141 @item 2.4
 142 Fixed 34.13 mypy stub.
 143
 144 @item 2.3
 145 Typo and pylint fixes.
 146
 147 @item 2.2
 148 GOST R 34.13-2015 padding methods
 149
 150 @item 2.1
 151 Documentation and supplementary files refactoring.
 152
 153 @item 2.0
 154 PEP-0247 compatible hashers and MAC.
 155
 156 @item 1.0
 157     @itemize
 158     @item Ability to specify curve in pygost.x509 module
 159     @item Ability to use 34.10-2012 in pygost.x509 functions
 160     @end itemize
 161
 162     Renamed classes and modules:
 163
 164     @itemize
 165     @item pygost.gost3410.SIZE_34100 -> pygost.gost3410.SIZE_3410_2001
 166     @item pygost.gost3410.SIZE_34112 -> pygost.gost3410.SIZE_3410_2012
 167     @item pygost.gost3411_12.GOST341112 -> pygost.gost3411_2012.GOST34112012
 168     @end itemize
 169
 170 @item 0.16
 171 34.10-2012 TC26 curve parameters.
 172
 173 @item 0.15
 174 PEP-0484 static typing hints.
 175
 176 @item 0.14
 177 34.10-2012 workability fix.
 178
 179 @item 0.13
 180 Python3 compatibility.
 181
 182 @item 0.11
 183 GOST R 34.12-2015 Кузнечик (Kuznechik) implementation.
 184
 185 @item 0.10
 186 CryptoPro and GOST key wrapping, CryptoPro key meshing.
 187 @end table
 188
 189 @node Download
 190 @unnumbered Download
 191
 192 No additional dependencies except Python 2.7/3.x interpreter are required.
 193
 194 Preferable way is to download tarball with the signature:
 195
 196 @verbatim
 197 % wget http://pygost.cypherpunks.ru/pygost-3.7.tar.xz
 198 % wget http://pygost.cypherpunks.ru/pygost-3.7.tar.xz.sig
 199 % gpg --verify pygost-3.7.tar.xz.sig pygost-3.7.tar.xz
 200 % xz -d < pygost-3.7.tar.xz | tar xf -
 201 % cd pygost-3.7
 202 % python setup.py install
 203 @end verbatim
 204
 205 @multitable {XXXXX} {XXXX KiB} {link sign} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
 206 @headitem Version @tab Size @tab Tarball @tab SHA256 checksum @tab Streebog-256 checksum
 207
 208 @item 3.7 @tab 43 KiB
 209 @tab @url{pygost-3.7.tar.xz, link} @url{pygost-3.7.tar.xz.sig, sign}
 210 @tab @code{2BE1647A 2ED7C794 7B80EBFA 32EB71B1 2AA95711 71CAA0CE E8319BF7 17361E28}
 211 @tab @code{b76ba4964a61b15a65be60c19d85063b88222fff881d9a9a8ff7dd8a07b2fc67}
 212
 213 @item 3.6 @tab 43 KiB
 214 @tab @url{pygost-3.6.tar.xz, link} @url{pygost-3.6.tar.xz.sig, sign}
 215 @tab @code{37EA8A31 B308DBC6 B3229922 ABA0355F 46008BEC 2649BF98 11F62091 17BD94B3}
 216 @tab @code{47495afde7218e5d01160800daa0f9c786f5c95579686b0ce5a37fb7550bc735}
 217
 218 @item 3.5 @tab 43 KiB
 219 @tab @url{pygost-3.5.tar.xz, link} @url{pygost-3.5.tar.xz.sig, sign}
 220 @tab @code{14E504AE 81E74DDD 122E5BF1 0B9E25D7 82D51AB6 5ED43533 0BF276A4 8A7C7AA4}
 221 @tab @code{eb2106523cf8ed1b462d7a0a57f771f94759047a7e0e5a0b96ee35b24293e264}
 222
 223 @item 3.4 @tab 43 KiB
 224 @tab @url{pygost-3.4.tar.xz, link} @url{pygost-3.4.tar.xz.sig, sign}
 225 @tab @code{89715612 8A197071 AD7689FA 96F89304 19E42F76 87632309 B47E5FDE 1AD6126D}
 226 @tab @code{e590ddc7485e6f99658f26ac23cd2266648f27efa584a33f93abec8b80e1771d}
 227
 228 @item 3.3 @tab 41 KiB
 229 @tab @url{pygost-3.3.tar.xz, link} @url{pygost-3.3.tar.xz.sig, sign}
 230 @tab @code{D118F539 537CCD5D 9CCE850E DD8EFD8E ACDA9D6E 0C113A0F C575574A F4BD452A}
 231 @tab @code{8400a3714b70dddfef03f6fe96325e73ac25db814d052a44dbd8f2ce5ddb05bb}
 232
 233 @item 3.2 @tab 41 KiB
 234 @tab @url{pygost-3.2.tar.xz, link} @url{pygost-3.2.tar.xz.sig, sign}
 235 @tab @code{6779D1B1 A4E2B1C3 49CA39F8 425FC962 AF2ED133 BB495343 0F83764B E2624087}
 236 @tab @code{0a39880ad00ca11d112fef096b81a42a85ce4e5b25c48d1f643858b1e0c520d6}
 237
 238 @item 3.1 @tab 39 KiB
 239 @tab @url{pygost-3.1.tar.xz, link} @url{pygost-3.1.tar.xz.sig, sign}
 240 @tab @code{ACCCF1A9 F4B345FF 01595248 5B793DAC FCF71D1F 32A6ABCF 32042DDB 20897BC5}
 241 @tab @code{823961b6c2a1abe83f6d828397002e68d711a08ce115f21ddff81a294882cd46}
 242
 243 @item 3.0 @tab 39 KiB
 244 @tab @url{pygost-3.0.tar.xz, link} @url{pygost-3.0.tar.xz.sig, sign}
 245 @tab @code{0AB10703 6960962D 30BD1646 ACC8D44B E9CBD8A8 4F25DF25 91F26383 DE28875F}
 246 @tab @code{ef4729df62b4f615a154a9c35ccffaf6bb614a23067f4dd49d2993ec93bb6665}
 247
 248 @item 2.4 @tab 37 KiB
 249 @tab @url{pygost-2.4.tar.xz, link} @url{pygost-2.4.tar.xz.sig, sign}
 250 @tab @code{94D14E99 3CF63973 6C8E78D0 5EBD0838 09A47624 C05A9878 11136301 C0A07264}
 251 @tab @code{b107b5ba043a2e4c30d9348e222b92218b8dff9d672964ffd04259c5261bc5a7}
 252
 253 @item 2.3 @tab 37 KiB
 254 @tab @url{pygost-2.3.tar.xz, link} @url{pygost-2.3.tar.xz.sig, sign}
 255 @tab @code{FF2C7E78 F3677B45 EB472DC6 1837C72C 0BD72387 AB0A9DC7 AD88AD11 59589732}
 256 @tab @code{42cfd0cdf357997a909a9114ca14391b4c5e8b62e298675f899b80a8a26d690f}
 257
 258 @end multitable
 259
 260 But also you can use PIP (@strong{no} authentication is performed!):
 261
 262 @verbatim
 263 % pip install pygost==3.7
 264 @end verbatim
 265
 266 You @strong{have to} verify downloaded tarballs integrity and
 267 authenticity to be sure that you retrieved trusted and untampered
 268 software. @url{https://www.gnupg.org/, The GNU Privacy Guard} is used
 269 for that purpose.
 270
 271 For the very first time it is necessary to get signing public key and
 272 import it. It is provided below, but you should check alternative
 273 resources.
 274
 275 @verbatim
 276 pub   rsa2048/0xE6FD1269CD0C009E 2016-09-13
 277       F55A 7619 3A0C 323A A031  0E6B E6FD 1269 CD0C 009E
 278 uid   PyGOST releases <pygost at cypherpunks dot ru>
 279 @end verbatim
 280
 281 @itemize
 282
 283 @item @url{https://lists.cypherpunks.ru/mailman/listinfo/gost, gost} maillist
 284
 285 @item
 286 @verbatim
 287 % gpg --keyserver hkp://keys.gnupg.net/ --recv-keys 0xE6FD1269CD0C009E
 288 % gpg --auto-key-locate dane --locate-keys pygost at cypherpunks dot ru
 289 % gpg --auto-key-locate wkd --locate-keys pygost at cypherpunks dot ru
 290 % gpg --auto-key-locate pka --locate-keys pygost at cypherpunks dot ru
 291 @end verbatim
 292
 293 @item
 294 @verbatiminclude PUBKEY.asc
 295
 296 @end itemize
 297
 298 You can obtain development source code by cloning
 299 @url{http://git-scm.com/, Git}
 300 @url{https://git.cypherpunks.ru/cgit.cgi/pygost.git/}.
 301
 302 @bye