diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/changelog.rst | 1 | ||||
| -rw-r--r-- | docs/contributing.rst | 3 | ||||
| -rw-r--r-- | docs/hazmat/backends/interfaces.rst | 21 | ||||
| -rw-r--r-- | docs/hazmat/backends/openssl.rst | 50 | ||||
| -rw-r--r-- | docs/hazmat/primitives/index.rst | 1 | ||||
| -rw-r--r-- | docs/hazmat/primitives/padding.rst | 10 | ||||
| -rw-r--r-- | docs/hazmat/primitives/rsa.rst | 58 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 24 | ||||
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/random-numbers.rst | 20 |
10 files changed, 171 insertions, 18 deletions
diff --git a/docs/changelog.rst b/docs/changelog.rst index e322b145..4d459bd9 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -17,6 +17,7 @@ Changelog * Added :class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC`. * Added :class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF`. * Added :doc:`/hazmat/backends/multibackend`. +* Set default random for the :doc:`/hazmat/backends/openssl` to the OS random engine. 0.1 - 2014-01-08 ~~~~~~~~~~~~~~~~ diff --git a/docs/contributing.rst b/docs/contributing.rst index 86708836..87075638 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -43,6 +43,8 @@ Code When in doubt, refer to :pep:`8` for Python code. +`Write comments as complete sentences.`_ + Every code file must start with the boilerplate notice of the Apache License. Additionally, every Python code file must contain @@ -287,6 +289,7 @@ The HTML documentation index can now be found at .. _`GitHub`: https://github.com/pyca/cryptography .. _`our mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev +.. _`Write comments as complete sentences.`: http://nedbatchelder.com/blog/201401/comments_should_be_sentences.html .. _`syntax`: http://sphinx-doc.org/domains.html#info-field-lists .. _`pytest`: https://pypi.python.org/pypi/pytest .. _`tox`: https://pypi.python.org/pypi/tox diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index cd64050c..e6bf8f69 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -191,3 +191,24 @@ A specific ``backend`` may provide one or more of these interfaces. the derived key. This is typically a password. :return bytes: Derived key. + + +.. class:: RSABackend + + .. versionadded:: 0.2 + + A backend with methods for using RSA. + + .. method:: generate_rsa_private_key(public_exponent, key_size) + + :param int public_exponent: The public exponent of the new key. + Often one of the small Fermat primes 3, 5, 17, 257 or 65537. + + :param int key_size: The length in bits of the modulus. Should be + at least 2048. + + :return: A new instance of a + :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey` + provider. + + :raises ValueError: If the public_exponent is not valid. diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index 4db3972d..ea72af96 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -16,10 +16,58 @@ The `OpenSSL`_ C library. * :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` * :class:`~cryptography.hazmat.backends.interfaces.PBKDF2HMACBackend` - It has one additional public attribute. + It also exposes the following: .. attribute:: name The string name of this backend: ``"openssl"`` + .. method:: activate_osrandom_engine() + + Activates the OS random engine. This will effectively disable OpenSSL's + default CSPRNG. + + .. method:: activate_builtin_random() + + This will activate the default OpenSSL CSPRNG. + +OS Random Engine +---------------- + +OpenSSL uses a user-space CSPRNG that is seeded from system random ( +``/dev/urandom`` or ``CryptGenRandom``). This CSPRNG is not reseeded +automatically when a process calls ``fork()``. This can result in situations +where two different processes can return similar or identical keys and +compromise the security of the system. + +The approach this project has chosen to mitigate this vulnerability is to +include an engine that replaces the OpenSSL default CSPRNG with one that sources +its entropy from ``/dev/urandom`` on UNIX-like operating systems and uses +``CryptGenRandom`` on Windows. This method of pulling from the system pool +allows us to avoid potential issues with `initializing the RNG`_ as well as +protecting us from the ``fork()`` weakness. + +This engine is **active** by default when importing the OpenSSL backend. When +active this engine will be used to generate all the random data OpenSSL +requests. + +When importing only the binding it is added to the engine list but +**not activated**. + + +OS Random Sources +----------------- + +On OS X and FreeBSD ``/dev/urandom`` is an alias for ``/dev/random`` and +utilizes the `Yarrow`_ algorithm. + +On Windows ``CryptGenRandom`` is backed by `Fortuna`_. + +Linux uses its own PRNG design. ``/dev/urandom`` is a non-blocking source seeded +from the same pool as ``/dev/random``. + + .. _`OpenSSL`: https://www.openssl.org/ +.. _`initializing the RNG`: http://en.wikipedia.org/wiki/OpenSSL#Vulnerability_in_the_Debian_implementation +.. _`Yarrow`: http://en.wikipedia.org/wiki/Yarrow_algorithm +.. _`Fortuna`: http://en.wikipedia.org/wiki/Fortuna_(PRNG) diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index bde07392..38ed24c9 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -11,5 +11,6 @@ Primitives symmetric-encryption padding key-derivation-functions + rsa constant-time interfaces diff --git a/docs/hazmat/primitives/padding.rst b/docs/hazmat/primitives/padding.rst index 4d79ac8f..da5a95dd 100644 --- a/docs/hazmat/primitives/padding.rst +++ b/docs/hazmat/primitives/padding.rst @@ -54,11 +54,11 @@ multiple of the block size. .. class:: PaddingContext - When calling ``padder()`` or ``unpadder()`` you will receive an a return - object conforming to the ``PaddingContext`` interface. You can then call - ``update(data)`` with data until you have fed everything into the context. - Once that is done call ``finalize()`` to finish the operation and obtain - the remainder of the data. + When calling ``padder()`` or ``unpadder()`` the result will conform to the + ``PaddingContext`` interface. You can then call ``update(data)`` with data + until you have fed everything into the context. Once that is done call + ``finalize()`` to finish the operation and obtain the remainder of the + data. .. method:: update(data) diff --git a/docs/hazmat/primitives/rsa.rst b/docs/hazmat/primitives/rsa.rst new file mode 100644 index 00000000..7c6356c1 --- /dev/null +++ b/docs/hazmat/primitives/rsa.rst @@ -0,0 +1,58 @@ +.. hazmat:: + +RSA +=== + +.. currentmodule:: cryptography.hazmat.primitives.asymmetric.rsa + +`RSA`_ is a `public-key`_ algorithm for encrypting and signing messages. + +.. class:: RSAPrivateKey(p, q, private_exponent, public_exponent, modulus) + + .. versionadded:: 0.2 + + An RSA private key is required for decryption and signing of messages. + + Normally you do not need to directly construct private keys because you'll + be loading them from a file or generating them automatically. + + .. warning:: + This method only checks a limited set of properties of its arguments. + Using an RSA that you do not trust or with incorrect parameters may + lead to insecure operation, crashes, and other undefined behavior. We + recommend that you only ever load private keys that were generated with + software you trust. + + This class conforms to the + :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey` + interface. + + :raises TypeError: This is raised when the arguments are not all integers. + + :raises ValueError: This is raised when the values of `p`, `q`, + `private_exponent`, `public_exponent` or `modulus` do + not match the bounds specified in `RFC 3447`_. + +.. class:: RSAPublicKey(public_exponent, modulus) + + .. versionadded:: 0.2 + + An RSA public key is required for encryption and verification of messages. + + Normally you do not need to directly construct public keys because you'll + be loading them from a file, generating them automatically or receiving + them from a 3rd party. + + This class conforms to the + :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` + interface. + + :raises TypeError: This is raised when the arguments are not all integers. + + :raises ValueError: This is raised when the values of `public_exponent` or + `modulus` do not match the bounds specified in + `RFC 3447`_. + +.. _`RSA`: https://en.wikipedia.org/wiki/RSA_(cryptosystem) +.. _`public-key`: https://en.wikipedia.org/wiki/Public-key_cryptography +.. _`RFC 3447`: https://tools.ietf.org/html/rfc3447 diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 7d954046..85d8e8e3 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -388,10 +388,10 @@ Interfaces .. class:: CipherContext When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object - you will receive a return object conforming to the ``CipherContext`` - interface. You can then call ``update(data)`` with data until you have fed - everything into the context. Once that is done call ``finalize()`` to - finish the operation and obtain the remainder of the data. + the result will conform to the ``CipherContext`` interface. You can then + call ``update(data)`` with data until you have fed everything into the + context. Once that is done call ``finalize()`` to finish the operation and + obtain the remainder of the data. Block ciphers require that plaintext or ciphertext always be a multiple of their block size, because of that **padding** is sometimes required to make @@ -429,14 +429,14 @@ Interfaces When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object with an AEAD mode (e.g. - :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM`) you will receive - a return object conforming to the ``AEADCipherContext`` and - ``CipherContext`` interfaces. If it is an encryption context it will - additionally be an ``AEADEncryptionContext`` interface. - ``AEADCipherContext`` contains an additional method - ``authenticate_additional_data`` for adding additional authenticated but - unencrypted data (see note below). You should call this before calls to - ``update``. When you are done call ``finalize()`` to finish the operation. + :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM`) the result will + conform to the ``AEADCipherContext`` and ``CipherContext`` interfaces. If + it is an encryption context it will additionally be an + ``AEADEncryptionContext`` interface. ``AEADCipherContext`` contains an + additional method ``authenticate_additional_data`` for adding additional + authenticated but unencrypted data (see note below). You should call this + before calls to ``update``. When you are done call ``finalize()`` to finish + the operation. .. note:: diff --git a/docs/index.rst b/docs/index.rst index 49e99be4..9114b895 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -59,6 +59,7 @@ The recipes layer :maxdepth: 2 fernet + random-numbers exceptions glossary diff --git a/docs/random-numbers.rst b/docs/random-numbers.rst new file mode 100644 index 00000000..cd73a7b7 --- /dev/null +++ b/docs/random-numbers.rst @@ -0,0 +1,20 @@ +Random number generation +======================== + +When generating random data for use in cryptographic operations, such as an +initialization vector for encryption in +:class:`~cryptography.hazmat.primitives.ciphers.modes.CBC` mode, you do not +want to use the standard :mod:`random` module APIs. This is because they do not +provide a cryptographically secure random number generator, which can result in +major security issues depending on the algorithms in use. + +Therefore, it is our recommendation to always use your operating system's +provided random number generator, which is available as ``os.urandom()``. For +example, if you need 16 bytes of random data for an initialization vector, you +can obtain them with: + +.. code-block:: pycon + + >>> import os + >>> os.urandom(16) + '...' |