diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/faq.rst | 13 | ||||
-rw-r--r-- | docs/hazmat/backends/interfaces.rst | 14 | ||||
-rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 88 | ||||
-rw-r--r-- | docs/hazmat/primitives/key-derivation-functions.rst | 2 | ||||
-rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 2 | ||||
-rw-r--r-- | docs/installation.rst | 12 |
6 files changed, 93 insertions, 38 deletions
diff --git a/docs/faq.rst b/docs/faq.rst index 0b7bdce4..d06c1d0e 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -14,5 +14,18 @@ to NaCl. If you prefer NaCl's design, we highly recommend `PyNaCl`_. +When I try to use ``cryptography`` on Windows I get a ``cffi.ffiplatform.VerificationError`` +-------------------------------------------------------------------------------------------- + +This error looks something like: + +.. code-block:: console + + cffi.ffiplatform.VerificationError: importing '<some_path>.pyd': DLL load failed: + +It typically occurs on Windows when you have not installed OpenSSL. Download +a `pre-compiled binary`_ to resolve this issue. + .. _`NaCl`: http://nacl.cr.yp.to/ .. _`PyNaCl`: https://pynacl.readthedocs.org +.. _`pre-compiled binary`: https://www.openssl.org/related/binaries.html diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index f363b541..1e1a6b28 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -275,6 +275,14 @@ A specific ``backend`` may provide one or more of these interfaces. :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` provider. + :return bytes: The decrypted data. + + :raises cryptography.exceptions.UnsupportedAlgorithm: If an unsupported + MGF, hash function, or padding is chosen. + + :raises ValueError: When decryption fails or key size does not match + ciphertext length. + .. method:: encrypt_rsa(public_key, plaintext, padding) :param public_key: An instance of an @@ -287,6 +295,12 @@ A specific ``backend`` may provide one or more of these interfaces. :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` provider. + :return bytes: The encrypted data. + + :raises cryptography.exceptions.UnsupportedAlgorithm: If an unsupported + MGF, hash function, or padding is chosen. + + :raises ValueError: When plaintext is too long for the key size. .. class:: TraditionalOpenSSLSerializationBackend diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 2700154c..7bae7142 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -154,21 +154,39 @@ RSA :class:`~cryptography.hazmat.primitives.asymmetric.padding.OAEP` it may also be raised for invalid label values. - .. code-block:: python + .. doctest:: - from cryptography.hazmat.backends import default_backend - from cryptography.hazmat.primitives import hashes - from cryptography.hazmat.primitives.asymmetric import padding + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives import hashes + >>> from cryptography.hazmat.primitives.asymmetric import padding - plaintext = private_key.decrypt( - ciphertext, - padding.OAEP( - mgf=padding.MGF1(algorithm=hashes.SHA1()), - algorithm=hashes.SHA1(), - label=None - ), - default_backend() - ) + >>> # Generate a key + >>> private_key = rsa.RSAPrivateKey.generate( + ... public_exponent=65537, + ... key_size=2048, + ... backend=default_backend() + ... ) + >>> public_key = private_key.public_key() + >>> # encrypt some data + >>> ciphertext = public_key.encrypt( + ... b"encrypted data", + ... padding.OAEP( + ... mgf=padding.MGF1(algorithm=hashes.SHA1()), + ... algorithm=hashes.SHA1(), + ... label=None + ... ), + ... default_backend() + ... ) + >>> # Now do the actual decryption + >>> plaintext = private_key.decrypt( + ... ciphertext, + ... padding.OAEP( + ... mgf=padding.MGF1(algorithm=hashes.SHA1()), + ... algorithm=hashes.SHA1(), + ... label=None + ... ), + ... default_backend() + ... ) .. class:: RSAPublicKey(public_exponent, modulus) @@ -306,27 +324,29 @@ RSA :class:`~cryptography.hazmat.primitives.asymmetric.padding.OAEP` it may also be raised for invalid label values. - .. code-block:: python - - from cryptography.hazmat.backends import default_backend - from cryptography.hazmat.primitives import hashes - from cryptography.hazmat.primitives.asymmetric import padding, rsa - - private_key = rsa.RSAPrivateKey.generate( - public_exponent=65537, - key_size=2048, - backend=default_backend() - ) - public_key = private_key.public_key() - ciphertext = public_key.encrypt( - plaintext, - padding.OAEP( - mgf=padding.MGF1(algorithm=hashes.SHA1()), - algorithm=hashes.SHA1(), - label=None - ), - default_backend() - ) + .. doctest:: + + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives import hashes + >>> from cryptography.hazmat.primitives.asymmetric import padding + + >>> # Generate a key + >>> private_key = rsa.RSAPrivateKey.generate( + ... public_exponent=65537, + ... key_size=2048, + ... backend=default_backend() + ... ) + >>> public_key = private_key.public_key() + >>> # encrypt some data + >>> ciphertext = public_key.encrypt( + ... b"encrypted data", + ... padding.OAEP( + ... mgf=padding.MGF1(algorithm=hashes.SHA1()), + ... algorithm=hashes.SHA1(), + ... label=None + ... ), + ... default_backend() + ... ) Handling partial RSA private keys diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index fdc540b9..de6bf5f8 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -194,7 +194,7 @@ Different KDFs are suitable for different tasks such as: .. method:: derive(key_material) :param bytes key_material: The input key material. - :retunr bytes: The derived key. + :return bytes: The derived key. Derives a new key from the input key material by performing both the extract and expand operations. diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 78bf6637..e5d8c65b 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -20,7 +20,7 @@ provides secrecy but not authenticity. That means an attacker can't see the message but an attacker can create bogus messages and force the application to decrypt them. -For this reason it is *strongly* recommended to combine encryption with a +For this reason it is **strongly** recommended to combine encryption with a message authentication code, such as :doc:`HMAC </hazmat/primitives/mac/hmac>`, in an "encrypt-then-MAC" formulation as `described by Colin Percival`_. diff --git a/docs/installation.rst b/docs/installation.rst index e2b35898..1efe1af5 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -128,13 +128,21 @@ Building cryptography with conda -------------------------------- Because of a `bug in conda`_, attempting to install cryptography out of the box -will result in an error. This can be resolved by setting the -``DYLD_LIBRARY_PATH`` environment variable: +will result in an error. This can be resolved by setting the library path +environment variable for your platform. + +On OS X: .. code-block:: console $ env DYLD_LIBRARY_PATH="$HOME/anaconda/lib" pip install cryptography +and on Linux: + +.. code-block:: console + + $ env LD_LIBRARY_PATH="$HOME/anaconda/lib" pip install cryptography + You will need to set this variable every time you start Python. For more information, consult `Greg Wilson's blog post`_ on the subject. |