API - Certificate Issuance

This section details the API endpoint for issuing new certificates, providing a programmatic interface for creating certificates with various configurations. This endpoint is crucial for integrating the PKI system with automated provisioning tools and other applications.

Key Functionality

Store a Newly Created Certificate

• Endpoint: POST /api/v1/certificates
• Description: Issues a new X.509 certificate signed by a specified Certificate Authority (CA).
• Parameters:
  • ca_id (required, integer): The ID of the CertificateAuthority to be used for signing the new certificate. Must exist in the system.
  • common_name (required, string, max 255): The Common Name (CN) for the certificate's subject.
  • type (required, string): The type of certificate to issue. Supported values include: server, client, email, code_signing, user.
  • validity_days (optional, integer, min 1, max 3650): The number of days the certificate will be valid for. Defaults to 365 days if not provided.
  • san_dns (optional, array of strings, max 255 per entry): An array of DNS Subject Alternative Names (SANs) to include in the certificate.
  • san_ip (optional, array of IP addresses): An array of IP address SANs to include in the certificate.
  • ca_password (optional, string): The private key password of the issuing CA. This parameter is required if the selected CertificateAuthority is password-protected.
• Validation:
  • All required fields are validated for presence and format.
  • ca_id is checked against existing CertificateAuthority records.
  • type is restricted to the defined set of supported certificate types.
  • validity_days is constrained to a reasonable range (1 to 3650 days).
  • san_dns and san_ip entries are validated for format.
  • If the issuing CA requires a password, ca_password is validated for presence and correctness.
• Error Handling:
  • Returns 422 Unprocessable Entity with detailed validation errors if input is invalid.
  • Returns 422 Unprocessable Entity with a specific error message if the ca_password is required but missing or incorrect.
  • Returns 500 Internal Server Error for other failures during certificate generation.
• Response (Success - 201 Created): json { "message": "Certificate created successfully", "data": { "id": 123, "common_name": "my-server.example.com", "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----", "serial_number": "1234567890ABCDEF", "valid_from": "2025-10-03T10:00:00Z", "valid_until": "2026-10-03T10:00:00Z" } }

Inferred Specifications

• API-First Certificate Provisioning: This endpoint is designed for automated and programmatic certificate issuance, enabling seamless integration with CI/CD pipelines, orchestration tools, and other services.
• Flexible Subject Alternative Names (SANs): Supports both DNS hostnames and IP addresses as SANs, accommodating diverse certificate requirements.
• Strict CA Password Enforcement: The API rigorously enforces password protection for issuing CAs, requiring the ca_password parameter when necessary and providing clear error feedback for security.
• Comprehensive Input Validation: Robust validation rules are applied to all incoming request parameters, ensuring the integrity and correctness of the certificate request before processing.
• Granular Certificate Types: Supports a predefined set of certificate types, allowing for the issuance of certificates tailored to specific use cases (e.g., server authentication, client authentication, email encryption).
• Configurable Validity Period: Certificates can be issued with a configurable validity period, up to a maximum of 10 years (3650 days).
• Detailed Error Responses: Provides specific and actionable error messages, particularly for validation failures and password-related issues, to aid in debugging and integration.
• Auditability: All certificate issuance actions performed via this API are expected to be logged for audit and compliance purposes (implied by the CryptoService and overall system design).