ocsputil

README

software.sslmate.com/src/ocsputil

software.sslmate.com/src/ocsputil is a Go package that provides convenience functions for OCSP checking. It's mostly a wrapper around golang.org/x/crypto/ocsp.

The ocsputil.Evaluate function evaluates the reliability of a certificate's OCSP responder, and is used by OCSP Watch.

View GoDocs

evalocsp

evalocsp is a command line tool that evaluates the reliability of a certificate's OCSP responder using ocsputil.Evaluate.

Install it with: go install software.sslmate.com/src/ocsputil/cmd/evalocsp@latest

Input (on stdin): Two PEM-encoded certificates - the certificate whose OCSP responder should be evaluated, followed by its issuer. The first certificate may be a precertificate, but if it's signed by a dedicated precert signing CA, then the second certificate must be the issuer of the final certificate rather than the precertificate. Extra certificates and non-certificate data are ignored.

Output (on stdout): A JSON object with the following fields:

Field Name	Description
error	null if the OCSP check was successful, or the error, as a string.
responder_url	The URL of the OCSP responder.
request_bytes	The bytes of the OCSP request, as a base64-encoded string.
response_bytes	The bytes of the OCSP response, as a base64-encoded string.
response_time	The length of time which the OCSP responder took to respond, formatted as a time.Duration string.

If error is null, then the other fields are non-null. If error is non-null, then any of the other fields may be null depending on the nature of the error.

Go 1.18 Bug

Go 1.18 accidentally banned SHA-1-signed OCSP responses, which can still be found in the WebPKI. To avoid this bug, use Go 1.18.1 or higher.

Documentation

Index

• Constants
• Variables
• func CheckCert(ctx context.Context, cert *x509.Certificate, issuerCert *x509.Certificate, ...) (revoked bool, revocationTime time.Time, err error)
• func CheckRawCert(ctx context.Context, certData []byte, issuerSubject []byte, ...) (revoked bool, revocationTime time.Time, err error)
• func CheckResponse(cert *x509.Certificate, issuerCert *x509.Certificate, responseBytes []byte) (revoked bool, revocationTime time.Time, err error)
• func CreateRequest(cert *x509.Certificate, issuerCert *x509.Certificate) (serverURL string, requestBytes []byte, err error)
• func ParseCertificate(certData []byte, issuerSubject []byte, issuerPubkeyBytes []byte) (cert *x509.Certificate, issuerCert *x509.Certificate, err error)
• func Query(ctx context.Context, serverURL string, requestBytes []byte, config *Config) ([]byte, error)
• type Config
• type Evaluation
  • func Evaluate(ctx context.Context, certData []byte, issuerSubject []byte, ...) (eval Evaluation)

Constants

const QueryTimeout = 10 * time.Second

The maximum amount of time to wait for an OCSP response, as specified by Section 4.10.2 of the Baseline Requirements: "The CA SHALL operate and maintain its CRL and OCSP capability with resources sufficient to provide a response time of ten seconds or less under normal operating conditions."

Variables

var (
	// ErrUnknown is returned when the certificate status is not good or revoked
	ErrUnknown = errors.New("OCSP responder does not know this certificate")

	// ErrNoResponder is returned when the certificte does not contain an HTTP OCSP responder URL
	ErrNoResponder = errors.New("Certificate does not contain an HTTP OCSP responder URL")

	// ErrNoCheck is returned when the certificate is an OCSP Responder certificate with the OCSP No Check extension
	ErrNoCheck = errors.New("Certificate is an OCSP responder certificate with the OCSP No Check extension")
)

Functions

func CheckCert

func CheckCert(ctx context.Context, cert *x509.Certificate, issuerCert *x509.Certificate, config *Config) (revoked bool, revocationTime time.Time, err error)

Given a certificate and its issuer, perform an OCSP check for the certificate and return if and when the certificate was revoked.

cert can be a precertificate, but issuerCert must be the final certificate's issuer, not the precertificate's issuer.

If config is nil, a zero-value Config is used, which provides sensible defaults.

This function is a wrapper around CreateRequest, Query, and CheckResponse. See those functions' documentation for details about the behavior.

func CheckRawCert

func CheckRawCert(ctx context.Context, certData []byte, issuerSubject []byte, issuerPubkeyBytes []byte, config *Config) (revoked bool, revocationTime time.Time, err error)

