ocsp

Documentation

Overview

Package ocsp parses OCSP responses as specified in RFC 2560. OCSP responses are signed messages attesting to the validity of a certificate for a small period of time. This is used to manage revocation for X.509 certificates.

Index

• Constants
• Variables
• func CreateRequest(cert, issuer *x509.Certificate, opts *RequestOptions) ([]byte, error)
• func CreateResponse(issuer, responderCert *x509.Certificate, template Response, priv crypto.Signer, ...) ([]byte, error)
• type ParseError
  • func (p ParseError) Error() string
• type Request
  • func ParseRequest(bytes []byte) (*Request, error)
  • func (req *Request) Marshal() ([]byte, error)
• type RequestOptions
• type Response
  • func ParseResponse(bytes []byte, issuer *x509.Certificate) (*Response, error)
  • func ParseResponseForCert(bytes []byte, cert, issuer *x509.Certificate) (*Response, error)
  • func (resp *Response) CheckSignatureFrom(issuer *x509.Certificate) error
• type ResponseError
  • func (r ResponseError) Error() string
• type ResponseStatus
  • func (r ResponseStatus) String() string

Constants

const (
	// Good means that the certificate is valid.
	Good = iota
	// Revoked means that the certificate has been deliberately revoked.
	Revoked
	// Unknown means that the OCSP responder doesn't know about the certificate.
	Unknown
	// ServerFailed is unused and was never used (see
	// https://go-review.googlesource.com/#/c/18944). ParseResponse will
	// return a ResponseError when an error response is parsed.
	ServerFailed
)

The status values that can be expressed in OCSP. See RFC 6960.

const (
	Unspecified          = 0
	KeyCompromise        = 1
	CACompromise         = 2
	AffiliationChanged   = 3
	Superseded           = 4
	CessationOfOperation = 5
	CertificateHold      = 6

	RemoveFromCRL      = 8
	PrivilegeWithdrawn = 9
	AACompromise       = 10
)

The enumerated reasons for revoking a certificate. See RFC 5280.

Variables

var (
	MalformedRequestErrorResponse = []byte{0x30, 0x03, 0x0A, 0x01, 0x01}
	InternalErrorErrorResponse    = []byte{0x30, 0x03, 0x0A, 0x01, 0x02}
	TryLaterErrorResponse         = []byte{0x30, 0x03, 0x0A, 0x01, 0x03}
	SigRequredErrorResponse       = []byte{0x30, 0x03, 0x0A, 0x01, 0x05}
	UnauthorizedErrorResponse     = []byte{0x30, 0x03, 0x0A, 0x01, 0x06}
)

These are pre-serialized error responses for the various non-success codes defined by OCSP. The Unauthorized code in particular can be used by an OCSP responder that supports only pre-signed responses as a response to requests for certificates with unknown status. See RFC 5019.

Functions

func CreateRequest

func CreateRequest(cert, issuer *x509.Certificate, opts *RequestOptions) ([]byte, error)

CreateRequest returns a DER-encoded, OCSP request for the status of cert. If opts is nil then sensible defaults are used.

func CreateResponse

func CreateResponse(issuer, responderCert *x509.Certificate, template Response, priv crypto.Signer, producedAt time.Time) ([]byte, error)

CreateResponse returns a DER-encoded OCSP response with the specified contents. The fields in the response are populated as follows:

The responder cert is used to populate the responder's name field, and the certificate itself is provided alongside the OCSP response signature.

The issuer cert is used to puplate the IssuerNameHash and IssuerKeyHash fields.

The template is used to populate the SerialNumber, Status, RevokedAt, RevocationReason, ThisUpdate, and NextUpdate fields.

If template.IssuerHash is not set, SHA1 will be used.

The ProducedAt date is rounded to the nearest minute from the given producedAt.

Types

type ParseError

type ParseError string

ParseError results from an invalid OCSP response.

func (ParseError) Error

func (p ParseError) Error() string

type Request

type Request struct {
	HashAlgorithm  crypto.Hash
	IssuerNameHash []byte
	IssuerKeyHash  []byte
	SerialNumber   *big.Int
}

Request represents an OCSP request. See RFC 6960.

func ParseRequest

func ParseRequest(bytes []byte) (*Request, error)

ParseRequest parses an OCSP request in DER form. It only supports requests for a single certificate. Signed requests are not supported. If a request includes a signature, it will result in a ParseError.

func (*Request) Marshal

func (req *Request) Marshal() ([]byte, error)

Marshal marshals the OCSP request to ASN.1 DER encoded form.

