diff options
Diffstat (limited to 'docs/hazmat')
| -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 |
5 files changed, 125 insertions, 18 deletions
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:: |