Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Interfaces for SCTs, feedback wanted #3467

Merged
merged 14 commits into from
Mar 22, 2017
75 changes: 75 additions & 0 deletions docs/x509/certificate-transparency.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the acceptable time period something each log decides?


.. 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.
1 change: 1 addition & 0 deletions docs/x509/index.rst
Original file line number Diff line number Diff line change
@@ -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
2 changes: 2 additions & 0 deletions src/cryptography/x509/__init__.py
Original file line number Diff line number Diff line change
@@ -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",
46 changes: 46 additions & 0 deletions src/cryptography/x509/certificate_transparency.py
Original file line number Diff line number Diff line change
@@ -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.
"""