type RequestOptions

type RequestOptions struct {
	// Hash contains the hash function that should be used when
	// constructing the OCSP request. If zero, SHA-1 will be used.
	Hash crypto.Hash
}

RequestOptions contains options for constructing OCSP requests.

type Response

type Response struct {
	// Status is one of {Good, Revoked, Unknown}
	Status                                        int
	SerialNumber                                  *big.Int
	ProducedAt, ThisUpdate, NextUpdate, RevokedAt time.Time
	RevocationReason                              int
	Certificate                                   *x509.Certificate
	// TBSResponseData contains the raw bytes of the signed response. If
	// Certificate is nil then this can be used to verify Signature.
	TBSResponseData    []byte
	Signature          []byte
	SignatureAlgorithm x509.SignatureAlgorithm

	// IssuerHash is the hash used to compute the IssuerNameHash and IssuerKeyHash.
	// Valid values are crypto.SHA1, crypto.SHA256, crypto.SHA384, and crypto.SHA512.
	// If zero, the default is crypto.SHA1.
	IssuerHash crypto.Hash

	// RawResponderName optionally contains the DER-encoded subject of the
	// responder certificate. Exactly one of RawResponderName and
	// ResponderKeyHash is set.
	RawResponderName []byte
	// ResponderKeyHash optionally contains the SHA-1 hash of the
	// responder's public key. Exactly one of RawResponderName and
	// ResponderKeyHash is set.
	ResponderKeyHash []byte

	// Extensions contains raw X.509 extensions from the singleExtensions field
	// of the OCSP response. When parsing certificates, this can be used to
	// extract non-critical extensions that are not parsed by this package. When
	// marshaling OCSP responses, the Extensions field is ignored, see
	// ExtraExtensions.
	Extensions []pkix.Extension

	// ExtraExtensions contains extensions to be copied, raw, into any marshaled
	// OCSP response (in the singleExtensions field). Values override any
	// extensions that would otherwise be produced based on the other fields. The
	// ExtraExtensions field is not populated when parsing certificates, see
	// Extensions.
	ExtraExtensions []pkix.Extension
}

Response represents an OCSP response containing a single SingleResponse. See RFC 6960.

func ParseResponse

func ParseResponse(bytes []byte, issuer *x509.Certificate) (*Response, error)

ParseResponse parses an OCSP response in DER form. The response must contain only one certificate status. To parse the status of a specific certificate from a response which may contain multiple statuses, use ParseResponseForCert instead.

If the response contains an embedded certificate, then that certificate will be used to verify the response signature. If the response contains an embedded certificate and issuer is not nil, then issuer will be used to verify the signature on the embedded certificate.

If the response does not contain an embedded certificate and issuer is not nil, then issuer will be used to verify the response signature.

Invalid responses and parse failures will result in a ParseError. Error responses will result in a ResponseError.

func ParseResponseForCert

func ParseResponseForCert(bytes []byte, cert, issuer *x509.Certificate) (*Response, error)

ParseResponseForCert acts identically to ParseResponse, except it supports parsing responses that contain multiple statuses. If the response contains multiple statuses and cert is not nil, then ParseResponseForCert will return the first status which contains a matching serial, otherwise it will return an error. If cert is nil, then the first status in the response will be returned.

func (*Response) CheckSignatureFrom

func (resp *Response) CheckSignatureFrom(issuer *x509.Certificate) error

CheckSignatureFrom checks that the signature in resp is a valid signature from issuer. This should only be used if resp.Certificate is nil. Otherwise, the OCSP response contained an intermediate certificate that created the signature. That signature is checked by ParseResponse and only resp.Certificate remains to be validated.

type ResponseError

type ResponseError struct {
	Status ResponseStatus
}

ResponseError is an error that may be returned by ParseResponse to indicate that the response itself is an error, not just that it's indicating that a certificate is revoked, unknown, etc.

func (ResponseError) Error

func (r ResponseError) Error() string

type ResponseStatus

type ResponseStatus int

ResponseStatus contains the result of an OCSP request. See https://tools.ietf.org/html/rfc6960#section-2.3

const (
	Success       ResponseStatus = 0
	Malformed     ResponseStatus = 1
	InternalError ResponseStatus = 2
	TryLater      ResponseStatus = 3
	// Status code four is unused in OCSP. See
	// https://tools.ietf.org/html/rfc6960#section-4.2.1
	SignatureRequired ResponseStatus = 5
	Unauthorized      ResponseStatus = 6
)

func (ResponseStatus) String

func (r ResponseStatus) String() string