Merge pull request #878 from public/ecdsa-interfaces

ECC interfaces

7 files changed, 354 insertions, 0 deletions

diff --git a/cryptography/hazmat/primitives/asymmetric/ec.py b/cryptography/hazmat/primitives/asymmetric/ec.py
new file mode 100644
index 00000000..1e49ad7b
--- /dev/null
+++ b/cryptography/hazmat/primitives/asymmetric/ec.py
@@ -0,0 +1,69 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import, division, print_function
+
+import six
+
+from cryptography.hazmat.primitives import interfaces
+
+
+class EllipticCurvePublicNumbers(object):
+    def __init__(self, x, y, curve):
+        if (
+            not isinstance(x, six.integer_types) or
+            not isinstance(y, six.integer_types)
+        ):
+            raise TypeError("x and y must be integers.")
+
+        if not isinstance(curve, interfaces.EllipticCurve):
+            raise TypeError("curve must provide the EllipticCurve interface.")
+
+        self._y = y
+        self._x = x
+        self._curve = curve
+
+    @property
+    def curve(self):
+        return self._curve
+
+    @property
+    def x(self):
+        return self._x
+
+    @property
+    def y(self):
+        return self._y
+
+
+class EllipticCurvePrivateNumbers(object):
+    def __init__(self, private_value, public_numbers):
+        if not isinstance(private_value, six.integer_types):
+            raise TypeError("private_value must be an integer.")
+
+        if not isinstance(public_numbers, EllipticCurvePublicNumbers):
+            raise TypeError(
+                "public_numbers must be an EllipticCurvePublicNumbers "
+                "instance."
+            )
+
+        self._private_value = private_value
+        self._public_numbers = public_numbers
+
+    @property
+    def private_value(self):
+        return self._private_value
+
+    @property
+    def public_numbers(self):
+        return self._public_numbers
diff --git a/cryptography/hazmat/primitives/interfaces.py b/cryptography/hazmat/primitives/interfaces.py
index 810a67a4..0dd1d01a 100644
--- a/cryptography/hazmat/primitives/interfaces.py
+++ b/cryptography/hazmat/primitives/interfaces.py
@@ -489,3 +489,63 @@ class CMACContext(object):
         """
         Return a CMACContext that is a copy of the current context.
         """
+
+
+@six.add_metaclass(abc.ABCMeta)
+class EllipticCurve(object):
+    @abc.abstractproperty
+    def name(self):
+        """
+        The name of the curve. e.g. secp256r1.
+        """
+
+    @abc.abstractproperty
+    def key_size(self):
+        """
+        The bit length of the base point of the curve.
+        """
+
+
+@six.add_metaclass(abc.ABCMeta)
+class EllipticCurveSignatureAlgorithm(object):
+    @abc.abstractproperty
+    def algorithm(self):
+        """
+        The digest algorithm used with this signature.
+        """
+
+
+@six.add_metaclass(abc.ABCMeta)
+class EllipticCurvePrivateKey(object):
+    @abc.abstractmethod
+    def signer(self, signature_algorithm):
+        """
+        Returns an AsymmetricSignatureContext used for signing data.
+        """
+
+    @abc.abstractmethod
+    def public_key(self):
+        """
+        The EllipticCurvePublicKey for this private key.
+        """
+
+    @abc.abstractproperty
+    def curve(self):
+        """
+        The EllipticCurve that this key is on.
+        """
+
+
+@six.add_metaclass(abc.ABCMeta)
+class EllipticCurvePublicKey(object):
+    @abc.abstractmethod
+    def verifier(self, signature, signature_algorithm):
+        """
+        Returns an AsymmetricVerificationContext used for signing data.
+        """
+
+    @abc.abstractproperty
+    def curve(self):
+        """
+        The EllipticCurve that this key is on.
+        """
diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst
new file mode 100644
index 00000000..f88b965a
--- /dev/null
+++ b/docs/hazmat/primitives/asymmetric/ec.rst
@@ -0,0 +1,51 @@
+.. hazmat::
+
+Elliptic Curve
+==============
+
+.. currentmodule:: cryptography.hazmat.primitives.asymmetric.ec
+
+
+.. class:: EllipticCurvePrivateNumbers(private_value, public_numbers)
+
+    .. versionadded:: 0.5
+
+    The collection of integers that make up an EC private key.
+
+    .. attribute:: public_numbers
+
+        :type: :class:`~cryptography.hazmat.primitives.ec.EllipticCurvePublicNumbers`
+
+        The :class:`EllipticCurvePublicNumbers` which makes up the EC public
+        key associated with this EC private key.
+
+    .. attribute:: private_value
+
+        :type: int
+
+        The private value.
+
+
+.. class:: EllipticCurvePublicNumbers(x, y, curve)
+
+    .. versionadded:: 0.5
+
+    The collection of integers that make up an EC public key.
+
+     .. attribute:: curve
+
+        :type: :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurve`
+
+        The elliptic curve for this key.
+
+    .. attribute:: x
+
+        :type: int
+
+        The affine x component of the public point used for verifying.
+
+    .. attribute:: y
+
+        :type: int
+
+        The affine y component of the public point used for verifying.
diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst
index 047f9cb9..6a5228ba 100644
--- a/docs/hazmat/primitives/asymmetric/index.rst
+++ b/docs/hazmat/primitives/asymmetric/index.rst
@@ -7,6 +7,7 @@ Asymmetric algorithms
     :maxdepth: 1
 
     dsa
+    ec
     rsa
     padding
     serialization
diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst
index dc09a26f..b2857f58 100644
--- a/docs/hazmat/primitives/interfaces.rst
+++ b/docs/hazmat/primitives/interfaces.rst
@@ -463,6 +463,97 @@ Asymmetric interfaces
             :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext`
 
 
