EC samples for verifying a singature, + serialization (#3076)

* first draft of verification and serialization

* tweaks in the RST syntax

* added example of deserialization

* taking into account the returned value, so that doctests pass

* adjusted rst syntax and indentation for code samples

* removed print call

* forgot to actually call splitlines

* added missing argument when loading private key

* added Deserialization to dictionary

* made lines shorter to meet style requirements

* applied requested changes in style

1 files changed, 79 insertions, 0 deletions

diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst
index add5966a..2421d921 100644
--- a/docs/hazmat/primitives/asymmetric/ec.rst
+++ b/docs/hazmat/primitives/asymmetric/ec.rst
@@ -61,6 +61,21 @@ Elliptic Curve Signature Algorithms
     :func:`~cryptography.hazmat.primitives.asymmetric.utils.decode_dss_signature`.
 
 
+    Verification requires the public key, the signature itself, the signed data, and knowledge of the hashing algorithm that was used when producing the signature:
+
+    >>> public_key = private_key.public_key()
+    >>> verifier = public_key.verifier(signature, ec.ECDSA(hashes.SHA256()))
+    >>> verifier.update(b"this is some data I'd like")
+    >>> verifier.update(b" to sign")
+    >>> verifier.verify()
+    True
+
+    The last call will either return ``True`` or raise an :class:`~cryptography.exceptions.InvalidSignature` exception.
+
+    .. note::
+        Although in this case the public key was derived from the private one, in a typical setting you will not possess the private key. The `Key loading`_ section explains how to load the public key from other sources.
+
+
 
 .. class:: EllipticCurvePrivateNumbers(private_value, public_numbers)
 
@@ -533,6 +548,70 @@ Key Interfaces
     Alias for :class:`EllipticCurvePublicKey`.
 
 
+
+Serialization
+~~~~~~~~~~~~~
+
+This sample demonstrates how to generate a private key and serialize it.
+
+
+.. doctest::
+
+    >>> from cryptography.hazmat.backends import default_backend
+    >>> from cryptography.hazmat.primitives import hashes
+    >>> from cryptography.hazmat.primitives.asymmetric import ec
+    >>> from cryptography.hazmat.primitives import serialization
+
+    >>> private_key = ec.generate_private_key(ec.SECP384R1(), default_backend())
+
+    >>> serialized_private = private_key.private_bytes(
+    ...     encoding=serialization.Encoding.PEM,
+    ...     format=serialization.PrivateFormat.PKCS8,
+    ...     encryption_algorithm=serialization.BestAvailableEncryption(b'testpassword')
+    ...     )
+    >>> serialized_private.splitlines()[0]
+    '-----BEGIN ENCRYPTED PRIVATE KEY-----'
+
+You can also serialize the key without a password, by relying on
+:class:`~cryptography.hazmat.primitives.serialization.NoEncryption`.
+
+The public key is serialized as follows:
+
+
+.. doctest::
+
+    >>> public_key = private_key.public_key()
+    >>> serialized_public = public_key.public_bytes(
+    ...     encoding=serialization.Encoding.PEM,
+    ...     format=serialization.PublicFormat.SubjectPublicKeyInfo
+    ...     )
+    >>> serialized_public.splitlines()[0]
+    '-----BEGIN PUBLIC KEY-----'
+
+This is the part that you would normally share with the rest of the world.
+
+
+Key loading
+~~~~~~~~~~~
+
+This extends the sample in the previous section, assuming that the variables
+``serialized_private`` and ``serialized_public`` contain the respective keys
+in PEM format.
+
+.. doctest::
+
+    >>> loaded_public_key = serialization.load_pem_public_key(
+    ...    serialized_public,
+    ...    backend=default_backend()
+    ...    )
+
+    >>> loaded_private_key = serialization.load_pem_private_key(
+    ...    serialized_private,
+    ...    password=b'testpassword',  # or password=None, if in plain text
+    ...    backend=default_backend()
+    ...    )
+
+
 .. _`FIPS 186-3`: http://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf
 .. _`FIPS 186-4`: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf
 .. _`800-56A`: http://csrc.nist.gov/publications/nistpubs/800-56A/SP800-56A_Revision1_Mar08-2007.pdf