API - CRL Management

This section details the public API endpoints for managing and distributing Certificate Revocation Lists (CRLs). CRLs are a critical component of a Public Key Infrastructure (PKI) for communicating the revocation status of certificates. These endpoints are designed for public consumption by clients and relying parties to verify certificate validity.

Key Functionalities

Get Certificate Revocation List (CRL)

  • Endpoint: GET /api/v1/crl/{ca}
  • Description: Retrieves the Certificate Revocation List (CRL) for a specified Certificate Authority (CA).
  • Public Access: This endpoint is public and does not require any authentication, which is standard for CRL distribution.
  • Parameters:
    • ca (path parameter): The ID or identifier of the Certificate Authority.
    • refresh (query parameter, boolean, optional): If true, forces a regeneration of the CRL, bypassing the cache.
  • Caching: Implements a caching mechanism (default 30 minutes) to efficiently serve CRLs. The CRL is regenerated if the cache is missed, a refresh is forced, or new revocations have occurred since the last generation.
  • Headers: Sets standard HTTP headers for Content-Type (application/pkix-crl), Content-Disposition (for download filename), Cache-Control, and custom X-CRL-* headers providing metadata like generation time, next update, CA name, and type.
  • CORS Support: Includes Access-Control-Allow-Origin: * headers to allow cross-origin requests.
  • Error Handling: Returns 404 Not Found if the CA is not active and 500 Internal Server Error for generation failures.

Get CRL Information/Metadata

  • Endpoint: GET /api/v1/crl/{ca}/info
  • Description: Provides metadata and information about a CA's CRL without downloading the actual CRL file. This is useful for clients to check CRL status and properties.
  • Parameters:
    • ca (path parameter): The ID or identifier of the Certificate Authority.
  • Response: Returns a JSON object containing:
    • ca_id, ca_name, ca_type.
    • crl_number: The current CRL number.
    • this_update, next_update: Timestamps for the current and next scheduled CRL updates.
    • revoked_certificates_count: Number of certificates listed in the CRL.
    • crl_url: The URL to download the full CRL.
    • validity_minutes, cache_minutes: Configured validity and cache durations.
    • distribution_points: URLs for primary and alternative (force refresh) distribution points.
    • formats: URLs for different CRL formats (DER, PEM).

List All Available CRLs

  • Endpoint: GET /api/v1/crls
  • Description: Retrieves a list of all active Certificate Authorities, along with summary information about their respective CRLs.
  • Public Access: This endpoint is public and does not require authentication.
  • Response: Returns a JSON array, where each element provides ca_id, ca_name, ca_type, crl_number, crl_url, last_update, and revoked_count.

CRL Service Health Check

  • Endpoint: GET /api/v1/crl/health
  • Description: Provides a health status check for the CRL generation and distribution service.
  • Response: Returns a JSON object with status (healthy or unhealthy), total_cas, crls_generated, and a timestamp.

Inferred Specifications

  • Public and Unauthenticated Access: CRLs are designed for public distribution, allowing any relying party to retrieve them without authentication, which is a fundamental PKI requirement.
  • Efficient Distribution with Caching: The system employs caching mechanisms to ensure that CRLs are served efficiently and are regenerated only when necessary (e.g., new revocations, cache expiry, forced refresh).
  • Standard Compliance: CRLs are distributed with the application/pkix-crl content type, adhering to industry standards.
  • Configurable Validity and Caching: The validity period of CRLs and their caching duration are configurable, allowing administrators to balance freshness with performance.
  • Comprehensive Metadata: The getCrlInfo endpoint provides rich metadata about CRLs, enabling clients to make informed decisions about their usage and validity.
  • CORS Enabled: Cross-Origin Resource Sharing (CORS) is enabled for CRL endpoints, facilitating integration into web-based applications.
  • Service Health Monitoring: A dedicated health check endpoint allows for continuous monitoring of the CRL service's operational status.
  • Audit Logging: All significant events related to CRL generation and distribution are logged for audit and compliance purposes.

Vous n'avez pas envie de la manager ?

Découvrir notre offre PKI As A Service