diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/bindings/index.rst | 7 | ||||
| -rw-r--r-- | docs/bindings/openssl.rst | 30 | ||||
| -rw-r--r-- | docs/community.rst | 4 | ||||
| -rw-r--r-- | docs/contributing.rst | 75 | ||||
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/primitives/symmetric-encryption.rst | 52 |
6 files changed, 166 insertions, 3 deletions
diff --git a/docs/bindings/index.rst b/docs/bindings/index.rst new file mode 100644 index 00000000..80f53594 --- /dev/null +++ b/docs/bindings/index.rst @@ -0,0 +1,7 @@ +Bindings +======== + +.. toctree:: + :maxdepth: 1 + + openssl diff --git a/docs/bindings/openssl.rst b/docs/bindings/openssl.rst new file mode 100644 index 00000000..241cc4d6 --- /dev/null +++ b/docs/bindings/openssl.rst @@ -0,0 +1,30 @@ +OpenSSL +======= + +.. warning:: + + The OpenSSL API is not easy to use, small mistakes can lead to significant + security vulnerabilities. We strongly recommend not using this directly, + and instead using one of the higher level APIs exposed by ``cryptography``. + + +These are `CFFI`_ bindings to the `OpenSSL`_ C library. + +.. data:: cryptography.bindings.openssl.api + + This is the exposed API for the OpenSSL bindings. It has two public + attributes: + + .. attribute:: ffi + + This is a :class:`cffi.FFI` instance. It can be used to allocate and + otherwise manipulate OpenSSL structures. + + .. attribute:: lib + + This is a ``cffi`` library. It can be used to call OpenSSL functions, + and access constants. + + +.. _`CFFI`: http://cffi.readthedocs.org/ +.. _`OpenSSL`: https://www.openssl.org/ 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/index.rst b/docs/index.rst index c8f63883..5cc455f6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -32,5 +32,6 @@ Contents architecture primitives/index + bindings/index contributing community diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index ce3b13e8..77d97911 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. + Insecure Ciphers ---------------- @@ -86,3 +95,46 @@ Modes ``block_size`` of the cipher. Do not reuse an ``initialization_vector`` with a given ``key``. + +.. class:: cryptography.primitives.block.modes.OFB(initialization_vector) + + OFB (Output Feedback) is a mode of operation for block ciphers. It + transforms a block cipher into a stream cipher. + + :param bytes initialization_vector: Must be random bytes. They do not need + to be kept secret (they can be included + in a transmitted message). Must be the + same number of bytes as the + ``block_size`` of the cipher. Do not + reuse an ``initialization_vector`` with + a given ``key``. + +.. class:: cryptography.primitives.block.modes.CFB(initialization_vector) + + CFB (Cipher Feedback) is a mode of operation for block ciphers. It + transforms a block cipher into a stream cipher. + + :param bytes initialization_vector: Must be random bytes. They do not need + to be kept secret (they can be included + in a transmitted message). Must be the + same number of bytes as the + ``block_size`` of the cipher. Do not + reuse an ``initialization_vector`` with + a given ``key``. + + +Insecure Modes +-------------- + +.. warning:: + + These modes are insecure. New applications should never make use of them, + and existing applications should strongly consider migrating away. + + +.. class:: cryptography.primitives.block.modes.ECB() + + ECB (Electronic Code Book) is the simplest mode of operation for block + ciphers. Each block of data is encrypted in the same way. This means + identical plaintext blocks will always result in identical ciphertext + blocks, and thus result in information leakage |