From 6b08aba7f1eb296461528328a3c9871fa7594fc4 Mon Sep 17 00:00:00 2001
From: Aviv Palivoda <palaviv@gmail.com>
Date: Sat, 24 Jun 2017 22:00:28 +0300
Subject: Dh parameters serialization (#3504)

* Support DH parameter serizalization - no X9.42

* Support X9.42 serialization - DER not working

* Fix dhp_rfc5114_2.der

Changing the DER parameters serialization after the
fix in openssl commit a292c9f1b835

* DH parameters X9.42 DER serialization fixed

* fix _skip_dhx_unsupported

* document DH parameter_bytes

* PEP8 fixes

* Document load_pem_parameters

* Document load_der_parameters

* document ParameterFormat

* Increase test coverage

* Increase test covrage

* Remove unneeded check

* Fix typo

* Fix error in load_der_parameters

* Add load_pem_parameters and load_der_parameters to interfaces

* CR fixes

* Removed unverified phrase

* Update version to 2.0

* Fix pep8

* Rename ParameterFormat.ASN1 to ParameterFormat.DHParameter

* link pkcs3

* Add new line at end of file to serialization.rst

* Rename DHparameters to PKCS3

* doc CR fix
---
 .../hazmat/primitives/asymmetric/serialization.rst | 91 ++++++++++++++++++++++
 1 file changed, 91 insertions(+)

(limited to 'docs/hazmat/primitives/asymmetric/serialization.rst')

diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst
index b745332e..b0cfbd0e 100644
--- a/docs/hazmat/primitives/asymmetric/serialization.rst
+++ b/docs/hazmat/primitives/asymmetric/serialization.rst
@@ -63,6 +63,20 @@ Key Serialization
     def sign_with_dsa_key(key, message):
         return b""
 
+    parameters_pem_data = b"""
+    -----BEGIN DH PARAMETERS-----
+    MIGHAoGBALsrWt44U1ojqTy88o0wfjysBE51V6Vtarjm2+5BslQK/RtlndHde3gx
+    +ccNs+InANszcuJFI8AHt4743kGRzy5XSlul4q4dDJENOHoyqYxueFuFVJELEwLQ
+    XrX/McKw+hS6GPVQnw6tZhgGo9apdNdYgeLQeQded8Bum8jqzP3rAgEC
+    -----END DH PARAMETERS-----
+    """.strip()
+
+    parameters_der_data = base64.b64decode(
+        b"MIGHAoGBALsrWt44U1ojqTy88o0wfjysBE51V6Vtarjm2+5BslQK/RtlndHde3gx+ccNs+In"
+        b"ANsz\ncuJFI8AHt4743kGRzy5XSlul4q4dDJENOHoyqYxueFuFVJELEwLQXrX/McKw+hS6GP"
+        b"VQnw6tZhgG\no9apdNdYgeLQeQded8Bum8jqzP3rAgEC"
+    )
+
 There are several common schemes for serializing asymmetric private and public
 keys to bytes. They generally support encryption of private keys and additional
 key metadata.
@@ -181,6 +195,37 @@ all begin with ``-----BEGIN {format}-----`` and end with ``-----END
     :raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized key
         is of a type that is not supported by the backend.
 
+.. function:: load_pem_parameters(data, backend)
+
+    .. versionadded:: 2.0
+
+    Deserialize encryption parameters from PEM encoded data to one of the supported
+    asymmetric encryption parameters types.
+
+    .. doctest::
+
+        >>> from cryptography.hazmat.primitives.serialization import load_pem_parameters
+        >>> from cryptography.hazmat.primitives.asymmetric import dh
+        >>> parameters = load_pem_parameters(parameters_pem_data, backend=default_backend())
+        >>> isinstance(parameters, dh.DHParameters)
+        True
+
+    :param bytes data: The PEM encoded parameters data.
+
+    :param backend: An instance of
+        :class:`~cryptography.hazmat.backends.interfaces.PEMSerializationBackend`.
+
+
+    :returns: Currently only
+        :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameters`
+        supported.
+
+    :raises ValueError: If the PEM data's structure could not be decoded
+        successfully.
+
+    :raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized parameters
+        is of a type that is not supported by the backend.
+
 DER
 ~~~
 
@@ -268,6 +313,37 @@ the rest.
         >>> isinstance(key, rsa.RSAPublicKey)
         True
 
+.. function:: load_der_parameters(data, backend)
+
+    .. versionadded:: 2.0
+
+    Deserialize encryption parameters from DER encoded data to one of the supported
+    asymmetric encryption parameters types.
+
+    :param bytes data: The DER encoded parameters data.
+
+    :param backend: An instance of
+        :class:`~cryptography.hazmat.backends.interfaces.DERSerializationBackend`.
+
+    :returns: Currently only
+        :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameters`
+        supported.
+
+    :raises ValueError: If the DER data's structure could not be decoded
+        successfully.
+
+    :raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized key is of a type that
+        is not supported by the backend.
+
+    .. doctest::
+
+        >>> from cryptography.hazmat.backends import default_backend
+        >>> from cryptography.hazmat.primitives.asymmetric import dh
+        >>> from cryptography.hazmat.primitives.serialization import load_der_parameters
+        >>> parameters = load_der_parameters(parameters_der_data, backend=default_backend())
+        >>> isinstance(parameters, dh.DHParameters)
+        True
+
 
 OpenSSH Public Key
 ~~~~~~~~~~~~~~~~~~
@@ -379,6 +455,18 @@ Serialization Formats
         The public key format used by OpenSSH (e.g. as found in
         ``~/.ssh/id_rsa.pub`` or ``~/.ssh/authorized_keys``).
 
+.. class:: ParameterFormat
+
+    .. versionadded:: 2.0
+
+    An enumeration for parameters formats. Used with the ``parameter_bytes``
+    method available on
+    :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParametersWithSerialization`.
+
+    .. attribute:: PKCS3
+
+        ASN1 DH parameters sequence as defined in `PKCS3`_.
+
 Serialization Encodings
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -445,3 +533,6 @@ Serialization Encryption Types
 .. class:: NoEncryption
 
     Do not encrypt.
+
+
+.. _`PKCS3`: https://www.emc.com/emc-plus/rsa-labs/standards-initiatives/pkcs-3-diffie-hellman-key-agreement-standar.htm
-- 
cgit v1.2.3