Given a certificate, its issuer's subject, and its issuer's public key, perform an OCSP check for the certificate and return if and when the certificate was revoked.

cert can be a precertificate, but issuerSubject and issuerPubkeyBytes must be from the final certificate's issuer, not the precertificate's issuer.

If config is nil, a zero-value Config is used, which provides sensible defaults.

This function is a wrapper around ParseCertificate, CreateRequest, Query, and CheckResponse. See those functions' documentation for details about the behavior.

func CheckResponse

func CheckResponse(cert *x509.Certificate, issuerCert *x509.Certificate, responseBytes []byte) (revoked bool, revocationTime time.Time, err error)

Given a certificate, its issuer, and an OCSP response, parse the response and return if and when it was revoked.

cert can be a precertificate, but issuerCert must be the final certificate's issuer, not the precertificate's issuer.

Returns ErrUnknown if the response is neither good nor revoked, or an error from golang.org/x/crypto/ocsp.ParseResponseForCert

func CreateRequest

func CreateRequest(cert *x509.Certificate, issuerCert *x509.Certificate) (serverURL string, requestBytes []byte, err error)

Given a certificate and its issuer, return the "http://" OCSP server URL and an OCSP request suitable for passing to Query.

cert can be a precertificate, but issuerCert must be the final certificate's issuer, not the precertificate's issuer.

Returns ErrNoResponder if the certificate lacks an "http://" OCSP responder, ErrNoCheck if the certificate is an OCSP Responder certificate with the OCSP No Check extension, or an error from golang.org/x/crypto/ocsp.CreateRequest

func ParseCertificate

func ParseCertificate(certData []byte, issuerSubject []byte, issuerPubkeyBytes []byte) (cert *x509.Certificate, issuerCert *x509.Certificate, err error)

Given a certificate, its issuer's subject, and its issuer's public key, return the parsed certificate and an issuer certificate suitable for passing to CreateRequest and CheckResponse. The returned issuerCert is not a fully-populated certificate and is only suitable for use with CreateRequest and CheckResponse.

cert can be a precertificate, but issuerSubject and issuerPubkeyBytes must be from the final certificate's issuer, not the precertificate's issuer.

Returns an error if any of the arguments can't be parsed by the crypto/x509 package.

func Query

func Query(ctx context.Context, serverURL string, requestBytes []byte, config *Config) ([]byte, error)

Given an OCSP server URL and an OCSP request (which can be created with CreateRequest), send the OCSP query using a POST request and return the response, which is suitable for passing to CheckResponse. The timeout for the query is defined by QueryTimeout.

If config is nil, a zero-value Config is used, which provides sensible defaults.

Returns errors for the following conditions:

• There's a problem parsing serverURL
• There's an error from the HTTP client
• There's an error reading the response
• The HTTP response code is not 200
• The Content-Type of the response is not "application/ocsp-response"

Types

type Config

type Config struct {
	// The HTTP client for making OCSP requests. If nil, then [http.DefaultClient] is used.
	HTTPClient *http.Client

	// The HTTP User-Agent string for OCSP requests. If empty, then no User-Agent is sent.
	UserAgent string
}

Contains configuration for the functions in this package. The zero value provides sensible defaults.

type Evaluation

type Evaluation struct {
	ResponderURL  *string
	RequestBytes  []byte
	ResponseBytes []byte
	ResponseTime  time.Duration
	Err           error
}

Represents the result of Evaluate. If Err is nil, then the other fields are non-nil. If Err is non-nil, then any of the other fields may be nil, depending on the nature of the error.

func Evaluate

func Evaluate(ctx context.Context, certData []byte, issuerSubject []byte, issuerPubkey []byte, config *Config) (eval Evaluation)

Given a certificate, its issuer's subject, and its issuer's public key, evaluate the certificate's OCSP responder.

cert can be a precertificate, but issuerSubject and issuerPubkey must be from the final certificate's issuer, not the precertificate's issuer.

This function is a wrapper around ParseCertificate, CreateRequest, Query, and CheckResponse. See the documentation for those functions for details about the behavior.

If config is nil, a zero-value Config is used, which provides sensible defaults.

Evaluate is used by OCSP Watch.