# Certificates

SSL/TLS certificates are essential for securing Buzzy deployments. This guide covers certificate requirements, acquisition, installation, and management for Buzzy services.

### Table of contents

1. [Certificate requirements](#certificate-requirements)
2. [Certificate types](#certificate-types)
3. [Obtaining certificates](#obtaining-certificates)
4. [Certificate installation](#certificate-installation)
5. [Certificate management](#certificate-management)
6. [Troubleshooting](#troubleshooting)

***

### Certificate requirements

#### Essential Certificates

* **Main Application**: Certificate for the primary Buzzy service domain
* **Logging Service**: Certificate for the logging service domain (if separate)
* **API Endpoints**: Certificates for API access points
* **File Storage**: Certificate for object storage endpoints (if using custom domain)

#### Certificate Specifications

* **Encryption**: Minimum 2048-bit RSA or 256-bit ECC
* **Signature Algorithm**: SHA-256 or higher
* **Protocol Support**: TLS 1.2 and TLS 1.3
* **Validity Period**: Recommended 1-2 years maximum

### Certificate types

#### Domain Validated (DV) Certificates

* **Use Case**: Basic encryption for development and testing
* **Validation**: Domain ownership verification only
* **Cost**: Low cost or free (Let's Encrypt)
* **Trust Level**: Basic browser trust

#### Organization Validated (OV) Certificates

* **Use Case**: Production environments with organizational validation
* **Validation**: Domain ownership and organization verification
* **Cost**: Moderate cost
* **Trust Level**: Higher trust with organization details

#### Extended Validation (EV) Certificates

* **Use Case**: High-security environments requiring maximum trust
* **Validation**: Extensive organization and legal verification
* **Cost**: Higher cost
* **Trust Level**: Highest trust with green address bar

#### Wildcard Certificates

* **Use Case**: Multiple subdomains under a single domain
* **Coverage**: \*.yourdomain.com covers all subdomains
* **Cost**: Higher than single-domain certificates
* **Management**: Simplified certificate management

### Obtaining certificates

#### Let's Encrypt (Free)

* **Automated**: Use ACME clients for automatic certificate management
* **Renewal**: Automatic renewal every 90 days
* **Limitations**: Domain validation only, rate limits apply
* **Tools**: Certbot, cert-manager for Kubernetes

```bash
# Example using Certbot
certbot certonly --standalone -d yourdomain.com -d www.yourdomain.com
```

#### Commercial Certificate Authorities

* **Providers**: DigiCert, GlobalSign, Sectigo, GoDaddy
* **Features**: Extended validation options, warranty coverage
* **Support**: Professional support and documentation
* **Integration**: Often easier integration with enterprise systems

#### Cloud Provider Certificates

* **AWS Certificate Manager**: Free certificates for AWS resources
* **Azure Key Vault**: Certificate management for Azure services
* **Google Cloud SSL**: Managed certificates for Google Cloud
* **Integration**: Seamless integration with cloud load balancers

### Certificate installation

#### Kubernetes Deployment

Using cert-manager for automatic certificate management:

```yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: buzzy-tls
  namespace: buzzy
spec:
  secretName: buzzy-tls-secret
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
  - yourdomain.com
  - www.yourdomain.com
```

#### Load Balancer Configuration

For AWS Application Load Balancer:

```yaml
apiVersion: v1
kind: Service
metadata:
  name: buzzy-service
  annotations:
    service.beta.kubernetes.io/aws-load-balancer-ssl-cert: arn:aws:acm:region:account:certificate/certificate-id
    service.beta.kubernetes.io/aws-load-balancer-backend-protocol: http
    service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443"
spec:
  type: LoadBalancer
  ports:
  - port: 443
    targetPort: 8080
    protocol: TCP
```

#### Docker Compose Configuration

For Docker Compose deployments with reverse proxy:

```yaml
version: '3'
services:
  nginx:
    image: nginx:alpine
    ports:
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./certs:/etc/nginx/certs
    depends_on:
      - buzzy-main
```

### Certificate management

#### Automated Renewal

* **Let's Encrypt**: Use certbot or cert-manager for automatic renewal
* **Commercial**: Set up renewal reminders and processes
* **Monitoring**: Monitor certificate expiration dates
* **Testing**: Test renewal processes regularly

#### Certificate Storage

* **Kubernetes Secrets**: Store certificates as TLS secrets
* **Key Vaults**: Use cloud key management services
* **File System**: Secure file system storage with proper permissions
* **Backup**: Regular backup of certificates and private keys

#### Security Best Practices

* **Private Key Protection**: Secure storage of private keys
* **Access Control**: Limit access to certificate files
* **Regular Rotation**: Regular certificate renewal and rotation
* **Monitoring**: Monitor for certificate-related security issues

### Troubleshooting

#### Common Issues

* **Certificate Mismatch**: Domain name doesn't match certificate
* **Expired Certificate**: Certificate has passed expiration date
* **Chain Issues**: Incomplete certificate chain
* **Permission Problems**: Incorrect file permissions

#### Diagnostic Commands

```bash
# Check certificate details
openssl x509 -in certificate.crt -text -noout

# Verify certificate chain
openssl verify -CAfile ca-bundle.crt certificate.crt

# Test SSL connection
openssl s_client -connect yourdomain.com:443

# Check certificate expiration
echo | openssl s_client -connect yourdomain.com:443 2>/dev/null | openssl x509 -noout -dates
```

#### Resolution Steps

1. **Verify Domain**: Ensure domain names match certificate
2. **Check Expiration**: Verify certificate is still valid
3. **Validate Chain**: Ensure complete certificate chain
4. **Test Connectivity**: Verify network connectivity and DNS
5. **Review Logs**: Check application and load balancer logs

***