Certificate Management

X.509 certificates provide the cryptographic foundation for AS2 message security. AS2aaS offers comprehensive certificate lifecycle management including upload, validation, monitoring, and automated expiry notifications.

Certificate Types

Signing Certificates

Used for digital signature creation and verification to ensure message authenticity and non-repudiation.

Encryption Certificates

Used for message encryption and decryption to protect sensitive business data during transmission.

Dual-Purpose Certificates

Certificates configured for both signing and encryption operations, suitable for smaller deployments with simplified certificate management.

Certificate Upload

Upload with Private Key

curl -X POST https://api.as2aas.com/v1/certificates \
  -H "Authorization: Bearer pk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cert_upload_001" \
  -d '{
    "name": "Corporate Signing Certificate",
    "type": "signing",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAKoK/heBjcOuMA0GCSqGSIb3DQEBBQUAMEUxCzAJBgNV\n...\n-----END CERTIFICATE-----",
    "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDBTuKsaLMFA7En\n...\n-----END PRIVATE KEY-----",
    "password": "certificate_password"
  }'

Upload Public Certificate Only

curl -X POST https://api.as2aas.com/v1/certificates \
  -H "Authorization: Bearer pk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cert_public_001" \
  -d '{
    "name": "Partner Public Certificate",
    "type": "encryption",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAKoK/heBjcOuMA0GCSqGSIb3DQEBBQUAMEUxCzAJBgNV\n...\n-----END CERTIFICATE-----",
    "owner": "partner"
  }'

Certificate Validation

The platform performs comprehensive validation upon certificate upload:

Validation Checks

• Format Validation - PEM structure and encoding
• Key Pair Verification - Private key matches certificate public key
• Expiration Validation - Certificate validity period
• Chain Validation - Certificate authority chain integrity
• Usage Validation - Key usage extensions compatibility
• Algorithm Support - Cryptographic algorithm compatibility

Validation Response

{
  "id": "cert_1234567890",
  "name": "Corporate Signing Certificate",
  "type": "signing",
  "status": "active",
  "validation": {
    "valid": true,
    "checks": {
      "format": "passed",
      "expiration": "passed",
      "key_match": "passed",
      "usage": "passed",
      "algorithm": "passed"
    }
  },
  "subject": "CN=Corporation Name, O=Corporation Inc, C=US",
  "issuer": "CN=Certificate Authority, O=CA Organization",
  "expires_at": "2025-12-31T23:59:59Z"
}

Certificate Listing

Retrieve All Certificates

curl -X GET https://api.as2aas.com/v1/certificates \
  -H "Authorization: Bearer pk_test_your_api_key"

Filter by Type

curl -X GET "https://api.as2aas.com/v1/certificates?type=signing" \
  -H "Authorization: Bearer pk_test_your_api_key"

Filter by Expiration

curl -X GET "https://api.as2aas.com/v1/certificates?expires_soon=true&expires_soon_days=30" \
  -H "Authorization: Bearer pk_test_your_api_key"

Expiry Monitoring

Expiry Status Check

curl -X GET https://api.as2aas.com/v1/certificates/cert_123/expiry \
  -H "Authorization: Bearer pk_test_your_api_key"

Response:

{
  "certificate_id": "cert_1234567890",
  "expires_at": "2024-12-31T23:59:59Z",
  "days_until_expiry": 45,
  "status": "valid",
  "recommendations": [
    "Certificate renewal recommended within 30 days of expiration"
  ]
}

Certificate Generation

Generate Certificate Signing Request

curl -X POST https://api.as2aas.com/v1/certificates/generate-csr \
  -H "Authorization: Bearer pk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "common_name": "as2.corporation.com",
      "organization": "Corporation Inc",
      "organizational_unit": "IT Operations",
      "country": "US",
      "state": "California",
      "locality": "San Francisco"
    },
    "key_algorithm": "RSA",
    "key_size": 2048,
    "signature_algorithm": "SHA256withRSA"
  }'

Partner Association

Associate Encryption Certificate

curl -X PATCH https://api.as2aas.com/v1/partners/prt_123 \
  -H "Authorization: Bearer pk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "encryption_cert_id": "cert_encryption_001"
  }'

Associate Signing Certificate

curl -X PATCH https://api.as2aas.com/v1/partners/prt_123 \
  -H "Authorization: Bearer pk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "signing_cert_id": "cert_signing_001"
  }'

Enterprise Certificate Management

Certificate Renewal Process

1. Generate new certificate with identical subject
2. Upload new certificate to platform
3. Update partner associations
4. Validate connectivity with test messages
5. Deactivate expired certificate

Bulk Certificate Operations

# Update multiple partners with new certificate
curl -X PATCH https://api.as2aas.com/v1/certificates/cert_old_123/replace \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "replacement_cert_id": "cert_new_456",
    "update_partners": true
  }'

Security Best Practices

Certificate Storage

• Private keys are encrypted at rest using AES-256
• Certificate access is logged and audited
• Key operations are performed in secure enclaves
• Backup and recovery procedures are automated

Operational Security

• Implement certificate rotation policies
• Monitor certificate usage patterns
• Use Hardware Security Modules for high-value certificates
• Maintain certificate inventory and dependencies

Error Handling

Certificate Validation Errors

Invalid Certificate Format:

{
  "error": {
    "type": "validation_error",
    "code": "invalid_certificate_format",
    "message": "Certificate must be in valid PEM format"
  }
}

Private Key Mismatch:

{
  "error": {
    "type": "validation_error",
    "code": "private_key_mismatch",
    "message": "Private key does not correspond to certificate public key"
  }
}

Expired Certificate:

{
  "error": {
    "type": "validation_error", 
    "code": "certificate_expired",
    "message": "Certificate validity period has expired"
  }
}