ctutil

Documentation

Overview

Package ctutil contains utilities for Certificate Transparency.

Index

• func ContainsSCT(cert *x509.Certificate, sct *ct.SignedCertificateTimestamp) (bool, error)
• func LeafHash(chain []*x509.Certificate, sct *ct.SignedCertificateTimestamp, embedded bool) ([sha256.Size]byte, error)
• func LeafHashB64(chain []*x509.Certificate, sct *ct.SignedCertificateTimestamp, embedded bool) (string, error)
• func VerifySCT(pubKey crypto.PublicKey, chain []*x509.Certificate, ...) error
• func VerifySCTWithVerifier(sv *ct.SignatureVerifier, chain []*x509.Certificate, ...) error

Functions

func ContainsSCT

func ContainsSCT(cert *x509.Certificate, sct *ct.SignedCertificateTimestamp) (bool, error)

ContainsSCT checks to see whether the given SCT is embedded within the given certificate.

func LeafHash

func LeafHash(chain []*x509.Certificate, sct *ct.SignedCertificateTimestamp, embedded bool) ([sha256.Size]byte, error)

LeafHash calculates the leaf hash of the certificate or precertificate at chain[0] that sct was issued for.

sct is required because the SCT timestamp is used to calculate the leaf hash. Leaf hashes are unique to (pre)certificate-SCT pairs.

This function can be used with three different types of leaf certificate:

• X.509 Certificate: If using this function to calculate the leaf hash for a normal X.509 certificate then it is enough to just provide the end entity certificate in chain. This case assumes that the SCT being provided is not embedded within the leaf certificate provided, i.e. the certificate is what was submitted to the Certificate Transparency Log in order to obtain the SCT. For this case, set embedded to false.
• Precertificate: If using this function to calculate the leaf hash for a precertificate then the issuing certificate must also be provided in chain. The precertificate should be at chain[0], and its issuer at chain[1]. For this case, set embedded to false.
• X.509 Certificate containing the SCT embedded within it: If using this function to calculate the leaf hash for a certificate where the SCT provided is embedded within the certificate you are providing at chain[0], set embedded to true. LeafHash will calculate the leaf hash by building the corresponding precertificate. LeafHash will return an error if the provided SCT cannot be found embedded within chain[0]. As with the precertificate case, the issuing certificate must also be provided in chain. The certificate containing the embedded SCT should be at chain[0], and its issuer at chain[1].

Note: LeafHash doesn't check that the provided SCT verifies for the given chain. It simply calculates what the leaf hash would be for the given (pre)certificate-SCT pair.

func LeafHashB64

func LeafHashB64(chain []*x509.Certificate, sct *ct.SignedCertificateTimestamp, embedded bool) (string, error)

LeafHashB64 does as LeafHash does, but returns the leaf hash base64-encoded. The base64-encoded leaf hash returned by B64LeafHash can be used with the get-proof-by-hash API endpoint of Certificate Transparency Logs.

func VerifySCT

func VerifySCT(pubKey crypto.PublicKey, chain []*x509.Certificate, sct *ct.SignedCertificateTimestamp, embedded bool) error

VerifySCT takes the public key of a Certificate Transparency Log, a certificate chain, and an SCT and verifies whether the SCT is a valid SCT for the certificate at chain[0], signed by the Log that the public key belongs to. If the SCT does not verify, an error will be returned.

This function can be used with three different types of leaf certificate:

• X.509 Certificate: If using this function to verify an SCT for a normal X.509 certificate then it is enough to just provide the end entity certificate in chain. This case assumes that the SCT being provided is not embedded within the leaf certificate provided, i.e. the certificate is what was submitted to the Certificate Transparency Log in order to obtain the SCT. For this case, set embedded to false.
• Precertificate: If using this function to verify an SCT for a precertificate then the issuing certificate must also be provided in chain. The precertificate should be at chain[0], and its issuer at chain[1]. For this case, set embedded to false.
• X.509 Certificate containing the SCT embedded within it: If the SCT you wish to verify is embedded within the certificate you are providing at chain[0], set embedded to true. VerifySCT will verify the provided SCT by building the corresponding precertificate. VerifySCT will return an error if the provided SCT cannot be found embedded within chain[0]. As with the precertificate case, the issuing certificate must also be provided in chain. The certificate containing the embedded SCT should be at chain[0], and its issuer at chain[1].

func VerifySCTWithVerifier

func VerifySCTWithVerifier(sv *ct.SignatureVerifier, chain []*x509.Certificate, sct *ct.SignedCertificateTimestamp, embedded bool) error

VerifySCTWithVerifier takes a ct.SignatureVerifier, a certificate chain, and an SCT and verifies whether the SCT is a valid SCT for the certificate at chain[0], signed by the Log whose public key was used to set up the ct.SignatureVerifier. If the SCT does not verify, an error will be returned.

This function can be used with three different types of leaf certificate:

• X.509 Certificate: If using this function to verify an SCT for a normal X.509 certificate then it is enough to just provide the end entity certificate in chain. This case assumes that the SCT being provided is not embedded within the leaf certificate provided, i.e. the certificate is what was submitted to the Certificate Transparency Log in order to obtain the SCT. For this case, set embedded to false.
• Precertificate: If using this function to verify an SCT for a precertificate then the issuing certificate must also be provided in chain. The precertificate should be at chain[0], and its issuer at chain[1]. For this case, set embedded to false.
• X.509 Certificate containing the SCT embedded within it: If the SCT you wish to verify is embedded within the certificate you are providing at chain[0], set embedded to true. VerifySCT will verify the provided SCT by building the corresponding precertificate. VerifySCT will return an error if the provided SCT cannot be found embedded within chain[0]. As with the precertificate case, the issuing certificate must also be provided in chain. The certificate containing the embedded SCT should be at chain[0], and its issuer at chain[1].