From 21fc5827f34c33e3dc2afcdff437b62751dbbe4e Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Fri, 4 Jul 2014 09:28:55 -0500 Subject: Improve EC docs * Fix some typos in links * Reorder docs to prioritize example above Numbers classes * Add more info to changelog * Add `Lange` to spelling wordlist since it fails on my machine (but not on the CI...so weird) --- CHANGELOG.rst | 3 +- docs/hazmat/primitives/asymmetric/ec.rst | 71 ++++++++++++++++---------------- docs/spelling_wordlist.txt | 1 + 3 files changed, 39 insertions(+), 36 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 13bc23f8..a49f3f46 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -23,7 +23,8 @@ Changelog and :class:`~cryptography.hazmat.backends.interfaces.TraditionalOpenSSLSerializationBackend` support to the :doc:`/hazmat/backends/openssl`. -* Added :class:`~cryptography.hazmat.backends.interfaces.EllipticCurveBackend`. +* Added :doc:`/hazmat/primitives/asymmetric/ec` and + :class:`~cryptography.hazmat.backends.interfaces.EllipticCurveBackend`. * Added :class:`~cryptography.hazmat.primitives.ciphers.modes.ECB` support for :class:`~cryptography.hazmat.primitives.ciphers.algorithms.TripleDES` on :doc:`/hazmat/backends/commoncrypto` and :doc:`/hazmat/backends/openssl`. diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst index 89d00c8d..0e19bb2e 100644 --- a/docs/hazmat/primitives/asymmetric/ec.rst +++ b/docs/hazmat/primitives/asymmetric/ec.rst @@ -13,7 +13,7 @@ Elliptic curve cryptography Generate a new private key on ``curve`` for use with ``backend``. :param backend: A - :class:`~cryptography.hazmat.primtives.interfaces.EllipticCurve` + :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurve` provider. :param backend: A @@ -21,10 +21,38 @@ Elliptic curve cryptography provider. :returns: A new instance of a - :class:`~cryptography.hazmat.primtivies.interfaces.EllipticCurvePrivateKey` + :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurvePrivateKey` provider. +Elliptic Curve Signature Algorithms +----------------------------------- + +.. class:: ECDSA(algorithm) + + .. versionadded:: 0.5 + + The ECDSA signature algorithm first standardized in NIST publication + `FIPS 186-3`_, and later in `FIPS 186-4`_. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + .. doctest:: + + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives import hashes + >>> from cryptography.hazmat.primitives.asymmetric import ec + >>> private_key = ec.generate_private_key( + ... ec.SECP384R1(), default_backend() + ... ) + >>> signer = private_key.signer(ec.ECDSA(hashes.SHA256())) + >>> signer.update(b"this is some data I'd like") + >>> signer.update(b" to sign") + >>> signature = signer.finalize() + + .. class:: EllipticCurvePrivateNumbers(private_value, public_numbers) .. versionadded:: 0.5 @@ -33,7 +61,7 @@ Elliptic curve cryptography .. attribute:: public_numbers - :type: :class:`~cryptography.hazmat.primitives.ec.EllipticCurvePublicNumbers` + :type: :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicNumbers` The :class:`EllipticCurvePublicNumbers` which makes up the EC public key associated with this EC private key. @@ -54,7 +82,7 @@ Elliptic curve cryptography provider. :returns: A new instance of a - :class:`~cryptography.hazmat.primtivies.interfaces.EllipticCurvePrivateKey` + :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurvePrivateKey` provider. @@ -92,37 +120,9 @@ Elliptic curve cryptography provider. :returns: A new instance of a - :class:`~cryptography.hazmat.primtivies.interfaces.EllipticCurvePublicKey` + :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurvePublicKey` provider. - -Elliptic Curve Signature Algorithms ------------------------------------ - -.. class:: ECDSA(algorithm) - - .. versionadded:: 0.5 - - The ECDSA signature algorithm first standardized in NIST publication - `FIPS 186-3`_, and later in `FIPS 186-4`_. - - :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` - provider. - - .. doctest:: - - >>> from cryptography.hazmat.backends import default_backend - >>> from cryptography.hazmat.primitives import hashes - >>> from cryptography.hazmat.primitives.asymmetric import ec - >>> private_key = ec.generate_private_key( - ... ec.SECP384R1(), default_backend() - ... ) - >>> signer = private_key.signer(ec.ECDSA(hashes.SHA256())) - >>> signer.update(b"this is some data I'd like") - >>> signer.update(b" to sign") - >>> signature = signer.finalize() - Elliptic Curves --------------- @@ -142,8 +142,9 @@ Prime fields also `minimize the number of security concerns for elliptic-curve cryptography`_. However there is `some concern`_ that both the prime field and binary field ("B") NIST curves may have been weakened during their generation. -Currently `cryptograhy` only supports NIST curves, none of which are considered -"safe" by the `SafeCurves`_ project run by Daniel J. Bernstein and Tanja Lange. +Currently `cryptography` only supports NIST curves, none of which are +considered "safe" by the `SafeCurves`_ project run by Daniel J. Bernstein and +Tanja Lange. All named curves are providers of :class:`~cryptography.hazmat.primtives.interfaces.EllipticCurve`. diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index 4668cfa9..d90547a8 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -29,6 +29,7 @@ introspectability invariants iOS Koblitz +Lange metadata namespace namespaces -- cgit v1.2.3