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
• type LogInfo
  • func NewLogInfo(log *loglist.Log, hc *http.Client) (*LogInfo, error)
  • func NewLogInfoOverDNS(log *loglist.Log) (*LogInfo, error)
  • func NewLogInfoOverDNSWrapper(log *loglist.Log, _ *http.Client) (*LogInfo, error)
  • func (li *LogInfo) LastSTH() *ct.SignedTreeHead
  • func (li *LogInfo) SetSTH(sth *ct.SignedTreeHead)
  • func (li *LogInfo) VerifyInclusion(ctx context.Context, leaf ct.MerkleTreeLeaf, timestamp uint64) (int64, error)
  • func (li *LogInfo) VerifyInclusionAt(ctx context.Context, leaf ct.MerkleTreeLeaf, timestamp, treeSize uint64, ...) (int64, error)
  • func (li *LogInfo) VerifyInclusionLatest(ctx context.Context, leaf ct.MerkleTreeLeaf, timestamp uint64) (int64, error)
  • func (li *LogInfo) VerifySCTSignature(sct ct.SignedCertificateTimestamp, leaf ct.MerkleTreeLeaf) error
• type LogInfoByHash
  • func LogInfoByKeyHash(ll *loglist.LogList, hc *http.Client) (LogInfoByHash, error)
  • func LogInfoByKeyHashOverDNS(ll *loglist.LogList, hc *http.Client) (LogInfoByHash, 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].

Types

type LogInfo

type LogInfo struct {
	Description string
	Client      client.CheckLogClient
	MMD         time.Duration
	Verifier    *ct.SignatureVerifier
	PublicKey   []byte
	// contains filtered or unexported fields
}

LogInfo holds the objects needed to perform per-log verification and validation of SCTs.

func NewLogInfo

func NewLogInfo(log *loglist.Log, hc *http.Client) (*LogInfo, error)

NewLogInfo builds a LogInfo object based on a log list entry.

func NewLogInfoOverDNS

func NewLogInfoOverDNS(log *loglist.Log) (*LogInfo, error)

NewLogInfoOverDNS builds a LogInfo object that accesses logs via DNS, based on a log list entry.

func NewLogInfoOverDNSWrapper

func NewLogInfoOverDNSWrapper(log *loglist.Log, _ *http.Client) (*LogInfo, error)

NewLogInfoOverDNSWrapper builds a LogInfo object that accesses logs via DNS, based on a log list entry. The inert http.Client argument allows this variant to be used interchangeably with NewLogInfo.

func (*LogInfo) LastSTH

func (li *LogInfo) LastSTH() *ct.SignedTreeHead

LastSTH returns the last STH known for the log.

func (*LogInfo) SetSTH

func (li *LogInfo) SetSTH(sth *ct.SignedTreeHead)

SetSTH sets the last STH known for the log.

func (*LogInfo) VerifyInclusion

func (li *LogInfo) VerifyInclusion(ctx context.Context, leaf ct.MerkleTreeLeaf, timestamp uint64) (int64, error)

VerifyInclusion checks that the given Merkle tree leaf, adjusted for the provided timestamp, is present in the current tree size of the log. On success, returns the index of the leaf in the log.

func (*LogInfo) VerifyInclusionAt

func (li *LogInfo) VerifyInclusionAt(ctx context.Context, leaf ct.MerkleTreeLeaf, timestamp, treeSize uint64, rootHash []byte) (int64, error)

VerifyInclusionAt checks that the given Merkle tree leaf, adjusted for the provided timestamp, is present in the given tree size & root hash of the log. On success, returns the index of the leaf in the log.

func (*LogInfo) VerifyInclusionLatest

func (li *LogInfo) VerifyInclusionLatest(ctx context.Context, leaf ct.MerkleTreeLeaf, timestamp uint64) (int64, error)

VerifyInclusionLatest checks that the given Merkle tree leaf, adjusted for the provided timestamp, is present in the latest known tree size of the log. If no tree size for the log is known, it will be queried. On success, returns the index of the leaf in the log.

func (*LogInfo) VerifySCTSignature

func (li *LogInfo) VerifySCTSignature(sct ct.SignedCertificateTimestamp, leaf ct.MerkleTreeLeaf) error

VerifySCTSignature checks the signature in the SCT matches the given leaf (adjusted for the timestamp in the SCT) and log.

type LogInfoByHash

type LogInfoByHash map[[sha256.Size]byte]*LogInfo

LogInfoByHash holds LogInfo objects index by the SHA-256 hash of the log's public key.

func LogInfoByKeyHash

func LogInfoByKeyHash(ll *loglist.LogList, hc *http.Client) (LogInfoByHash, error)

LogInfoByKeyHash builds a map of LogInfo objects indexed by their key hashes.

func LogInfoByKeyHashOverDNS

func LogInfoByKeyHashOverDNS(ll *loglist.LogList, hc *http.Client) (LogInfoByHash, error)

LogInfoByKeyHashOverDNS builds a map of LogInfo objects (for access over DNS) indexed by their key hashes.