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