API - CA Rotation Management

This section details the API endpoints for managing Certificate Authority (CA) rotation, providing programmatic access to rotation recommendations, status checks, prerequisite validation, and the rotation process itself. These endpoints are crucial for automating CA lifecycle management and integrating with other systems.

Key Functionalities

Get Rotation Recommendations

• Endpoint: GET /api/v1/ca-rotation/recommendations
• Description: Retrieves a list of recommendations for CA rotation across all Certificate Authorities in the system.
• Response: Returns an array of rotation recommendations, likely including priority and suggested actions.

Get CA Rotation Status

• Endpoint: GET /api/v1/ca-rotation/ca/{ca}/status
• Description: Provides a detailed rotation status report for a specific Certificate Authority.
• Parameters:
  • ca (path parameter): The ID or identifier of the Certificate Authority.
• Response: Returns the current rotation status, including urgency, days until expiry, and any identified issues.

Validate Rotation Prerequisites

• Endpoint: GET /api/v1/ca-rotation/ca/{ca}/validate
• Description: Checks and lists all prerequisites that must be met before a specific CA can be rotated.
• Parameters:
  • ca (path parameter): The ID or identifier of the Certificate Authority.
• Response: Returns a list of unmet prerequisites, if any, indicating what needs to be resolved.

Perform CA Rotation

• Endpoint: POST /api/v1/ca-rotation/ca/{ca}/rotate
• Description: Initiates the CA rotation process for a specified Certificate Authority.
• Parameters:
  • ca (path parameter): The ID or identifier of the Certificate Authority.
  • validity_days: Required integer (365-7300), validity period for the new CA.
  • key_size: Required integer (2048, 3072, 4096), key size for the new CA.
  • hash_algorithm: Required string (sha256, sha384, sha512), hash algorithm for the new CA.
  • enable_cross_signing: Boolean (optional), whether to enable cross-signing.
  • cross_sign_validity_days: Integer (30-365, optional), validity for cross-signed certificate if enabled.
  • confirm_rotation: Required boolean, must be true to confirm the action.
• Response: Returns the result of the rotation, typically including details of the new CA created.

Get Certificate Migration Plan

• Endpoint: GET /api/v1/ca-rotation/migration-plan/{oldCA}/{newCA}
• Description: Generates and returns a plan for migrating existing certificates from an old CA to a newly rotated CA.
• Parameters:
  • oldCA (path parameter): The ID or identifier of the old Certificate Authority.
  • newCA (path parameter): The ID or identifier of the new Certificate Authority.
• Response: Returns a detailed plan for certificate migration, ensuring continuity of services.

Inferred Specifications

• API-Driven CA Lifecycle: The API provides full programmatic control over the CA rotation lifecycle, from assessment to execution.
• Automated Rotation: Enables the automation of CA rotation processes, which is critical for maintaining security and compliance at scale.
• Prerequisite Enforcement: The API enforces strict prerequisite checks before allowing CA rotation, ensuring system stability and security.
• Configurable New CA Attributes: Allows for the specification of cryptographic parameters (key size, hash algorithm) and validity periods for the newly generated CA during rotation.
• Cross-Signing Support: Facilitates a smooth transition of trust by supporting cross-signing between the old and new CAs.
• Certificate Migration Planning: Provides tools for planning the migration of certificates, minimizing service disruption during CA rotation.
• Input Validation: All API endpoints for rotation actions include robust input validation to ensure data integrity and prevent erroneous operations.
• Auditability: All CA rotation operations performed via the API are expected to be thoroughly logged for audit and compliance purposes (implied by the CARotationService and overall system design).