+.. class:: EllipticCurve
+
+    .. versionadded:: 0.5
+
+    A named elliptic curve.
+
+    .. attribute:: name
+
+        :type: string
+
+        The name of the curve. Usually the name used for the ASN.1 OID such as
+        ``secp256k1``.
+
+    .. attribute:: key_size
+
+        :type: int
+
+        The bit length of the curve's base point.
+
+
+.. class:: EllipticCurveSignatureAlgorithm
+
+    .. versionadded:: 0.5
+
+    A signature algorithm for use with elliptic curve keys.
+
+    .. attribute:: algorithm
+
+        :type: :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
+
+        The digest algorithm to be used with the signature scheme.
+
+
+.. class:: EllipticCurvePrivateKey
+
+    .. versionadded:: 0.5
+
+    An elliptic curve private key for use with an algorithm such as `ECDSA`_ or
+    `EdDSA`_.
+
+    .. classmethod:: signer(signature_algorithm)
+
+        Sign data which can be verified later by others using the public key.
+
+        :param signature_algorithm: An instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurveSignatureAlgorithm`
+            provider.
+
+        :returns:
+            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext`
+
+    .. attribute:: curve
+
+        :type: :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurve`
+
+        The elliptic curve for this key.
+
+    .. method:: public_key()
+
+        :return: :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurvePublicKey`
+
+        The EllipticCurvePublicKey object for this private key.
+
+
+.. class:: EllipticCurvePublicKey
+
+    .. versionadded:: 0.5
+
+    An elliptic curve public key.
+
+    .. classmethod:: verifier(signer, signature_algorithm)
+
+        Verify data was signed by the private key associated with this public
+        key.
+
+        :param bytes signature: The signature to verify.
+
+        :param signature_algorithm: An instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurveSignatureAlgorithm`
+            provider.
+
+        :returns:
+            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext`
+
+     .. attribute:: curve
+
+        :type: :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurve`
+
+        The elliptic curve for this key.
+
+
 .. class:: AsymmetricSignatureContext
 
     .. versionadded:: 0.2
@@ -612,3 +703,5 @@ Key derivation functions
 .. _`Chinese remainder theorem`: https://en.wikipedia.org/wiki/Chinese_remainder_theorem
 .. _`DSA`: https://en.wikipedia.org/wiki/Digital_Signature_Algorithm
 .. _`CMAC`: https://en.wikipedia.org/wiki/CMAC
+.. _`ECDSA`: http://en.wikipedia.org/wiki/ECDSA
+.. _`EdDSA`: http://en.wikipedia.org/wiki/EdDSA
diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
index b5896158..9baf0822 100644
--- a/docs/spelling_wordlist.txt
+++ b/docs/spelling_wordlist.txt
@@ -1,3 +1,4 @@
+affine
 backend
 backends
 Backends
diff --git a/tests/hazmat/primitives/test_ec.py b/tests/hazmat/primitives/test_ec.py
new file mode 100644
index 00000000..53985fe2
--- /dev/null
+++ b/tests/hazmat/primitives/test_ec.py
@@ -0,0 +1,79 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+from __future__ import absolute_import, division, print_function
+
+import pytest
+
+from cryptography import utils
+from cryptography.hazmat.primitives import interfaces
+from cryptography.hazmat.primitives.asymmetric import ec
+
+
+@utils.register_interface(interfaces.EllipticCurve)
+class DummyCurve(object):
+    name = "dummy-curve"
+
+
+class TestECC(object):
+    def test_ec_numbers(self):
+        numbers = ec.EllipticCurvePrivateNumbers(
+            1,
+            ec.EllipticCurvePublicNumbers(
+                2, 3, DummyCurve()
+            )
+        )
+
+        assert numbers.private_value == 1
+        assert numbers.public_numbers.x == 2
+        assert numbers.public_numbers.y == 3
+        assert isinstance(numbers.public_numbers.curve, DummyCurve)
+
+        with pytest.raises(TypeError):
+            ec.EllipticCurvePrivateNumbers(
+                None,
+                ec.EllipticCurvePublicNumbers(
+                    2, 3, DummyCurve()
+                )
+            )
+
+        with pytest.raises(TypeError):
+            ec.EllipticCurvePrivateNumbers(
+                1,
+                ec.EllipticCurvePublicNumbers(
+                    None, 3, DummyCurve()
+                )
+            )
+
+        with pytest.raises(TypeError):
+            ec.EllipticCurvePrivateNumbers(
+                1,
+                ec.EllipticCurvePublicNumbers(
+                    2, None, DummyCurve()
+                )
+            )
+
+        with pytest.raises(TypeError):
+            ec.EllipticCurvePrivateNumbers(
+                1,
+                ec.EllipticCurvePublicNumbers(
+                    2, 3, None
+                )
+            )
+
+        with pytest.raises(TypeError):
+            ec.EllipticCurvePrivateNumbers(
+                1,
+                None
+            )