From bca951ebd869cb6c911cd6bba52b2d798366b409 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 22 Mar 2017 09:17:20 -0400 Subject: [PATCH] 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 | 79 +++++++++++++++++++ docs/x509/index.rst | 1 + src/cryptography/x509/__init__.py | 2 + .../x509/certificate_transparency.py | 46 +++++++++++ 4 files changed, 128 insertions(+) create mode 100644 docs/x509/certificate-transparency.rst create mode 100644 src/cryptography/x509/certificate_transparency.py diff --git a/docs/x509/certificate-transparency.rst b/docs/x509/certificate-transparency.rst new file mode 100644 index 000000000000..0d344d2bc50a --- /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 2e3aa74c0572..ec47fe627aff 100644 --- a/docs/x509/index.rst +++ b/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 diff --git a/src/cryptography/x509/__init__.py b/src/cryptography/x509/__init__.py index 51914e1e3817..38ae0f07783a 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 000000000000..d00fe8126925 --- /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. + """