API - CA Management (CRUD)

This section details the RESTful API endpoints for performing Create, Read, Update, and Delete (CRUD) operations on Certificate Authorities (CAs). These endpoints provide programmatic control over the full lifecycle of CAs, from creation to deletion, and are essential for integrating the PKI system with other management tools and automation scripts.

Key Functionalities

List Certificate Authorities

• Endpoint: GET /api/v1/certificate-authorities
• Description: Retrieves a comprehensive list of all Certificate Authorities configured in the system.
• Details: Includes information about parent and child CAs, as well as counts of issued certificates and revocations for each CA.

Store a New Certificate Authority

• Endpoint: POST /api/v1/certificate-authorities
• Description: Creates a new Root or Intermediate Certificate Authority.
• Parameters:
  • name (required, string, max 255): A unique name for the CA.
  • type (required, string): The type of CA to create (root or intermediate).
  • common_name (required, string, max 255): The Common Name (CN) for the CA's subject.
  • country (required, string, size 2): The two-letter country code.
  • state (optional, string, max 255): The state or province.
  • city (optional, string, max 255): The city or locality.
  • organization (required, string, max 255): The organization name.
  • organizational_unit (optional, string, max 255): The organizational unit name.
  • email (required, email): The email address for the CA.
  • validity_days (required, integer, min 1, max 36500): The number of days the CA certificate will be valid for.
  • key_size (required, integer): The size of the cryptographic key. Supported values: 2048, 3072, 4096.
  • purpose_category (optional, string, max 255): A category describing the primary purpose of the CA (e.g., web_servers, openvpn).
  • approval_mode (optional, string): The approval workflow for certificates issued by this CA. Supported values: automatic, manual_password, manual_user_approval, manual_team_approval, external_api, policy_based.
  • tenant_id (optional, string, max 255): The ID of the tenant this CA belongs to.
  • parent_ca_id (required for intermediate type, integer): The ID of the parent CA for an intermediate CA.
  • password (optional, string, min 8, max 255): An optional password to protect the CA's private key.
• Private Key Encryption: The system handles the secure encryption of the CA's private key, including an atomic workflow to ensure data integrity during password protection.
• Response (Success - 201 Created): Returns the full details of the newly created CA, including its parent and child CA relationships.

Show Certificate Authority Details

• Endpoint: GET /api/v1/certificate-authorities/{id}
• Description: Retrieves detailed information for a specific Certificate Authority.
• Parameters:
  • id (path parameter): The ID of the Certificate Authority.
• Access Control: Enforces user access based on CAGroup memberships, returning 403 Forbidden if the user does not have access.
• Response: Returns comprehensive CA data, including its hierarchy, status, validity period, and counts of issued certificates.

Update Certificate Authority

• Endpoint: PUT/PATCH /api/v1/certificate-authorities/{id}
• Description: Updates specific attributes of an existing Certificate Authority.
• Parameters (Optional):
  • name (string, max 255): New name for the CA.
  • purpose_category (string, max 255): New purpose category.
  • approval_mode (string): New approval mode.
• Response: Returns the updated CA details.

Delete Certificate Authority

• Endpoint: DELETE /api/v1/certificate-authorities/{id}
• Description: Deletes a specific Certificate Authority from the system.
• Precondition: Prevents deletion if the CA has any active certificates, returning 422 Unprocessable Entity.
• Response: Returns a success message upon successful deletion.

Download CA Certificate

• Endpoint: GET /api/v1/certificate-authorities/{id}/certificate
• Description: Downloads the public certificate of a specified Certificate Authority in PEM format.
• Response: Returns the CA certificate as a file attachment.

Download CA CRL

• Endpoint: GET /api/v1/certificate-authorities/{id}/crl
• Description: Generates and downloads a Certificate Revocation List (CRL) for a specified Certificate Authority.
• Note: The CRL data generated by this endpoint is currently a placeholder (CRL_DATA_PLACEHOLDER).
• Response: Returns the CRL in PKIX CRL format as a file attachment.

Inferred Specifications

• RESTful API Design: Adheres to REST principles for managing CA resources, providing a consistent and predictable interface.
• Comprehensive CA Creation: Supports the creation of both Root and Intermediate CAs with a wide range of configurable parameters, including cryptographic settings, subject details, and operational modes.
• Secure Private Key Handling: Implements an atomic workflow for encrypting CA private keys, particularly when a password is provided, to ensure the key is securely stored and associated with the correct entity ID.
• Role-Based Access Control: Access to CA details and management operations is enforced through user permissions and CAGroup memberships, ensuring that only authorized users can interact with specific CAs.
• Strict Deletion Policy: Prevents the deletion of CAs that still have active certificates, safeguarding the integrity of the PKI and preventing accidental service disruptions.
• API-Driven Downloads: Provides dedicated API endpoints for downloading CA certificates and CRLs, facilitating automated retrieval by client applications.
• CRL Placeholder: The current CRL generation is a placeholder, indicating that full, dynamic CRL generation with actual revoked certificate data is a future enhancement.
• Supported Key Sizes: CA creation supports RSA key sizes of 2048, 3072, and 4096 bits.
• Maximum CA Validity: CAs can be created with a validity period of up to 36500 days (approximately 100 years).
• Flexible Approval Modes: Supports various approval modes for certificates issued by a CA, allowing for adaptable security workflows.