AWS PCA Integration

[jmgilman]

AWS PCA Integration

Overview

Implement comprehensive integration with AWS Private Certificate Authority (PCA) to enable certificate issuance, including client wrapper implementation, certificate profiles configuration, and robust error handling.

Objective

Create a reliable, performant integration layer with AWS PCA that handles certificate issuance requests, applies appropriate certificate profiles (client, server, machine), and provides proper error handling and retry logic for transient failures.

Tasks

Canonical Scope

• This document is the canonical source for:
  • Certificate profile definitions and CA selection
  • AWS PCA client behavior and retry policy
• For CSR and field validation and error schema, see 07 Security & Validation.
• For GORM models and persistence, see 05 Database Layer.

AWS PCA Client Wrapper

• Implement PCA client wrapper in internal/ca/pca.go
• Configure AWS SDK v2 with proper region and credentials
• Implement connection pooling and timeout configurations
• Create abstraction layer over AWS PCA SDK for:
  • Certificate issuance
  • Certificate retrieval
  • CA certificate chain retrieval
  • Certificate revocation (if needed)
• Implement client configuration:

  type PCAClient struct {
    client *acmpca.Client
    config *PCAConfig
    logger *zap.Logger
  }
  
  type PCAConfig struct {
    Region       string
    RootCAArn    string
    ClientCAArn  string
    ServerCAArn  string
    IstioCAArn   string
    MaxRetries   int
    RetryDelay   time.Duration
  }

Certificate Profiles Implementation

• Implement certificate profiles in internal/ca/profiles.go
• Define profile structures for client, server, and machine certificates
• Client Profile Configuration:

  // Key Usage: DigitalSignature | KeyAgreement
  // Extended Key Usage: ClientAuthentication
  // Validity: 7 days maximum

• Server Profile Configuration:

  // Key Usage: DigitalSignature | KeyEncipherment
  // Extended Key Usage: ServerAuthentication
  // Validity: 7 days maximum

• Machine Profile Configuration:

  // Key Usage: DigitalSignature | KeyEncipherment
  // Extended Key Usage: ClientAuthentication | ServerAuthentication
  // Validity: 7 days maximum

• Implement profile selection logic based on certificate type
• Create profile validation to ensure compliance with policies

Certificate Issuance Logic

• Implement certificate issuance function with profile support
• Create CSR generation if not provided by client
• Implement key pair generation (RSA 2048 or ECDSA P-256)
• Build certificate request structure:

  type CertificateRequest struct {
    CommonName string
    SANs       []string
    Profile    CertificateProfile
    CSR        []byte // Optional, generate if not provided
    ValidityDays int  // Max 7 days
  }

• Map profiles to appropriate CA selection (client-ca, server-ca, istio-ca)
• Implement AWS PCA IssueCertificate API call
• Handle certificate signing and retrieval
• Implement certificate chain assembly (cert + intermediates + root)
• Return certificate bundle in PEM format

Request Validation

• Use validators defined in 07 Security & Validation:
  • CSR parsing and signature/key-strength checks
  • Domain/IP validation and wildcard rules
  • Validity period enforcement (max 7 days)
  • Profile-specific validation rules
  • SAN validation and deduplication

Error Handling and Retry Logic

• Implement comprehensive error mapping from AWS PCA errors
• Error types mapping:

  // AWS PCA Error → HTTP Status Code
  InvalidArgsException → 400 Bad Request
  LimitExceededException → 429 Too Many Requests
  InvalidStateException → 503 Service Unavailable
  ResourceNotFoundException → 500 Internal Server Error
  RequestInProgressException → 409 Conflict

• Implement exponential backoff retry mechanism:
  • Maximum 3 retry attempts
  • Initial delay: 100ms
  • Backoff factor: 2
  • Maximum delay: 5 seconds
• Create retry-able vs non-retry-able error classification
• Add detailed error logging with AWS request IDs

CA Certificate Management

• Implement CA certificate retrieval and caching
• Create function to fetch CA certificate chains from AWS PCA
• Implement local caching with 1-hour TTL
• Store CA certificates in database (certificate_authorities table)
• Implement CA certificate refresh mechanism
• Monitor CA certificate expiration (alert if < 30 days)
• Create CA chain validation logic

GORM Models

• Use models defined in 05 Database Layer for certificate and CA entities

Acceptance Criteria

• Successfully issue certificates through AWS PCA
• All three certificate profiles (client, server, machine) working
• Proper CA selection based on certificate type
• Certificate validity enforced at 7 days maximum
• Retry logic handles transient AWS failures
• Error responses properly mapped to HTTP status codes
• CA certificates cached and refreshed appropriately
• All validations working (CSR, domain, validity)
• Certificate metadata stored in database via GORM
• Comprehensive error logging with AWS request IDs

Technical Considerations

• Use AWS SDK v2 for Go
• Implement context propagation for all AWS API calls
• Use structured logging for all operations
• Consider rate limiting to avoid AWS PCA throttling
• Use GORM hooks for automatic timestamp management
• Cache frequently used CA certificates (1-hour TTL as per GUIDE)
• Use AWS SDK default connection pooling as specified

Dependencies

• AWS SDK v2 packages:
  • github.com/aws/aws-sdk-go-v2/config
  • github.com/aws/aws-sdk-go-v2/service/acmpca
  • github.com/aws/aws-sdk-go-v2/service/sts
• Certificate handling:
  • crypto/x509
  • crypto/x509/pkix
  • crypto/rand
  • encoding/pem
• GORM and PostgreSQL driver (from issue feat: adds cuetools package #1)

Testing Requirements

• Unit tests for profile selection logic
• Unit tests for CSR validation
• Unit tests for error mapping
• Unit tests for retry logic
• Integration tests with AWS PCA (using test CA)
• Mock AWS PCA client for unit testing
• Load test certificate issuance (verify 5 RPS)
• Test certificate chain validation
• Test CA certificate caching and refresh

Definition of Done

• Code reviewed and approved
• All tests passing
• Successfully issued test certificates for all profiles
• AWS PCA integration documented
• Error scenarios tested and handled
• Performance metrics meet requirements
• No security vulnerabilities in certificate handling
• Proper cleanup of test certificates