From 13f108f926a84eec9c0598164f25cedaece567e3 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 9 Sep 2013 21:41:03 -0500 Subject: Add ECB class + docs + tests * Slightly refactors test_nist to allow fetching of data that has no IV * Does not modify create_block_cipher_context (next commit) --- docs/primitives/symmetric-encryption.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs') diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index 1b8d1d73..8a9bbbdf 100644 --- a/docs/primitives/symmetric-encryption.rst +++ b/docs/primitives/symmetric-encryption.rst @@ -67,3 +67,15 @@ Modes ``block_size`` of the cipher. Do not reuse an ``initialization_vector`` with a given ``key``. + + +Insecure Modes +-------------- + +.. class:: cryptography.primitives.block.modes.ECB() + + ECB (Electronic Code Book) is the simplest mode of operation for block + ciphers. The data is separated into blocks and each block is encrypted + separately. This means identical plaintext blocks will always result in + identical encrypted blocks. Due to this property it is not recommended + for use. Really, don't use it. Just. Don't. -- cgit v1.2.3 From 09980a55fe5a3e4f586425a11b20ba89e84d0452 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 10 Sep 2013 08:24:30 -0500 Subject: remove unneeded init in ECB class, add warning to docs for ECB mode --- docs/primitives/symmetric-encryption.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index 8a9bbbdf..d0429d4b 100644 --- a/docs/primitives/symmetric-encryption.rst +++ b/docs/primitives/symmetric-encryption.rst @@ -72,6 +72,7 @@ Modes Insecure Modes -------------- +.. warning:: Do not use. This is an insecure mode. .. class:: cryptography.primitives.block.modes.ECB() ECB (Electronic Code Book) is the simplest mode of operation for block -- cgit v1.2.3 From cd413a36d3716bf56df7b6e071e57071730d1386 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 10 Sep 2013 18:59:43 -0700 Subject: Cleaned up the docs for ECB --- docs/primitives/symmetric-encryption.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index d0429d4b..f028c755 100644 --- a/docs/primitives/symmetric-encryption.rst +++ b/docs/primitives/symmetric-encryption.rst @@ -72,11 +72,15 @@ Modes Insecure Modes -------------- -.. warning:: Do not use. This is an insecure mode. +.. 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. The data is separated into blocks and each block is encrypted - separately. This means identical plaintext blocks will always result in - identical encrypted blocks. Due to this property it is not recommended - for use. Really, don't use it. Just. Don't. + 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 -- cgit v1.2.3 From 6f412a0fc35386ad980c5b3fa2bdb3c90436f3b6 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 10 Sep 2013 21:30:50 -0500 Subject: add output feedback mode support + test vectors (aes) --- docs/primitives/symmetric-encryption.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'docs') diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index d0429d4b..7ec42a30 100644 --- a/docs/primitives/symmetric-encryption.rst +++ b/docs/primitives/symmetric-encryption.rst @@ -68,6 +68,19 @@ Modes 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``. + Insecure Modes -------------- -- cgit v1.2.3 From c507412ec09e6fa502fbd8587824901e1cf9a935 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 10 Sep 2013 22:15:00 -0500 Subject: change OFB iv to nonce to reflect dstufft nomenclature pitch * Namely, we should try to call things IV if reuse leaks a small amount of data and nonce if reuse can result in a complete break. This can be somewhat ambiguous, but we'll track in #58 --- docs/primitives/symmetric-encryption.rst | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index 7ec42a30..587c94b4 100644 --- a/docs/primitives/symmetric-encryption.rst +++ b/docs/primitives/symmetric-encryption.rst @@ -68,18 +68,16 @@ Modes reuse an ``initialization_vector`` with a given ``key``. -.. class:: cryptography.primitives.block.modes.OFB(initialization_vector) +.. class:: cryptography.primitives.block.modes.OFB(nonce) 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``. + :param bytes nonce: 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. Reuse of a ``nonce`` with a given + ``key`` can allow recovery of the original plaintext. Insecure Modes -- cgit v1.2.3 From 4223df72cf3d3566ae8ccbce7d31dbae7ee25cdd Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 11 Sep 2013 09:48:04 -0500 Subject: add CFB to documentation --- docs/primitives/symmetric-encryption.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'docs') diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index c4f78a79..be86229b 100644 --- a/docs/primitives/symmetric-encryption.rst +++ b/docs/primitives/symmetric-encryption.rst @@ -79,6 +79,19 @@ Modes of the cipher. Reuse of a ``nonce`` with a given ``key`` can allow recovery of the original plaintext. +.. 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 -------------- -- cgit v1.2.3 From f1a39bd77ff8ea5fda5a24616c3fc9a9199be633 Mon Sep 17 00:00:00 2001 From: David Reid Date: Wed, 11 Sep 2013 16:28:42 -0700 Subject: OFB uses an initialization vector instead a nonce. --- docs/primitives/symmetric-encryption.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index be86229b..46d7c07c 100644 --- a/docs/primitives/symmetric-encryption.rst +++ b/docs/primitives/symmetric-encryption.rst @@ -68,16 +68,18 @@ Modes reuse an ``initialization_vector`` with a given ``key``. -.. class:: cryptography.primitives.block.modes.OFB(nonce) +.. 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 nonce: 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. Reuse of a ``nonce`` with a given - ``key`` can allow recovery of the original plaintext. + :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) -- cgit v1.2.3 From 6d02e2ddfd87f0fd06a70d56ad1a2167ceec5232 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 30 Sep 2013 10:37:22 -0700 Subject: Make the lib and ffi public for the OpenSSL binding and document them --- docs/bindings/index.rst | 7 +++++++ docs/bindings/openssl.rst | 23 +++++++++++++++++++++++ docs/index.rst | 1 + 3 files changed, 31 insertions(+) create mode 100644 docs/bindings/index.rst create mode 100644 docs/bindings/openssl.rst (limited to 'docs') 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..144ed9b3 --- /dev/null +++ b/docs/bindings/openssl.rst @@ -0,0 +1,23 @@ +OpenSSL +======= + +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/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 -- cgit v1.2.3 From 0f7f7813ebf7b1fb52f0bab1c6c26321bf9cd5d9 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 30 Sep 2013 10:52:36 -0700 Subject: Put a warning --- docs/bindings/openssl.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs') diff --git a/docs/bindings/openssl.rst b/docs/bindings/openssl.rst index 144ed9b3..79468cb4 100644 --- a/docs/bindings/openssl.rst +++ b/docs/bindings/openssl.rst @@ -1,6 +1,13 @@ 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, + 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 -- cgit v1.2.3 From 0d9bb14f40c7903aac5be58ff40aa1f813876ead Mon Sep 17 00:00:00 2001 From: Richard Wall Date: Tue, 1 Oct 2013 16:17:24 +0100 Subject: some narrative documentation explaining how to set up a development environment --- docs/contributing.rst | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index b4c72ba4..4f089fed 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -73,8 +73,89 @@ So, specifically: - No blank line at the end. - Use Sphinx parameter/attribute documentation `syntax`_. +Development +----------- + +Working on ``cryptography`` requires the installation of a small number of +development dependencies. +The list of development dependencies can be found in ``requirements-dev.txt``. +We recommend that you install these using ``virtualenv`` and ``pip``. +The following example shows how to create a ``cryptography`` development +environment on Linux: + +.. code-block:: sh + + cd ~/projects + git clone git@github.com:/cryptography.git + cd cryptography + mkdir -p ~/.virtualenvs/cryptography + virtualenv --no-site-packages ~/.virtualenvs/cryptography + source ~/.virtualenvs/cryptography/bin/activate + pip install -r requirements-dev.txt + pip install -e . + +You are now ready to run the tests and build the documentation. +Those steps are described in the next sections. + +Testing +------- + +``cryptography`` unit tests are found in the ``tests`` directory. +They are designed to be run using `pytest`_ as follows + +.. code-block:: sh + + py.test tests + ... + 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. +Here is an example: + +.. code-block:: sh + + tox -l + ... + py33 + + tox -e py33 + ... + py33: commands succeeded + congratulations :) + +``tox`` can also be used to build the ``cryptography`` documentation. +That is described in the next section. + +Building Documentation +---------------------- + +``cryptography`` documentation is stored in the ``docs`` directory. +It is written in ``ReST`` and built using ``sphinx``. + +The simplest way to build the documentation is to use ``tox``. +The following example shows how to build the documentation using ``tox``: + +.. code-block:: sh + + tox -e doc + ... + py33: commands succeeded + congratulations :) + +The HTML documentation can now be found in the ``docs/_build/html`` +sub-directory. + +.. code-block:: sh + + firefox docs/_build/html/index.html + .. _`GitHub`: https://github.com/alex/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`: http://pytest.org -- cgit v1.2.3 From c3d1eb5eda5bb18109c7a401b062730489be2367 Mon Sep 17 00:00:00 2001 From: Richard Wall Date: Tue, 1 Oct 2013 16:29:07 +0100 Subject: add some more links --- docs/contributing.rst | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 4f089fed..a77ed849 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -79,7 +79,7 @@ Development Working on ``cryptography`` requires the installation of a small number of development dependencies. The list of development dependencies can be found in ``requirements-dev.txt``. -We recommend that you install these using ``virtualenv`` and ``pip``. +We recommend that you install these using `virtualenv`_ and `pip`_. The following example shows how to create a ``cryptography`` development environment on Linux: @@ -112,7 +112,7 @@ They are designed to be run using `pytest`_ as follows 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 +For this we use `tox`_, which will automatically create a `virtualenv`_ for each supported Python version and run the tests. Here is an example: @@ -127,23 +127,23 @@ Here is an example: py33: commands succeeded congratulations :) -``tox`` can also be used to build the ``cryptography`` documentation. +`tox`_ can also be used to build the ``cryptography`` documentation. That is described in the next section. Building Documentation ---------------------- ``cryptography`` documentation is stored in the ``docs`` directory. -It is written in ``ReST`` and built using ``sphinx``. +It is written in `ReST`_ and built using `sphinx`_. -The simplest way to build the documentation is to use ``tox``. -The following example shows how to build the documentation using ``tox``: +The simplest way to build the documentation is to use `tox`_. +The following example demonstrates how: .. code-block:: sh tox -e doc ... - py33: commands succeeded + docs: commands succeeded congratulations :) The HTML documentation can now be found in the ``docs/_build/html`` @@ -158,4 +158,9 @@ sub-directory. .. _`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`: http://pytest.org +.. _`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 +.. _`ReST`: http://docutils.sourceforge.net/rst.html -- cgit v1.2.3 From 40cde82b2e3e4f791f9d7d931b8c926da1eaca07 Mon Sep 17 00:00:00 2001 From: Richard Wall Date: Tue, 1 Oct 2013 20:20:15 +0100 Subject: Address review comments. Better headings. More documentation build options --- docs/contributing.rst | 97 +++++++++++++++++++++++++++++++-------------------- 1 file changed, 60 insertions(+), 37 deletions(-) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index a77ed849..0f5cdfac 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -73,39 +73,34 @@ So, specifically: - No blank line at the end. - Use Sphinx parameter/attribute documentation `syntax`_. -Development ------------ +Development Environment +----------------------- Working on ``cryptography`` requires the installation of a small number of development dependencies. -The list of development dependencies can be found in ``requirements-dev.txt``. -We recommend that you install these using `virtualenv`_ and `pip`_. -The following example shows how to create a ``cryptography`` development -environment on Linux: +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:: sh - cd ~/projects - git clone git@github.com:/cryptography.git - cd cryptography - mkdir -p ~/.virtualenvs/cryptography - virtualenv --no-site-packages ~/.virtualenvs/cryptography - source ~/.virtualenvs/cryptography/bin/activate - pip install -r requirements-dev.txt - pip install -e . + # 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. -Those steps are described in the next sections. -Testing -------- +Running Tests +------------- -``cryptography`` unit tests are found in the ``tests`` directory. -They are designed to be run using `pytest`_ as follows +``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:: sh - py.test tests + py.test ... 4294 passed in 15.24 seconds @@ -113,31 +108,30 @@ 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. -Here is an example: +each supported Python version and run the tests. For example: .. code-block:: sh - tox -l + tox ... - py33 - - tox -e py33 - ... - py33: commands succeeded - congratulations :) + 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 -`tox`_ can also be used to build the ``cryptography`` documentation. -That is described in the next section. +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 `ReST`_ and built using `sphinx`_. +``cryptography`` documentation is stored in the ``docs/`` directory. +It is written in `Restructured Text`_ and rendered using `sphinx`_. -The simplest way to build the documentation is to use `tox`_. -The following example demonstrates how: +The simplest way to build the documentation is to use `tox`_. For example: .. code-block:: sh @@ -146,13 +140,42 @@ The following example demonstrates how: docs: commands succeeded congratulations :) -The HTML documentation can now be found in the ``docs/_build/html`` +The HTML documentation can now be found in the ``docs/_build/html/`` sub-directory. .. code-block:: sh firefox docs/_build/html/index.html +You can also build non-HTML documentation and run various documentation tests +by running ``make`` in the ``docs/`` directory. +Just type ``make`` to see the available options: + +.. code-block:: sh + + make + ... + Please use `make ' where is one of + html to make standalone HTML files + dirhtml to make HTML files named index.html in directories + singlehtml to make a single large HTML file + pickle to make pickle files + json to make JSON files + htmlhelp to make HTML files and a HTML help project + qthelp to make HTML files and a qthelp project + devhelp to make HTML files and a Devhelp project + epub to make an epub + latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + latexpdf to make LaTeX files and run them through pdflatex + text to make text files + man to make manual pages + texinfo to make Texinfo files + info to make Texinfo files and run them through makeinfo + gettext to make PO message catalogs + changes to make an overview of all changed/added/deprecated items + linkcheck to check all external links for integrity + doctest to run all doctests embedded in the documentation (if enabled) + .. _`GitHub`: https://github.com/alex/cryptography .. _`our mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev @@ -163,4 +186,4 @@ sub-directory. .. _`virtualenv`: https://pypi.python.org/pypi/virtualenv .. _`pip`: https://pypi.python.org/pypi/pip .. _`sphinx`: https://pypi.python.org/pypi/sphinx -.. _`ReST`: http://docutils.sourceforge.net/rst.html +.. _`Restructured Text`: http://docutils.sourceforge.net/rst.html -- cgit v1.2.3 From 7d4ca1efc4a353023613aa20a2ddfd657939f31b Mon Sep 17 00:00:00 2001 From: Richard Wall Date: Tue, 1 Oct 2013 21:10:45 +0100 Subject: address dreids review comments --- docs/contributing.rst | 48 +++++++----------------------------------------- 1 file changed, 7 insertions(+), 41 deletions(-) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 0f5cdfac..8007e6b6 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -86,8 +86,8 @@ install ``cryptography`` in ``editable`` mode. For example: .. code-block:: sh # Create a virtualenv and activate it - pip install --requirement dev-requirements.txt - pip install --editable . + $ pip install --requirement dev-requirements.txt + $ pip install --editable . You are now ready to run the tests and build the documentation. @@ -100,7 +100,7 @@ and are designed to be run using `pytest`_. .. code-block:: sh - py.test + $ py.test ... 4294 passed in 15.24 seconds @@ -112,7 +112,7 @@ each supported Python version and run the tests. For example: .. code-block:: sh - tox + $ tox ... ERROR: py26: InterpreterNotFound: python2.6 py27: commands succeeded @@ -131,50 +131,16 @@ Building Documentation ``cryptography`` documentation is stored in the ``docs/`` directory. It is written in `Restructured Text`_ and rendered using `sphinx`_. -The simplest way to build the documentation is to use `tox`_. For example: +Use `tox`_ to build the documentation. For example: .. code-block:: sh - tox -e doc + $ tox -e docs ... docs: commands succeeded congratulations :) -The HTML documentation can now be found in the ``docs/_build/html/`` -sub-directory. - -.. code-block:: sh - - firefox docs/_build/html/index.html - -You can also build non-HTML documentation and run various documentation tests -by running ``make`` in the ``docs/`` directory. -Just type ``make`` to see the available options: - -.. code-block:: sh - - make - ... - Please use `make ' where is one of - html to make standalone HTML files - dirhtml to make HTML files named index.html in directories - singlehtml to make a single large HTML file - pickle to make pickle files - json to make JSON files - htmlhelp to make HTML files and a HTML help project - qthelp to make HTML files and a qthelp project - devhelp to make HTML files and a Devhelp project - epub to make an epub - latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - latexpdf to make LaTeX files and run them through pdflatex - text to make text files - man to make manual pages - texinfo to make Texinfo files - info to make Texinfo files and run them through makeinfo - gettext to make PO message catalogs - changes to make an overview of all changed/added/deprecated items - linkcheck to check all external links for integrity - doctest to run all doctests embedded in the documentation (if enabled) +The HTML documentation index can now be found at ``docs/_build/html/index.html`` .. _`GitHub`: https://github.com/alex/cryptography -- cgit v1.2.3 From 166cbd3947cd4416fe7b48f1525853563cd1125f Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 1 Oct 2013 13:30:29 -0700 Subject: Reflow some paragraphs in the contributing docs --- docs/contributing.rst | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 8007e6b6..9dd14c23 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -77,11 +77,9 @@ Development Environment ----------------------- 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: +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:: sh @@ -94,9 +92,9 @@ 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: +``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:: sh @@ -122,14 +120,14 @@ each supported Python version and run the tests. For example: 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. +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`_. +``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: @@ -152,4 +150,4 @@ The HTML documentation index can now be found at ``docs/_build/html/index.html`` .. _`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 +.. _`reStructured Text`: http://docutils.sourceforge.net/rst.html -- cgit v1.2.3 From 5cb03b2c442e6b2f9af95867058f8a48325874d8 Mon Sep 17 00:00:00 2001 From: Hynek Schlawack Date: Thu, 3 Oct 2013 13:13:55 +0200 Subject: Fix typo in OpenSSL bindings docs --- docs/bindings/openssl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') 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``. -- cgit v1.2.3 From 85707941515cdf4dcc3d85da499f836ae23cc20b Mon Sep 17 00:00:00 2001 From: Donald Stufft Date: Fri, 4 Oct 2013 23:55:27 -0400 Subject: Switch all repositories over to the new location --- docs/community.rst | 4 ++-- docs/contributing.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') 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 9dd14c23..8f6a178e 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -141,7 +141,7 @@ Use `tox`_ to build the documentation. For example: The HTML documentation index can now be found at ``docs/_build/html/index.html`` -.. _`GitHub`: https://github.com/alex/cryptography +.. _`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 -- cgit v1.2.3 From ae5c907769365d1e7f89b1b7db99eb861d149b25 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sun, 6 Oct 2013 11:04:08 -0700 Subject: Use the right lexer for these examples --- docs/contributing.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 8f6a178e..1f4c1ca9 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -81,7 +81,7 @@ 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:: sh +.. code-block:: console # Create a virtualenv and activate it $ pip install --requirement dev-requirements.txt @@ -96,7 +96,7 @@ Running Tests designed to be run using `pytest`_. `pytest`_ will discover the tests automatically, so all you have to do is: -.. code-block:: sh +.. code-block:: console $ py.test ... @@ -108,7 +108,7 @@ 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:: sh +.. code-block:: console $ tox ... @@ -131,7 +131,7 @@ written in `reStructured Text`_ and rendered using `Sphinx`_. Use `tox`_ to build the documentation. For example: -.. code-block:: sh +.. code-block:: console $ tox -e docs ... -- cgit v1.2.3 From 7587ded5cfcb5c66bce412a3c3696e96a016d7d0 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sun, 6 Oct 2013 12:14:05 -0700 Subject: This is a comment, not a command run in a root shell --- docs/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 1f4c1ca9..2d8fceeb 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -83,7 +83,7 @@ dependencies, install ``cryptography`` in ``editable`` mode. For example: .. code-block:: console - # Create a virtualenv and activate it + $ # Create a virtualenv and activate it $ pip install --requirement dev-requirements.txt $ pip install --editable . -- cgit v1.2.3 From dff22d4707a50b8164c5c6acd5521bcd91160cd1 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Fri, 27 Sep 2013 13:43:06 -0500 Subject: Camellia block cipher support * Tests for CBC, OFB, CFB, and ECB * Tests will be automatically skipped if camellia support is not present in your OpenSSL library (e.g. OS X 10.8 with default OpenSSL) * Test for unsupported cipher in create_block_cipher_context * Docs for the cipher --- docs/primitives/symmetric-encryption.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs') diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index 46d7c07c..c4bbf0a5 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 ~~~~~ -- cgit v1.2.3