diff --git a/Doc/conf.py b/Doc/conf.py index ed55529eb..c31bae80c 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -104,8 +104,7 @@ # documentation. html_theme_options = { "textcolor" : "#000000", - "headingcolor" : "#000000", - "linkcolor" : "#FF0000" + "headingcolor" : "#000000" } # Add any paths that contain custom themes here, relative to this directory. diff --git a/Doc/index.rst b/Doc/index.rst index 9109c392b..a9825b442 100644 --- a/Doc/index.rst +++ b/Doc/index.rst @@ -9,9 +9,7 @@ Welcome to PyCryptodome's documentation src/installation src/api src/examples - src/pycrypto - src/contributing - src/support + src/contribute_support src/future src/changelog src/license diff --git a/Doc/src/contributing.rst b/Doc/src/contribute_support.rst similarity index 61% rename from Doc/src/contributing.rst rename to Doc/src/contribute_support.rst index 5ce02f325..75877734d 100644 --- a/Doc/src/contributing.rst +++ b/Doc/src/contribute_support.rst @@ -1,12 +1,16 @@ -How to contribute -================= +Contribute and support +====================== - Do not be afraid to contribute with small and apparently insignificant improvements like correction to typos. Every change counts. - Read carefully the :doc:`license` of PyCryptodome. By submitting your code, - you acknowledge that you accept to release it according to those terms - to the public domain. If your contribution was partially copied or derived - from somewhere else, you must verify that the source is in the public domain. + you acknowledge that you accept to release it according to the terms described + in the license (*public domain*). As a fallback, you also accept to release it + under the `MIT license`_ in those jurisdictions that do not recognize public + domain works. +- You must disclaim which parts of your code in your contribution were partially + copied or derived from an existing source. Ensure that the original is in the + public domain. - You can propose changes in any way you find most convenient. However, the preferred approach is to: @@ -24,8 +28,14 @@ How to contribute - Add a short summary of the change to the file ``Changelog.rst``. - Add your name to the list of contributors in the file ``AUTHORS.rst``. +The PyCryptodome mailing list is hosted on `Google Groups `_. +You can mail any comment or question to *pycryptodome@googlegroups.com*. + +Bug reports can be filed on the `GitHub tracker `_. + .. _GitHub: https://github.com/Legrandin/pycryptodome .. _pull request: https://help.github.com/articles/using-pull-requests .. _PEP8: http://www.python.org/dev/peps/pep-0008/ +.. _MIT license: http://opensource.org/licenses/MIT .. _PEP257: http://legacy.python.org/dev/peps/pep-0257/ .. _Python 2.4: http://rgruet.free.fr/PQR24/PQR2.4.html diff --git a/Doc/src/features.rst b/Doc/src/features.rst index 8da99bb15..359756454 100644 --- a/Doc/src/features.rst +++ b/Doc/src/features.rst @@ -1,7 +1,18 @@ Features -------- -* Symmetric cipher algorithms: +This page lists the low-level primitives that PyCryptodome provides. + +You are expected to have a solid understanding of cryptography and security +engineering to successfully use them. + +You must also be able to recognize that some primitives are obsolete (e.g. TDES) +or even unsecure (RC4). They are provided only to enable backward compatibility +where required by the applications. + +A list of useful resources in that area can be found on `Matthew Green's blog`_. + +* Symmetric ciphers: - AES - Single and Triple DES @@ -24,12 +35,12 @@ Features - GCM (AES only) - SIV (AES only) -* Stream cipher algorithms: +* Stream ciphers: - Salsa20 - RC4 -* Hash algorithms: +* Cryptographic hashes: - SHA-1 - SHA-2 family (224, 256, 384, 512) @@ -37,12 +48,12 @@ Features - RIPE-MD160 - MD5 -* Message Authentication Code (MAC) algorithms: +* Message Authentication Codes (MAC): - HMAC - CMAC -* Key generation for asymmetric algorithms: +* Asymmetric key generation: - RSA - DSA @@ -54,14 +65,14 @@ Features - PKCS#8 (clear and encrypted) - ASN.1 DER -* Public Key encryption algorithms: +* Asymmetric ciphers: - PKCS#1 - RSAES-PKCS1-v1_5 - RSAES-OAEP -* Public Key signature algorithms: +* Asymmtric digital signatures: - PKCS#1 @@ -73,7 +84,7 @@ Features - FIPS 186-3 - Deterministic (RFC6979) -* Key derivation algorithms: +* Key derivation: - PBKDF1 - PBKDF2 @@ -91,4 +102,4 @@ Features - ISO-7816 - X.923 - +.. _`Matthew Green's blog`: http://blog.cryptographyengineering.com/p/useful-cryptography-resources.html diff --git a/Doc/src/introduction.rst b/Doc/src/introduction.rst index 34d8f8aab..fd5dea8c1 100644 --- a/Doc/src/introduction.rst +++ b/Doc/src/introduction.rst @@ -6,3 +6,26 @@ cryptographic primitives. It supports Python 2.4 or newer, all Python 3 versions and PyPy. +All the code can be downloaded from `GitHub`_. + +PyCryptodome is not a wrapper to a separate C library like *OpenSSL*. +To the largest possible extent, algorithms are implemented in pure Python. +Only the pieces that are extremely critical to performance (e.g. block ciphers) +are implemented as C extensions. + +PyCryptodome and PyCrypto +------------------------- + +PyCryptodome is a recent fork of the `PyCrypto `_ project. +At the time of the fork (May 2014), the last official PyCrypto release was v2.6 and v2.7 was in alpha stage. + +The fork took place because PyCrypto had gone almost unmaintained for the past four years. +New features were considered for inclusion on average after more than 1 year they +were originally submitted, even if they concerned fundamental primitives for any modern +security software (PKCS#1 paddings, AEAD modes, tools for importing/exporting keys, +scrypt KDF, etc). + +Additionally, it was felt that too little attention was paid to having a good, detailed +API documentation and too much to performance optimizations. + +.. _GitHub: https://github.com/Legrandin/pycryptodome diff --git a/Doc/src/pycrypto.rst b/Doc/src/pycrypto.rst deleted file mode 100644 index 90de0b35c..000000000 --- a/Doc/src/pycrypto.rst +++ /dev/null @@ -1,21 +0,0 @@ -PyCryptodome and PyCrypto -------------------------- - -PyCryptodome is a recent fork of the `PyCrypto `_ project. -At the time of the fork, the last official PyCrypto release was v2.6 and v2.7 was in alpha stage. - -The fork took place because PyCrypto had been almost unmaintained for the past four years. -New features were considered for inclusion on average after more than 1 year they -were originally submitted, even if they concerned fundamental primitives for any modern -security software (PKCS#1 paddings, AEAD modes, tools for importing/exporting keys, -scrypt KDF, etc). - -Additionally, it was felt that too little attention was paid to having a good, detailed -API documentation and too much to performance optimizations. - -.. note:: - - PyCryptodome resides in the same namespace of PyCrypto (``Crypto``). - If your system includes a packaged version of PyCrypto, it is recommended you only install - PyCryptodome in a *virtualenv* environment. - diff --git a/Doc/src/support.rst b/Doc/src/support.rst deleted file mode 100644 index 3fc46f028..000000000 --- a/Doc/src/support.rst +++ /dev/null @@ -1,9 +0,0 @@ -Support -------- - -The PyCryptodome mailing list is hosted on `Google Groups `_. -You can mail any comment or question to *pycryptodome@googlegroups.com*. - -Bug reports can be filed on the `GitHub tracker `_. - - diff --git a/INSTALL.rst b/INSTALL.rst index 8b4a9f666..135cc485f 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -1,64 +1,152 @@ Installation ------------ -Linux/Unix -~~~~~~~~~~ +The procedures below all perform the same actions, just in different operating systems: -Set up your environment so that you can compile Python C extensions via ``pip``. -It is also recommeded you install ``virtualenv`` and the development libraries for the GMP library. +#. Install ``virtualenv`` +#. Install a C compiler +#. Create a virtual environment (and install ``pip`` in it) +#. Download PyCryptodome from ``pypi`` +#. Compile the C extensions of PyCryptodome +#. Install PyCryptodome in the virtual environment -On a platform like Ubuntu, for Python 2.x, that can be done with:: +.. note:: - $ sudo apt-get install build-essential libgmp3-dev python-virtualenv - $ sudo apt-get install python-pip python-dev + PyCryptodome resides in the same namespace of PyCrypto (``Crypto``). + In order to avoid any possible conflict, these instructions do not + install PyCryptodome at the system level. + +Linux Ubuntu +~~~~~~~~~~~~ + +For Python 2.x:: + + $ sudo apt-get install build-essential libgmp3-dev + $ sudo apt-get install python-virtualenv python-dev + $ virtualenv -p /usr/bin/python2 MyProject + $ cd MyProject + $ . bin/activate + $ pip install pycryptodome + +For Python 3.x:: + + $ sudo apt-get install build-essential libgmp3-dev + $ sudo apt-get install python-virtualenv python3-dev + $ virtualenv -p /usr/bin/python3 MyProject + $ cd MyProject + $ . bin/activate + $ pip install pycryptodome + +For PyPy:: + + $ sudo apt-get install build-essential libgmp3-dev + $ sudo apt-get install python-virtualenv pypy-dev + $ virtualenv -p /usr/bin/pypy MyProject + $ cd MyProject + $ . bin/activate + $ pip install pycryptodome + +Linux Fedora +~~~~~~~~~~~~ + +For Python 2.x:: + + $ sudo yum install gcc gmp-devel + $ sudo yum install python-virtualenv python-devel + $ virtualenv -p /usr/bin/python2 MyProject + $ cd MyProject + $ . bin/activate + $ pip install pycryptodome For Python 3.x:: - $ sudo apt-get install build-essential libgmp3-dev python-virtualenv - $ sudo apt-get install python3-pip python3-dev + $ sudo yum install gcc gmp-devel + $ sudo yum install python-virtualenv python3-devel + $ virtualenv -p /usr/bin/python3 MyProject + $ cd MyProject + $ . bin/activate + $ pip install pycryptodome -Once the (virtual) environment is in place, proceed with:: +For PyPy:: - $ pip install pycryptodome + $ sudo apt-get install build-essential libgmp3-dev + $ sudo apt-get install python-virtualenv pypy-devel + $ virtualenv -p /usr/bin/pypy MyProject + $ cd MyProject + $ . bin/activate + $ pip install pycryptodome Windows ~~~~~~~ -First, unless you have Python 3.4 or newer, install ``pip`` as explained on -the `official installation page `_. -Python 3.4 ships with ``pip`` by default. +.. note:: -Second, install a Visual Studio C++ compiler that matches the runtime your Python -is linked to. + Installing a Python package with C extensions (like PyCryptodome) + is clearly very complicated on Windows. + In the future, pre-compiled binaries will be made available + as `Python wheels `_ on ``pypi``. -That means: +#. Make sure the directory where your Python is installed and its subdirectory ``Scripts`` + are included in your ``PATH`` environmental variable. - * For Python 3.2 or older (including all 2.x), Visual C++ Compiler 2008 from the `MS Windows SDK for Windows 7 and .NET Framework 3.5 SP1 `_. - * For Python 3.3 or newer, Visual C++ Compiler 2010 from the `MS Windows SDK for Windows 7 and .NET Framework 4 `_. +#. You need to know exactly the version of Python you have and + whether it is a 32 bit or a 64 bit application. + You can easily discover that by running the interpreter from the command + prompt. Look at the very first line it prints. -For 32 bit versions of Python, download the file ``GRMSDK_EN_DVD.iso``, open a command -prompt and execute the following steps:: + For instance, if you see:: - > "C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\vcvars32.bat" - > set MSSdk=1 - > setenv /x86 /release - > set DISTUTILS_USE_SDK=1 + Python 2.7.2+ ... [MSC v.1500 32 bit (Intel)] on win32 -replace *9.0* with *10.0* depending on the version of Visual Studio. + You clearly have Python 2.7 and it is a 32 bit application. -For 64 bit version of Python, download the file ``GRMSDKX_EN_DVD.iso``, open a command -prompt and execute the following steps:: +#. **[Skip if you have Python 3.4 or newer]** Install ``pip`` by downloading and executing + the Python script `get-pip.py`_:: - > "C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\vcvars64.bat" - > set MSSdk=1 - > setenv /x64 /release + > python get-pip.py + +#. Install ``virtualenv`` with:: + + > pip install virtualenv + +#. Install a Visual Studio C++ (MSVC) compiler that matches the runtime your Python + is linked to. The good news is that the compilers can be found inside some Microsoft SDKs + that are available free of charge from the Microsoft website. + The bad news is that you need to download between 500MB and 1.4GB of data that mostly you will not need. + + The specific Microsoft SDK to download depends on the version of Python you have: + + * For Python 3.2 or older (including all 2.x), you need Visual C++ Compiler **2008** from the `MS Windows SDK for Windows 7 and .NET Framework 3.5 SP1`_. + * For Python 3.3 or newer, you need Visual C++ Compiler **2010** from the `MS Windows SDK for Windows 7 and .NET Framework 4`_. + + In either case, you will be given the possibility to download three different ISO files. + Most probably, these days you have a 64 bit version of a Windows OS so you can just + select the file ``GRMSDKX_EN_DVD.iso`` (the other two ISOs are for 32 bit x86 and for IA). + Mount the ISO (for instance by means of `Virtual Clone Drive`_) and install just + the compiler and the redistributables. + +#. If you have installed Visual C++ **2008** and your Python is a 64 bit application, perform the following steps:: + + > cd "C:\Program Files\Microsoft SDKs\Windows\v7.0" + > cmd /V:ON /K Bin\SetEnv.Cmd /x64 /release > set DISTUTILS_USE_SDK=1 -Again, replace *9.0* with *10.0* depending on the version of Visual Studio. + For other combinations, the steps need to be slightly adjusted: -At the end of all of this, you should be able to install PyCryptodome in your -(virtual) environment with:: + * If you have installed Visual C++ **2010** you must replace ``v7.0`` with ``v7.1``. + * If your Python is a 32 bit application you must replace ``/x64`` with ``/x32``. - > pip install pycryptodome +#. Create a virtual environment for your project:: + > virtualenv MyProject + > cd MyProject + > Scripts\activate + +#. Congratulations. You should be able to install PyCryptodome with:: + + > pip install pycryptodome +.. _get-pip.py: https://bootstrap.pypa.io/get-pip.py +.. _MS Windows SDK for Windows 7 and .NET Framework 3.5 SP1: http://www.microsoft.com/en-us/download/details.aspx?id=18950 +.. _MS Windows SDK for Windows 7 and .NET Framework 4: https://www.microsoft.com/en-us/download/details.aspx?id=8442 +.. _Virtual Clone Drive: http://www.slysoft.com/it/virtual-clonedrive.html