From e44efb634fb1db024fcd6e110eacbf59abbc4782 Mon Sep 17 00:00:00 2001
From: Aviv Palivoda <palaviv@gmail.com>
Date: Mon, 6 Mar 2017 04:24:55 +0200
Subject: DH subgroup order (q) (#3369)

* Support DH q (subgroup order)

* Change RFC5114.txt to NIST format

* Add tests for DH q

* Update docs for DH q

* Fix pep8

* Improve test covergae for DH q

* Create _dh_params_dup that copy q if DHparams_dup don't

On OpenSSL < 1.0.2 DHparams_dup don't copy q. _dh_params_dup
call DHparams_dup and if the version is smaller than 1.0.2
copy q manually

* Copy q manually on libressl

* Add to test vectors serialized RFC5114 2048 bit DH parameters with 224 bit subgroup

* Support serialization of DH with q

* Add tests for serialization of DH with q

* Support DH serialization with q only if Cryptography_HAS_EVP_PKEY_DHX is true

* Raise exception when trying to serialize DH X9.42 when not supported

* raise unsupported key type when deserilizing DH X9.42 if not supported

* pep8 fixes

* Fix test_serialization

* Add dhx_serialization_supported method to DHBacked

* document q in dh_parameters_supported

* Rename dhx_serialization_supported to dh_x942_serialization_supported
---
 docs/development/test-vectors.rst        | 14 ++++++++++++++
 docs/hazmat/backends/interfaces.rst      | 15 ++++++++++++---
 docs/hazmat/primitives/asymmetric/dh.rst | 12 ++++++++++--
 3 files changed, 36 insertions(+), 5 deletions(-)

(limited to 'docs')

diff --git a/docs/development/test-vectors.rst b/docs/development/test-vectors.rst
index 15fe2d2e..f9f865e8 100644
--- a/docs/development/test-vectors.rst
+++ b/docs/development/test-vectors.rst
@@ -110,6 +110,20 @@ Key exchange
   ``vectors/cryptography_vectors/asymmetric/DH/dhpub.der`` contains
   are the above parameters and keys in DER format.
 
+* ``vectors/cryptography_vectors/asymmetric/DH/dhp_rfc5114_2.pem``,
+  ``vectors/cryptography_vectors/asymmetric/DH/dhkey_rfc5114_2.pem`` and
+  ``vectors/cryptography_vectors/asymmetric/DH/dhpub_rfc5114_2.pem`` contains
+  Diffie-Hellman parameters and key respectively. The keys were
+  generated using OpenSSL following `DHKE`_ guide. When creating the
+  parameters we added the `-pkeyopt dh_rfc5114:2` option to use
+  RFC5114 2048 bit DH parameters with 224 bit subgroup.
+  ``vectors/cryptography_vectors/asymmetric/DH/dhkey_rfc5114_2.txt`` contains
+  all parameter in text.
+  ``vectors/cryptography_vectors/asymmetric/DH/dhp_rfc5114_2.der``,
+  ``vectors/cryptography_vectors/asymmetric/DH/dhkey_rfc5114_2.der`` and
+  ``vectors/cryptography_vectors/asymmetric/DH/dhpub_rfc5114_2.der`` contains
+  are the above parameters and keys in DER format.
+
 
 X.509
 ~~~~~
diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst
index 87fc6ab7..4f15d5c6 100644
--- a/docs/hazmat/backends/interfaces.rst
+++ b/docs/hazmat/backends/interfaces.rst
@@ -666,14 +666,23 @@ A specific ``backend`` may provide one or more of these interfaces.
         :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised
             when any backend specific criteria are not met.
 
-    .. method:: dh_parameters_supported(p, g)
+    .. method:: dh_parameters_supported(p, g, q=None)
 
         :param int p: The p value of the DH key.
 
         :param int g: The g value of the DH key.
 
-        :returns: ``True`` if the given values of ``p`` and ``g`` are supported
-            by this backend, otherwise ``False``.
+        :param int q: The q value of the DH key.
+
+        :returns: ``True`` if the given values of ``p``, ``g`` and ``q``
+            are supported by this backend, otherwise ``False``.
+
+    .. versionadded:: 1.8
+
+    .. method:: dh_x942_serialization_supported()
+
+        :returns: True if serialization of DH objects with
+            subgroup order (q) is supported by this backend.
 
 
 .. class:: ScryptBackend
diff --git a/docs/hazmat/primitives/asymmetric/dh.rst b/docs/hazmat/primitives/asymmetric/dh.rst
index 73e534e2..759b265b 100644
--- a/docs/hazmat/primitives/asymmetric/dh.rst
+++ b/docs/hazmat/primitives/asymmetric/dh.rst
@@ -223,7 +223,7 @@ Key interfaces
 Numbers
 ~~~~~~~
 
-.. class:: DHParameterNumbers(p, g)
+.. class:: DHParameterNumbers(p, g, q=None)
 
     .. versionadded:: 0.8
 
@@ -239,7 +239,15 @@ Numbers
 
         :type: int
 
-        The generator value. Must be 2 or 5.
+        The generator value. Must be 2 or 5 (Unless q is given).
+
+    .. attribute:: q
+
+        .. versionadded:: 1.8
+
+        :type: int
+
+        p subgroup order value.
 
 .. class:: DHPrivateNumbers(x, public_numbers)
 
-- 
cgit v1.2.3