diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/bindings/openssl.rst | 2 | ||||
| -rw-r--r-- | docs/community.rst | 4 | ||||
| -rw-r--r-- | docs/contributing.rst | 75 | ||||
| -rw-r--r-- | docs/primitives/symmetric-encryption.rst | 28 |
4 files changed, 105 insertions, 4 deletions
diff --git a/docs/bindings/openssl.rst b/docs/bindings/openssl.rst index 79468cb4..241cc4d6 100644 --- a/docs/bindings/openssl.rst +++ b/docs/bindings/openssl.rst @@ -4,7 +4,7 @@ OpenSSL .. warning:: The OpenSSL API is not easy to use, small mistakes can lead to significant - security vulnerabilities. We strongly reccomend not using this directly, + security vulnerabilities. We strongly recommend not using this directly, and instead using one of the higher level APIs exposed by ``cryptography``. diff --git a/docs/community.rst b/docs/community.rst index 809ffd12..86ba5055 100644 --- a/docs/community.rst +++ b/docs/community.rst @@ -10,6 +10,6 @@ You can find ``cryptography`` all over the web: * IRC: ``#cryptography-dev`` on ``irc.freenode.net`` .. _`Mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev -.. _`Source code`: https://github.com/alex/cryptography -.. _`Issue tracker`: https://github.com/alex/cryptography/issues +.. _`Source code`: https://github.com/pyca/cryptography +.. _`Issue tracker`: https://github.com/pyca/cryptography/issues .. _`Documentation`: https://cryptography.readthedocs.org/ diff --git a/docs/contributing.rst b/docs/contributing.rst index b4c72ba4..2d8fceeb 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -73,8 +73,81 @@ So, specifically: - No blank line at the end. - Use Sphinx parameter/attribute documentation `syntax`_. +Development Environment +----------------------- -.. _`GitHub`: https://github.com/alex/cryptography +Working on ``cryptography`` requires the installation of a small number of +development dependencies. These are listed in ``dev-requirements.txt`` and they +can be installed in a `virtualenv`_ using `pip`_. Once you've installed the +dependencies, install ``cryptography`` in ``editable`` mode. For example: + +.. code-block:: console + + $ # Create a virtualenv and activate it + $ pip install --requirement dev-requirements.txt + $ pip install --editable . + +You are now ready to run the tests and build the documentation. + +Running Tests +------------- + +``cryptography`` unit tests are found in the ``tests/`` directory and are +designed to be run using `pytest`_. `pytest`_ will discover the tests +automatically, so all you have to do is: + +.. code-block:: console + + $ py.test + ... + 4294 passed in 15.24 seconds + +This runs the tests with the default Python interpreter. + +You can also verify that the tests pass on other supported Python interpreters. +For this we use `tox`_, which will automatically create a `virtualenv`_ for +each supported Python version and run the tests. For example: + +.. code-block:: console + + $ tox + ... + ERROR: py26: InterpreterNotFound: python2.6 + py27: commands succeeded + ERROR: pypy: InterpreterNotFound: pypy + ERROR: py32: InterpreterNotFound: python3.2 + py33: commands succeeded + docs: commands succeeded + pep8: commands succeeded + +You may not have all the required Python versions installed, in which case you +will see one or more ``InterpreterNotFound`` errors. + +Building Documentation +---------------------- + +``cryptography`` documentation is stored in the ``docs/`` directory. It is +written in `reStructured Text`_ and rendered using `Sphinx`_. + +Use `tox`_ to build the documentation. For example: + +.. code-block:: console + + $ tox -e docs + ... + docs: commands succeeded + congratulations :) + +The HTML documentation index can now be found at ``docs/_build/html/index.html`` + + +.. _`GitHub`: https://github.com/pyca/cryptography .. _`our mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev .. _`PEP 8`: http://www.peps.io/8/ .. _`syntax`: http://sphinx-doc.org/domains.html#info-field-lists +.. _`pytest`: https://pypi.python.org/pypi/pytest +.. _`tox`: https://pypi.python.org/pypi/tox +.. _`virtualenv`: https://pypi.python.org/pypi/virtualenv +.. _`pip`: https://pypi.python.org/pypi/pip +.. _`sphinx`: https://pypi.python.org/pypi/sphinx +.. _`reStructured Text`: http://docutils.sourceforge.net/rst.html diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index 46d7c07c..7899e67d 100644 --- a/docs/primitives/symmetric-encryption.rst +++ b/docs/primitives/symmetric-encryption.rst @@ -51,6 +51,15 @@ Ciphers :param bytes key: The secret key, either ``128``, ``192``, or ``256`` bits. This must be kept secret. +.. class:: cryptography.primitives.block.ciphers.Camellia(key) + + Camellia is a block cipher approved for use by CRYPTREC and ISO/IEC. + It is considered to have comparable security and performance to AES, but + is not as widely studied or deployed. + + :param bytes key: The secret key, either ``128``, ``192``, or ``256`` bits. + This must be kept secret. + Modes ~~~~~ @@ -68,6 +77,25 @@ Modes reuse an ``initialization_vector`` with a given ``key``. + +.. class:: cryptography.primitives.block.modes.CTR(nonce) + + .. warning:: + + Counter mode is not recommended for use with block ciphers that have a + block size of less than 128-bits. + + CTR (Counter) is a mode of operation for block ciphers. It is considered + cryptographically strong. + + :param bytes nonce: Should be random bytes. It is critical to never reuse a + ``nonce`` with a given key. Any reuse of a nonce + with the same key compromises the security of every + message encrypted with that key. Must be the same + number of bytes as the ``block_size`` of the cipher + with a given key. The nonce does not need to be kept + secret and may be included alongside the ciphertext. + .. class:: cryptography.primitives.block.modes.OFB(initialization_vector) OFB (Output Feedback) is a mode of operation for block ciphers. It |