README 4.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103
  1. Python Cryptography Toolkit (pycrypto)
  2. ======================================
  3. This is a collection of both secure hash functions (such as SHA256 and
  4. RIPEMD160), and various encryption algorithms (AES, DES, RSA, ElGamal,
  5. etc.). The package is structured to make adding new modules easy.
  6. This section is essentially complete, and the software interface will
  7. almost certainly not change in an incompatible way in the future; all
  8. that remains to be done is to fix any bugs that show up. If you
  9. encounter a bug, please report it in the Launchpad bug tracker at
  10. https://launchpad.net/products/pycrypto/+bugs
  11. An example usage of the SHA256 module is:
  12. >>> from Crypto.Hash import SHA256
  13. >>> hash = SHA256.new()
  14. >>> hash.update('message')
  15. >>> hash.digest()
  16. '\xabS\n\x13\xe4Y\x14\x98+y\xf9\xb7\xe3\xfb\xa9\x94\xcf\xd1\xf3\xfb"\xf7\x1c\xea\x1a\xfb\xf0+F\x0cm\x1d'
  17. An example usage of an encryption algorithm (AES, in this case) is:
  18. >>> from Crypto.Cipher import AES
  19. >>> obj = AES.new('This is a key456', AES.MODE_ECB)
  20. >>> message = "The answer is no"
  21. >>> ciphertext = obj.encrypt(message)
  22. >>> ciphertext
  23. 'o\x1aq_{P+\xd0\x07\xce\x89\xd1=M\x989'
  24. >>> obj2 = AES.new('This is a key456', AES.MODE_ECB)
  25. >>> obj2.decrypt(ciphertext)
  26. 'The answer is no'
  27. One possible application of the modules is writing secure
  28. administration tools. Another application is in writing daemons and
  29. servers. Clients and servers can encrypt the data being exchanged and
  30. mutually authenticate themselves; daemons can encrypt private data for
  31. added security. Python also provides a pleasant framework for
  32. prototyping and experimentation with cryptographic algorithms; thanks
  33. to its arbitrary-length integers, public key algorithms are easily
  34. implemented.
  35. As of PyCrypto 2.1.0, PyCrypto provides an easy-to-use random number
  36. generator:
  37. >>> from Crypto import Random
  38. >>> rndfile = Random.new()
  39. >>> rndfile.read(16)
  40. '\xf7.\x838{\x85\xa0\xd3>#}\xc6\xc2jJU'
  41. A stronger version of Python's standard "random" module is also
  42. provided:
  43. >>> from Crypto.Random import random
  44. >>> random.choice(['dogs', 'cats', 'bears'])
  45. 'bears'
  46. Caveat: For the random number generator to work correctly, you must
  47. call Random.atfork() in both the parent and child processes after
  48. using os.fork()
  49. Installation
  50. ============
  51. PyCrypto is written and tested using Python version 2.1 through 3.2. Python
  52. 1.5.2 is not supported.
  53. The modules are packaged using the Distutils, so you can simply run
  54. "python setup.py build" to build the package, and "python setup.py
  55. install" to install it.
  56. If the setup.py script crashes with a DistutilsPlatformError
  57. complaining that the file /usr/lib/python2.2/config/Makefile doesn't
  58. exist, this means that the files needed for compiling new Python
  59. modules aren't installed on your system. Red Hat users often run into
  60. this because they don't have the python2-devel RPM installed. The fix
  61. is to simply install the requisite RPM. On Debian/Ubuntu, you need the
  62. python-dev package.
  63. To verify that everything is in order, run "python setup.py test". It
  64. will test all the cryptographic modules, skipping ones that aren't
  65. available. If the test script reports an error on your machine,
  66. please report the bug using the bug tracker (URL given above). If
  67. possible, track down the bug and include a patch that fixes it,
  68. provided that you are able to meet the eligibility requirements at
  69. http://www.pycrypto.org/submission-requirements/.
  70. It is possible to test a single sub-package or a single module only, for instance
  71. when you investigate why certain tests fail and don't want to run the whole
  72. suite each time. Use "python setup.py test --module=name", where 'name'
  73. is either a sub-package (Cipher, PublicKey, etc) or a module (Cipher.DES,
  74. PublicKey.RSA, etc).
  75. To further cut test coverage, pass also the option "--skip-slow-tests".
  76. To install the package under the site-packages directory of
  77. your Python installation, run "python setup.py install".
  78. If you have any comments, corrections, or improvements for this
  79. package, please report them to our mailing list, accessible via the
  80. PyCrypto website:
  81. http://www.pycrypto.org/