API - CA Private Key Password Management

This section details the RESTful API endpoints dedicated to managing the password protection of Certificate Authority (CA) private keys. These endpoints are critical for enhancing the security of sensitive CA keys and are designed to be integrated into secure administrative tools and workflows.

Key Functionalities

Set Private Key Password Protection

  • Endpoint: POST /api/v1/certificate-authorities/{ca}/password/set
  • Description: Enables password protection for a specified CA's private key. The CA's private key will be re-encrypted with the provided password.
  • Parameters:
    • password (required, string, min 8, max 255): The new password for the CA's private key.
    • password_confirmation (required, string): Confirmation of the new password, must match password.
  • Audit Logging: Logs the event of setting password protection for the CA.

Remove Private Key Password Protection

  • Endpoint: DELETE /api/v1/certificate-authorities/{ca}/password/remove
  • Description: Removes password protection from a CA's private key. The private key will be re-encrypted using the system's default encryption (e.g., APP_KEY).
  • Parameters:
    • current_password (required, string): The current password of the CA's private key, required for decryption before removing protection.
  • Audit Logging: Logs the event of removing password protection.

Change Private Key Password

  • Endpoint: PUT /api/v1/certificate-authorities/{ca}/password/change
  • Description: Changes the existing password for a CA's private key. The private key is decrypted with the current password and then re-encrypted with the new password.
  • Parameters:
    • current_password (required, string): The current password of the CA's private key.
    • new_password (required, string, min 8, max 255): The new password for the CA's private key. Must be different from current_password.
    • confirm_new_password or new_password_confirmation (required, string): Confirmation of the new password, must match new_password.
  • Audit Logging: Logs the event of changing the CA's private key password.

Unlock Private Key for Operations

  • Endpoint: POST /api/v1/certificate-authorities/{ca}/password/unlock
  • Description: Temporarily unlocks a password-protected CA's private key for subsequent cryptographic operations within a session or for a limited time. This does not remove the password protection.
  • Parameters:
    • password (required, string): The password for the CA's private key.
  • Rate Limiting: If the CA's private key is temporarily locked due to too many failed attempts, returns 423 Locked with locked_until timestamp.
  • Validation: Validates the provided password against the stored hash.
  • Audit Logging: Logs successful private key unlocks and failed attempts (including remaining attempts).
  • Response: Returns 401 Unauthorized for invalid passwords.

Get Private Key Protection Status

  • Endpoint: GET /api/v1/certificate-authorities/{ca}/password/status
  • Description: Retrieves the current password protection status and related information for a CA's private key.
  • Response: Returns a JSON object with:
    • requires_private_key_password: Boolean, indicates if password protection is enabled.
    • is_locked: Boolean, indicates if the key is temporarily locked due to failed attempts.
    • locked_until: Timestamp, if is_locked is true.
    • last_accessed_at: Timestamp of the last successful access.
    • access_attempts: Number of recent failed access attempts.

Inferred Specifications

  • API-Driven Security Management: Provides a comprehensive API for managing the security of CA private keys, enabling integration with secure management applications.
  • Strong Password Policy: Enforces a minimum password length of 8 characters and requires confirmation for setting and changing passwords.
  • Secure Password Storage: Passwords are not stored in plaintext; instead, they are used to encrypt/decrypt the CA's private key, and their hashes (BCrypt) are stored for verification.
  • Robust Rate Limiting and Lockout: Implements a rate-limiting mechanism (e.g., 3 failed attempts leading to a temporary lockout) to protect against brute-force attacks on CA private key passwords.
  • Comprehensive Audit Trail: All actions related to CA private key password management (setting, changing, removing, and unlock attempts) are meticulously logged for security, compliance, and forensic analysis.
  • Clear and Specific Error Responses: The API provides distinct HTTP status codes (e.g., 401 Unauthorized, 422 Unprocessable Entity, 423 Locked) and informative error messages to guide API consumers.
  • Temporary Unlock Mechanism: The unlockPrivateKey endpoint facilitates temporary access to the CA's private key for operations without permanently removing its password protection, enhancing operational security.

Vous n'avez pas envie de la manager ?

Découvrir notre offre PKI As A Service