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
diff --git a/docs/x509/certificate-transparency.rst b/docs/x509/certificate-transparency.rst
new file mode 100644
index 0000000..0d344d2
--- /dev/null
+++ b/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/
diff --git a/docs/x509/index.rst b/docs/x509/index.rst
index 2e3aa74..ec47fe6 100644
--- a/docs/x509/index.rst
+++ b/docs/x509/index.rst
@@ -9,6 +9,7 @@
:maxdepth: 2
tutorial
+ certificate-transparency
reference
.. _`public key infrastructure`: https://en.wikipedia.org/wiki/Public_key_infrastructure
diff --git a/src/cryptography/x509/__init__.py b/src/cryptography/x509/__init__.py
index 51914e1..38ae0f0 100644
--- a/src/cryptography/x509/__init__.py
+++ b/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",
diff --git a/src/cryptography/x509/certificate_transparency.py b/src/cryptography/x509/certificate_transparency.py
new file mode 100644
index 0000000..d00fe81
--- /dev/null
+++ b/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.
+ """