crlutil

README

software.sslmate.com/src/crlutil

crlutil is a Go package for downloading, parsing, and validating CRLs. It is used by CRL Watch.

View GoDocs

checkcrl

checkcrl is a command line tool for evaluating a single CRL or a set of partitioned CRLs using the same logic as CRL Watch.

Note that checkcrl is NOT a linter and does not do comprehensive checks for standards compliance. It only does basic sanity checks to ensure that a CA's CRL disclosure is valid and usable. The best time to run checkcrl is when updating a CCADB disclosure, to confirm that the information you're about to disclose is correct; for checking a CRL at signing time, use a linter.

Installation

Install the checkcrl command line tool using Go 1.21 or higher:

go install software.sslmate.com/src/crlutil/cmd/checkcrl@latest

Scenario 1: Check a CRL stored in a file

checkcrl -ca ca.pem -url http://example.com/ca.crl -file downloaded.crl

Parameters:

• -ca: Path to the PEM-encoded CA certificate that issued the CRL (required)
• -url: URL where the CRL will be published (this URL is not downloaded, but is used for validating the CRL) (this URL should be byte-for-byte equal to the URL disclosed for the CA in the CCADB)
• -file: Path to the local CRL file to validate

Scenario 2: Check a CRL at a URL

checkcrl -ca ca.pem -url http://example.com/ca.crl

Parameters:

• -ca: Path to the PEM-encoded CA certificate that issued the CRL (required)
• -url: URL of the CRL to download and validate (this URL should be byte-for-byte equal to the URL disclosed for the CA in the CCADB)

Scenario 3: Check a JSON Array of Partitioned CRLs

checkcrl -ca ca.pem -json crls.json

Parameters:

• -ca: Path to the PEM-encoded CA certificate that issued the CRLs (required)
• -json: Path to a JSON file containing an array of CRL URLs to download and validate (the file contents should be byte-for-byte equal to the "JSON Array of Partitioned CRLs" disclosed for the CA in the CCADB)

Output

If downloading, parsing, and validating the CRL(s) is successful, checkcrl exits with status 0 and produces no output.

Otherwise, an error is printed to stderr and checkcrl exits with a non-zero status.

Documentation

Overview

Package crlutil provides functionality for parsing and validating CRLs.

Index

• Constants
• func CheckJSON(ctx context.Context, config *DownloadConfig, ca *x509.Certificate, ...) error
• type DownloadConfig
• type RevocationList
  • func DownloadCRL(ctx context.Context, config *DownloadConfig, ca *x509.Certificate, url string) (*RevocationList, error)
  • func ParseRevocationList(der []byte, ca *x509.Certificate, uri string) (*RevocationList, error)
• type RevokedCertificate

Constants

const ContentType = "application/pkix-crl"

The Content-Type of CRLs, per RFC 5280

Functions

func CheckJSON

func CheckJSON(ctx context.Context, config *DownloadConfig, ca *x509.Certificate, jsonBytes []byte) error

CheckJSON parses a "JSON Array of Partitioned CRLs" (in the format expected by the CCADB) and attempts to download and validate each one using DownloadCRL.

Types

type DownloadConfig

type DownloadConfig struct {
	HTTPClient *http.Client
	UserAgent  string
}

DownloadConfig specifies the configuration for downloading CRLs. The zero value provides sensible defaults.

type RevocationList

type RevocationList struct {
	PublishedAt  time.Time
	Certificates []RevokedCertificate
	NumBytes     int
}

RevocationList represents a parsed Certificate Revocation List.

func DownloadCRL

func DownloadCRL(ctx context.Context, config *DownloadConfig, ca *x509.Certificate, url string) (*RevocationList, error)

DownloadCRL downloads a CRL from the specified URL and parses and validates it with [ParseCRL].

func ParseRevocationList

func ParseRevocationList(der []byte, ca *x509.Certificate, uri string) (*RevocationList, error)

ParseRevocationList parses a DER-encoded CRL and validates it. If ca is not nil, verifies the CRL signature and issuer match the CA certificate. If uri is not empty and the CRL contains an Issuing Distribution Point extension, verifies the URI is listed in the extension. Returns an error if the fails validation.

type RevokedCertificate

type RevokedCertificate struct {
	SerialNumber   *big.Int
	RevocationTime time.Time
	Reason         int
}

RevokedCertificate represents a certificate that has been revoked.