ocsp

Documentation

Overview

Package ocsp provides middleware for validating client certificates using OCSP (Online Certificate Status Protocol) RFC 6960.

The OCSP middleware checks the revocation status of client certificates by sending OCSP requests to a specified OCSP responder. It ensures that only valid and non-revoked certificates are allowed to access protected routes.

Usage

import (
	"crypto/x509"
	"github.com/gofiber/fiber/v2"
	"github.com/H0llyW00dzZ/ocsp-fiber/ocsp"
)

func main() {
	app := fiber.New()

	ocspMiddleware := ocsp.New(ocsp.Config{
		Issuer: issuerCert,
		ResponderFunc: func(cert *x509.Certificate) string {
			// Determine the OCSP responder URL based on the client certificate
			if cert.Issuer.CommonName == "Example CA" {
				return "http://example.com/ocsp"
			} else if cert.Issuer.CommonName == "Another CA" {
				return "http://another-ca.com/ocsp"
			}
			// Default responder URL
			return "http://default-responder.com/ocsp"
		},
	})

	app.Use(ocspMiddleware)

	// Define your routes and start the server
	// ...
}

Configuration

The OCSP middleware is configured using the ocsp.Config struct. The important fields are:

• Issuer: The certificate of the issuing CA. It is used to validate the client certificates against the issuer's public key.
• ResponderFunc: A function that takes a client certificate and returns the URL of the OCSP responder. It allows for dynamic selection of the OCSP responder based on the client certificate.
• ResponseHandler: A function that handles the response when an error occurs. If not provided, a default JSON response handler will be used.

Revocation Reasons

The OCSP middleware defines constants for various revocation reasons. These constants provide human-readable descriptions for the revocation reasons returned by the OCSP responder.

• RevocationReasonUnspecified: Unspecified revocation reason.
• RevocationReasonKeyCompromise: The key has been compromised.
• RevocationReasonCACompromise: The CA has been compromised.
• RevocationReasonAffiliationChanged: The affiliation has changed.
• RevocationReasonSuperseded: The certificate has been superseded.
• RevocationReasonCessationOfOperation: Cessation of operation.
• RevocationReasonCertificateHold: The certificate is on hold.
• RevocationReasonRemoveFromCRL: Removed from the CRL.
• RevocationReasonPrivilegeWithdrawn: The privilege has been withdrawn.
• RevocationReasonAACompromise: The AA has been compromised.
• RevocationReasonUnknown: Unknown revocation reason.

OCSP Response

The ocsp.Response struct represents an OCSP response. It embeds the ocsp.Response struct from the golang.org/x/crypto/ocsp package and provides additional functionality. The Response struct allows access to the fields and methods of the embedded ocsp.Response struct, such as Status, SerialNumber, RevocationReason, RevokedAt, ThisUpdate, NextUpdate, and Extensions.

The Response struct is used to create a new instance of the OCSP response after parsing the response received from the OCSP responder. It provides a structured and convenient way to work with the OCSP response data.

Index

• Constants
• func New(config Config) fiber.Handler
• type Config
• type RequestOptions
• type Response
• type ResponseHandler

Constants

const (
	// MIMEApplicationOCSPRequest is the MIME type for OCSP requests.
	// RFC: https://datatracker.ietf.org/doc/html/rfc6960#page-40
	MIMEApplicationOCSPRequest = "application/ocsp-request"

	// MIMEApplicationOCSPResponse is the MIME type for OCSP responses.
	// RFC: https://datatracker.ietf.org/doc/html/rfc6960#page-40
	MIMEApplicationOCSPResponse = "application/ocsp-response"
)

const (
	// RevocationReasonUnspecified represents an unspecified revocation reason.
	RevocationReasonUnspecified = "Unspecified"

	// RevocationReasonKeyCompromise represents a revocation reason indicating that the key has been compromised.
	RevocationReasonKeyCompromise = "Key Compromise"

	// RevocationReasonCACompromise represents a revocation reason indicating that the CA has been compromised.
	RevocationReasonCACompromise = "CA Compromise"

	// RevocationReasonAffiliationChanged represents a revocation reason indicating that the affiliation has changed.
	RevocationReasonAffiliationChanged = "Affiliation Changed"

	// RevocationReasonSuperseded represents a revocation reason indicating that the certificate has been superseded.
	RevocationReasonSuperseded = "Superseded"

	// RevocationReasonCessationOfOperation represents a revocation reason indicating the cessation of operation.
	RevocationReasonCessationOfOperation = "Cessation Of Operation"

	// RevocationReasonCertificateHold represents a revocation reason indicating that the certificate is on hold.
	RevocationReasonCertificateHold = "Certificate Hold"

	// RevocationReasonRemoveFromCRL represents a revocation reason indicating removal from the CRL.
	RevocationReasonRemoveFromCRL = "Remove From CRL"

	// RevocationReasonPrivilegeWithdrawn represents a revocation reason indicating that the privilege has been withdrawn.
	RevocationReasonPrivilegeWithdrawn = "Privilege Withdrawn"

	// RevocationReasonAACompromise represents a revocation reason indicating that the AA has been compromised.
	RevocationReasonAACompromise = "AA Compromise"

	// RevocationReasonUnknown represents an unknown revocation reason.
	RevocationReasonUnknown = "Unknown"
)

Functions

func New

func New(config Config) fiber.Handler

New creates a new instance of the OCSP middleware with the provided configuration.

Types

type Config

type Config struct {
	// Issuer is the certificate of the issuing CA.
	// It is used to validate the client certificates against the issuer's public key.
	// The Issuer field must be set to a valid [*x509.Certificate].
	Issuer *x509.Certificate

	// Responder is the URL of the OCSP responder.
	// It specifies the endpoint where the OCSP requests will be sent to check the Revocation status of client certificates.
	// The Responder field must be set to a valid URL string.
	//
	// Deprecated: Use ResponderFunc Instead.
	Responder string

	// ResponderFunc is a function that takes a client certificate and returns the OCSP responder URL.
	// It allows dynamic selection of the OCSP responder based on the client certificate.
	// The ResponderFunc field must be set to a valid function.
	ResponderFunc func(*x509.Certificate) string

	// ResponseHandler is a function that handles the response when an error occurs.
	// If not provided, a default JSON response handler will be used.
	ResponseHandler ResponseHandler

	// RequestOptions specifies the options for creating OCSP requests.
	// If not provided, default options will be used.
	RequestOptions RequestOptions
}

Config represents the configuration for the OCSP middleware.

type RequestOptions

type RequestOptions struct {
	Hash crypto.Hash
}

RequestOptions represents the options for creating an OCSP request.

type Response

type Response struct {
	*ocsp.Response
}

Response represents an OCSP response. It embeds the ocsp.Response struct and provides additional functionality.

type ResponseHandler

type ResponseHandler func(c *fiber.Ctx, statusCode int, message string) error

ResponseHandler is a function that handles the response when an error occurs.