diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/development/reviewing-patches.rst | 16 | ||||
| -rw-r--r-- | docs/development/test-vectors.rst | 7 | ||||
| -rw-r--r-- | docs/doing-a-release.rst | 13 | ||||
| -rw-r--r-- | docs/hazmat/backends/interfaces.rst | 34 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/dsa.rst | 125 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/index.rst | 1 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/padding.rst | 26 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 24 | ||||
| -rw-r--r-- | docs/index.rst | 6 |
9 files changed, 216 insertions, 36 deletions
diff --git a/docs/development/reviewing-patches.rst b/docs/development/reviewing-patches.rst index 9147a731..bd3ee96a 100644 --- a/docs/development/reviewing-patches.rst +++ b/docs/development/reviewing-patches.rst @@ -1,8 +1,11 @@ -Reviewing/merging patches -========================= +Reviewing and merging patches +============================= -Everyone is encouraged to review open pull requests. When reviewing a patch try -to keep each of these concepts in mind: +Everyone is encouraged to review open pull requests. We only ask that you try +and think carefully, ask questions and are `excellent to one another`_. Code +review is our opportunity to share knowledge, design ideas and make friends. + +When reviewing a patch try to keep each of these concepts in mind: Architecture ------------ @@ -24,8 +27,8 @@ Implementation * Has it been documented? * Will this change introduce new bugs? -Grammar/Style -------------- +Grammar and style +----------------- These are small things that are not caught by the automated style checkers. @@ -54,3 +57,4 @@ devastating, ``cryptography`` has a strict merge policy for committers: The purpose of these policies is to minimize the chances we merge a change that jeopardizes our users' security. +.. _`excellent to one another`: https://speakerdeck.com/ohrite/better-code-review diff --git a/docs/development/test-vectors.rst b/docs/development/test-vectors.rst index c5ea8152..484d06bd 100644 --- a/docs/development/test-vectors.rst +++ b/docs/development/test-vectors.rst @@ -20,7 +20,9 @@ Asymmetric ciphers * RSA PKCS #1 from the RSA FTP site (ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-1/ and ftp://ftp.rsa.com/pub/rsalabs/tmp/). * RSA FIPS 186-2 and PKCS1 v1.5 vulnerability test vectors from `NIST CAVP`_. -* DSA test vectors from `FIPS 186-2`_ and `FIPS 186-3`_. +* FIPS 186-2 and FIPS 186-3 DSA test vectors from `NIST CAVP`_. +* FIPS 186-2 and FIPS 186-3 ECDSA test vectors from `NIST CAVP`_. +* Ed25519 test vectors from the `Ed25519 website_`. * OpenSSL PEM RSA serialization vectors from the `OpenSSL example key`_ and `GnuTLS key parsing tests`_. * OpenSSL PEM DSA serialization vectors from the `GnuTLS example keys`_. @@ -127,8 +129,7 @@ header format (substituting the correct information): .. _`unencpkcs8.pem`: https://gitorious.org/gnutls/gnutls/source/f8d943b38bf74eaaa11d396112daf43cb8aa82ae:tests/pkcs8-decode/unencpkcs8.pem .. _`pkcs12_s2k_pem.c`: https://gitorious.org/gnutls/gnutls/source/f8d943b38bf74eaaa11d396112daf43cb8aa82ae:tests/pkcs12_s2k_pem.c .. _`Botan's ECC private keys`: https://github.com/randombit/botan/tree/4917f26a2b154e841cd27c1bcecdd41d2bdeb6ce/src/tests/data/ecc -.. _`FIPS 186-2`: http://csrc.nist.gov/groups/STM/cavp/documents/dss/186-2dsatestvectors.zip -.. _`FIPS 186-3`: http://csrc.nist.gov/groups/STM/cavp/documents/dss/186-3dsatestvectors.zip .. _`GnuTLS example keys`: https://gitorious.org/gnutls/gnutls/commit/ad2061deafdd7db78fd405f9d143b0a7c579da7b .. _`NESSIE IDEA vectors`: https://www.cosic.esat.kuleuven.be/nessie/testvectors/bc/idea/Idea-128-64.verified.test-vectors .. _`NESSIE`: https://en.wikipedia.org/wiki/NESSIE +.. _`Ed25519 website`: http://ed25519.cr.yp.to/software.html diff --git a/docs/doing-a-release.rst b/docs/doing-a-release.rst index fc88a91c..ad3b4791 100644 --- a/docs/doing-a-release.rst +++ b/docs/doing-a-release.rst @@ -39,3 +39,16 @@ correctly: '...' Verify that this is the version you just released. + +Post-release tasks +------------------ + +* Update the version number to the next major (e.g. ``0.5.dev1``) in + ``cryptography/__about__.py`` and + ``vectors/cryptography_vectors/__about__.py``. +* Add new :doc:`/changelog` entry with next version and note that it is under + active development +* Send a pull request with these items +* Check for any outstanding code undergoing a deprecation cycle by looking in + ``cryptography.utils`` for ``DeprecatedIn**`` definitions. If any exist open + a ticket to increment them for the next release. diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index c38f818f..9c401d28 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -285,3 +285,37 @@ A specific ``backend`` may provide one or more of these interfaces. :raises cryptography.exceptions.UnsupportedAlgorithm: If the data is encrypted with an unsupported algorithm. + + +.. class:: DSABackend + + .. versionadded:: 0.4 + + A backend with methods for using DSA. + + .. method:: generate_dsa_parameters(key_size) + + :param int key_size: The length of the modulus in bits. It should be + either "1024, 2048 or 3072". For keys generated in 2014 this should + be at least 2048. + Note that some applications (such as SSH) have not yet gained support + for larger key sizes specified in FIPS 186-3 and are still restricted + to only the 1024-bit keys specified in FIPS 186-2. + + :return: A new instance of a + :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters` + provider. + + .. method:: generate_dsa_private_key(parameters) + + :param parameters: A + :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters` + provider. + + :return: A new instance of a + :class:`~cryptography.hazmat.primitives.interfaces.DSAPrivateKey` + provider. + + :raises ValueError: This is raised if the key size is not (1024 or 2048 or 3072) + or if the OpenSSL version is older than 1.0.0 and the key size is larger than 1024 + because older OpenSSL versions don't support a key size larger than 1024. diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst new file mode 100644 index 00000000..1a6a6e0e --- /dev/null +++ b/docs/hazmat/primitives/asymmetric/dsa.rst @@ -0,0 +1,125 @@ +.. hazmat:: + +DSA +=== + +.. currentmodule:: cryptography.hazmat.primitives.asymmetric.dsa + +`DSA`_ is a `public-key`_ algorithm for signing messages. + +.. class:: DSAParameters(modulus, subgroup_order, generator) + + .. versionadded:: 0.4 + + DSA Parameters are required for generating a DSA private key. + + You should use :meth:`~generate` to generate new parameters. + + .. warning:: + This method only checks a limited set of properties of its arguments. + Using DSA parameters that you do not trust or with incorrect arguments + may lead to insecure operation, crashes, and other undefined behavior. + We recommend that you only ever load parameters that were generated + with software you trust. + + + This class conforms to the + :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters` + interface. + + :raises TypeError: This is raised when the arguments are not all integers. + + :raises ValueError: This is raised when the values of ``modulus``, + ``subgroup_order``, or ``generator`` do + not match the bounds specified in `FIPS 186-4`_. + + .. classmethod:: generate(key_size, backend) + + Generate a new ``DSAParameters`` instance using ``backend``. + + :param int key_size: The length of the modulus in bits. It should be + either "1024, 2048 or 3072". For keys generated in 2014 this should + be `at least 2048`_ (See page 41). + Note that some applications (such as SSH) have not yet gained support + for larger key sizes specified in FIPS 186-3 and are still restricted + to only the 1024-bit keys specified in FIPS 186-2. + + :return: A new instance of ``DSAParameters`` + + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if + the provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.DSABackend` + + +.. class:: DSAPrivateKey(modulus, subgroup_order, generator, x, y) + + .. versionadded:: 0.4 + + A DSA private key is required for signing messages. + + You should use :meth:`~generate` to generate new keys. + + .. warning:: + This method only checks a limited set of properties of its arguments. + Using a DSA private key 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.DSAPrivateKey` + interface. + + :raises TypeError: This is raised when the arguments are not all integers. + + :raises ValueError: This is raised when the values of ``modulus``, + ``subgroup_order``, or ``generator`` do + not match the bounds specified in `FIPS 186-4`_. + + .. classmethod:: generate(parameters, backend) + + Generate a new ``DSAPrivateKey`` instance using ``backend``. + + :param parameters: A + :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters` + provider. + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.DSABackend` + provider. + :return: A new instance of ``DSAPrivateKey``. + + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if + the provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.DSABackend` + + :raises ValueError: This is raised if the key size is not (1024 or 2048 or 3072) + or if the OpenSSL version is older than 1.0.0 and the key size is larger than 1024 + because older OpenSSL versions don't support a key size larger than 1024. + + +.. class:: DSAPublicKey(modulus, subgroup_order, generator, y) + + .. versionadded:: 0.4 + + A DSA public key is required for verifying 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.DSAPublicKey` + interface. + + :raises TypeError: This is raised when the arguments are not all integers. + + :raises ValueError: This is raised when the values of ``modulus``, + ``subgroup_order``,``generator``, or ``y`` + do not match the bounds specified in `FIPS 186-4`_. + + +.. _`DSA`: https://en.wikipedia.org/wiki/Digital_Signature_Algorithm +.. _`public-key`: https://en.wikipedia.org/wiki/Public-key_cryptography +.. _`FIPS 186-4`: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf +.. _`at least 2048`: http://www.ecrypt.eu.org/documents/D.SPA.20.pdf diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst index 7ec1c5f2..ca048d11 100644 --- a/docs/hazmat/primitives/asymmetric/index.rst +++ b/docs/hazmat/primitives/asymmetric/index.rst @@ -6,5 +6,6 @@ Asymmetric algorithms .. toctree:: :maxdepth: 1 + dsa rsa padding diff --git a/docs/hazmat/primitives/asymmetric/padding.rst b/docs/hazmat/primitives/asymmetric/padding.rst index 2a5de3c7..89af7eaa 100644 --- a/docs/hazmat/primitives/asymmetric/padding.rst +++ b/docs/hazmat/primitives/asymmetric/padding.rst @@ -10,10 +10,13 @@ Padding correct padding signatures can be forged, messages decrypted, and private keys compromised. -.. class:: PSS(mgf) +.. class:: PSS(mgf, salt_length) .. versionadded:: 0.3 + .. versionchanged:: 0.4 + Added ``salt_length`` parameter. + PSS (Probabilistic Signature Scheme) is a signature scheme defined in :rfc:`3447`. It is more complex than PKCS1 but possesses a `security proof`_. This is the `recommended padding algorithm`_ for RSA signatures. @@ -21,6 +24,14 @@ Padding :param mgf: A mask generation function object. At this time the only supported MGF is :class:`MGF1`. + :param int salt_length: The length of the salt. It is recommended that this + be set to ``PSS.MAX_LENGTH``. + + .. attribute:: MAX_LENGTH + + Pass this attribute to ``salt_length`` to get the maximum salt length + available. + .. class:: PKCS1v15() .. versionadded:: 0.3 @@ -31,10 +42,13 @@ Padding Mask generation functions ~~~~~~~~~~~~~~~~~~~~~~~~~ -.. class:: MGF1(algorithm, salt_length) +.. class:: MGF1(algorithm) .. versionadded:: 0.3 + .. versionchanged:: 0.4 + Deprecated the ``salt_length`` parameter. + MGF1 (Mask Generation Function 1) is used as the mask generation function in :class:`PSS` padding. It takes a hash algorithm and a salt length. @@ -42,14 +56,6 @@ Mask generation functions :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` provider. - :param int salt_length: The length of the salt. It is recommended that this - be set to ``MGF1.MAX_LENGTH``. - - .. attribute:: MAX_LENGTH - - Pass this attribute to ``salt_length`` to get the maximum salt length - available. - .. _`Padding is critical`: http://rdist.root.org/2009/10/06/why-rsa-encryption-padding-is-critical/ .. _`security proof`: http://eprint.iacr.org/2001/062.pdf diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 182e35d2..5074f1c5 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -42,9 +42,9 @@ RSA Usually one of the small Fermat primes 3, 5, 17, 257, 65537. If in doubt you should `use 65537`_. :param int key_size: The length of the modulus in bits. For keys - generated in 2014 this should be `at least 2048`_. (See page 41.) - Must be at least 512. Some backends may have additional - limitations. + generated in 2014 it is strongly recommended to be + `at least 2048`_ (See page 41). It must not be less than 512. + Some backends may have additional limitations. :param backend: A :class:`~cryptography.hazmat.backends.interfaces.RSABackend` provider. @@ -73,10 +73,8 @@ RSA ... ) >>> signer = private_key.signer( ... padding.PSS( - ... mgf=padding.MGF1( - ... algorithm=hashes.SHA256(), - ... salt_length=padding.MGF1.MAX_LENGTH - ... ) + ... mgf=padding.MGF1(hashes.SHA256()), + ... salt_length=padding.PSS.MAX_LENGTH ... ), ... hashes.SHA256(), ... default_backend() @@ -158,10 +156,8 @@ RSA ... ) >>> signer = private_key.signer( ... padding.PSS( - ... mgf=padding.MGF1( - ... algorithm=hashes.SHA256(), - ... salt_length=padding.MGF1.MAX_LENGTH - ... ) + ... mgf=padding.MGF1(hashes.SHA256()), + ... salt_length=padding.PSS.MAX_LENGTH ... ), ... hashes.SHA256(), ... default_backend() @@ -173,10 +169,8 @@ RSA >>> verifier = public_key.verifier( ... signature, ... padding.PSS( - ... mgf=padding.MGF1( - ... algorithm=hashes.SHA256(), - ... salt_length=padding.MGF1.MAX_LENGTH - ... ) + ... mgf=padding.MGF1(hashes.SHA256()), + ... salt_length=padding.PSS.MAX_LENGTH ... ), ... hashes.SHA256(), ... default_backend() diff --git a/docs/index.rst b/docs/index.rst index 58424bfc..083533c9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,7 +2,9 @@ Welcome to ``cryptography`` =========================== ``cryptography`` is a Python library which exposes cryptographic recipes and -primitives. Our goal is for it to be your "cryptographic standard library". +primitives. Our goal is for it to be your "cryptographic standard library". If +you are interested in learning more about the field of cryptography, we +recommend `Crypto 101, by Laurens Van Houtven`_. Installation ------------ @@ -98,4 +100,4 @@ The ``cryptography`` open source project documentation. If you're interested in discussing an audit please :doc:`get in touch </community>`. -.. _`pre-compiled binaries`: https://www.openssl.org/related/binaries.html +.. _`Crypto 101, by Laurens Van Houtven`: https://www.crypto101.io/ |