Update to documentation

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.

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

Doc/src/contributing.rst → 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 <https://groups.google.com/forum/#!forum/pycryptodome>`_.
+You can mail any comment or question to *[email protected]*.
+
+Bug reports can be filed on the `GitHub tracker <https://github.com/Legrandin/pycryptodome/issues>`_.
+
 .. _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

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,25 +35,25 @@ 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)
   - SHA-3 family (224, 256, 384, 512 - FIPS 202 draft May 2014)
   - 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

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 <https://www.dlitz.net/software/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

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 <https://pip.pypa.io/en/latest/installing.html>`_.
-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 <http://pythonwheels.com/>`_ 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 <http://www.microsoft.com/en-us/download/details.aspx?id=18950>`_.
- * For Python 3.3 or newer, Visual C++ Compiler 2010 from the `MS Windows SDK for Windows 7 and .NET Framework 4 <https://www.microsoft.com/en-us/download/details.aspx?id=8442>`_.
+#. 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