www.texi

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