Interfaces for SCTs, feedback wanted (#3467)

* Stub API for SCTs, feedback wanted

* grr, flake8

* port this to being an ABC

* finish up the __init__

* Two necessary enums

* Roll this back

* Wrote some docs

* spell words correctly

* linky

* more details

* use the words UTC

* coverage

* Define MMD for the kids at some

* linky linky

docs/x509/certificate-transparency.rst

@@ -0,0 +1,79 @@
+Certificate Transparency
+========================
+
+.. currentmodule:: cryptography.x509.certificate_transparency
+
+`Certificate Transparency`_ is a set of protocols specified in :rfc:`6962`
+which allow X.509 certificates to be sent to append-only logs and have small
+cryptographic proofs that a certificate has been publicly logged. This allows
+for external auditing of the certificates that a certificate authority has
+issued.
+
+.. class:: SignedCertificateTimestamp
+
+    .. versionadded:: 1.9
+
+    SignedCertificateTimestamps (SCTs) are small cryptographically signed
+    assertions that the specified certificate has been submitted to a
+    Certificate Transparency Log, and that it will be part of the public log
+    within some time period, this is called the "maximum merge delay" (MMD) and
+    each log specifies its own.
+
+    .. attribute:: version
+
+        :type: :class:`~cryptography.x509.certificate_transparency.Version`
+
+        The SCT version as an enumeration. Currently only one version has been
+        specified.
+
+    .. attribute:: log_id
+
+        :type: bytes
+
+        An opaque identifier, indicating which log this SCT is from. This is
+        the SHA256 hash of the log's public key.
+
+    .. attribute:: timestamp
+
+        :type: :class:`datetime.datetime`
+
+        A naïve datetime representing the time in UTC at which the log asserts
+        the certificate had been submitted to it.
+
+    .. attribute:: entry_type
+
+        :type:
+            :class:`~cryptography.x509.certificate_transparency.LogEntryType`
+
+        The type of submission to the log that this SCT is for. Log submissions
+        can either be certificates themselves or "pre-certificates" which
+        indicate a binding-intent to issue a certificate for the same data,
+        with SCTs embedded in it.
+
+
+.. class:: Version
+
+    .. versionadded:: 1.9
+
+    An enumeration for SignedCertificateTimestamp versions.
+
+    .. attribute:: v1
+
+        For version 1 SignedCertificateTimestamps.
+
+.. class:: LogEntryType
+
+    .. versionadded:: 1.9
+
+    An enumeration for SignedCertificateTimestamp log entry types.
+
+    .. attribute:: X509_CERTIFICATE
+
+        For SCTs corresponding to X.509 certificates.
+
+    .. attribute:: PRE_CERTIFICATE
+
+        For SCTs corresponding to pre-certificates.
+
+
+.. _`Certificate Transparency`: https://www.certificate-transparency.org/

docs/x509/index.rst

@@ -9,6 +9,7 @@ certificates are commonly used in protocols like `TLS`_.
     :maxdepth: 2
 
     tutorial
+    certificate-transparency
     reference
 
 .. _`public key infrastructure`: https://en.wikipedia.org/wiki/Public_key_infrastructure

src/cryptography/x509/__init__.py

@@ -4,6 +4,7 @@
 
 from __future__ import absolute_import, division, print_function
 
+from cryptography.x509 import certificate_transparency
 from cryptography.x509.base import (
     Certificate, CertificateBuilder, CertificateRevocationList,
     CertificateRevocationListBuilder,
@@ -110,6 +111,7 @@
 
 
 __all__ = [
+    "certificate_transparency",
     "load_pem_x509_certificate",
     "load_der_x509_certificate",
     "load_pem_x509_csr",

src/cryptography/x509/certificate_transparency.py

@@ -0,0 +1,46 @@
+# This file is dual licensed under the terms of the Apache License, Version
+# 2.0, and the BSD License. See the LICENSE file in the root of this repository
+# for complete details.
+
+from __future__ import absolute_import, division, print_function
+
+import abc
+from enum import Enum
+
+import six
+
+
+class LogEntryType(Enum):
+    X509_CERTIFICATE = 0
+    PRE_CERTIFICATE = 1
+
+
+class Version(Enum):
+    v1 = 0
+
+
+@six.add_metaclass(abc.ABCMeta)
+class SignedCertificateTimestamp(object):
+    @abc.abstractproperty
+    def version(self):
+        """
+        Returns the SCT version.
+        """
+
+    @abc.abstractproperty
+    def log_id(self):
+        """
+        Returns an identifier indicating which log this SCT is for.
+        """
+
+    @abc.abstractproperty
+    def timestamp(self):
+        """
+        Returns the timestamp for this SCT.
+        """
+
+    @abc.abstractproperty
+    def entry_type(self):
+        """
+        Returns whether this is an SCT for a certificate or pre-certificate.
+        """