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