# HTTPS/TLS Support

## Overview

AtlasOS supports HTTPS/TLS encryption for secure communication. TLS can be enabled via environment variables, and the system will automatically enforce HTTPS connections when TLS is enabled.

## Configuration

### Environment Variables

TLS is configured via environment variables:

- **`ATLAS_TLS_CERT`**: Path to TLS certificate file (PEM format)
- **`ATLAS_TLS_KEY`**: Path to TLS private key file (PEM format)
- **`ATLAS_TLS_ENABLED`**: Force enable TLS (optional, auto-enabled if cert/key provided)

### Automatic Detection

TLS is automatically enabled if both `ATLAS_TLS_CERT` and `ATLAS_TLS_KEY` are set:

```bash
export ATLAS_TLS_CERT=/etc/atlas/tls/cert.pem
export ATLAS_TLS_KEY=/etc/atlas/tls/key.pem
./atlas-api
```

### Explicit Enable

Force TLS even if cert/key are not set (will fail at startup if cert/key missing):

```bash
export ATLAS_TLS_ENABLED=true
export ATLAS_TLS_CERT=/etc/atlas/tls/cert.pem
export ATLAS_TLS_KEY=/etc/atlas/tls/key.pem
./atlas-api
```

## Certificate Requirements

### Certificate Format

- **Format**: PEM (Privacy-Enhanced Mail)
- **Certificate**: X.509 certificate
- **Key**: RSA or ECDSA private key
- **Chain**: Certificate chain can be included in cert file

### Certificate Validation

At startup, the system validates:
- Certificate file exists
- Key file exists
- Certificate and key are valid and match
- Certificate is not expired (checked by Go's TLS library)

## TLS Configuration

### Supported TLS Versions

- **Minimum**: TLS 1.2
- **Maximum**: TLS 1.3

### Cipher Suites

The system uses secure cipher suites:

- `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`
- `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`
- `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305`
- `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305`
- `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`
- `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`

### Elliptic Curves

Preferred curves:
- `CurveP256`
- `CurveP384`
- `CurveP521`
- `X25519`

## HTTPS Enforcement

### Automatic Redirect

When TLS is enabled, HTTP requests are automatically redirected to HTTPS:

```
HTTP Request → 301 Moved Permanently → HTTPS
```

### Exceptions

HTTPS enforcement is skipped for:
- **Health checks**: `/healthz`, `/health` (allows monitoring)
- **Localhost**: Requests from `localhost`, `127.0.0.1`, `::1` (development)

### Reverse Proxy Support

The system respects `X-Forwarded-Proto` header for reverse proxy setups:

```
X-Forwarded-Proto: https
```

## Usage Examples

### Development (HTTP)

```bash
# No TLS configuration - runs on HTTP
./atlas-api
```

### Production (HTTPS)

```bash
# Enable TLS
export ATLAS_TLS_CERT=/etc/ssl/certs/atlas.crt
export ATLAS_TLS_KEY=/etc/ssl/private/atlas.key
export ATLAS_HTTP_ADDR=:8443
./atlas-api
```

### Using Let's Encrypt

```bash
# Let's Encrypt certificates
export ATLAS_TLS_CERT=/etc/letsencrypt/live/atlas.example.com/fullchain.pem
export ATLAS_TLS_KEY=/etc/letsencrypt/live/atlas.example.com/privkey.pem
./atlas-api
```

### Self-Signed Certificate (Testing)

Generate a self-signed certificate:

```bash
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
```

Use it:

```bash
export ATLAS_TLS_CERT=./cert.pem
export ATLAS_TLS_KEY=./key.pem
./atlas-api
```

## Security Headers

When TLS is enabled, additional security headers are set:

### HSTS (HTTP Strict Transport Security)

```
Strict-Transport-Security: max-age=31536000; includeSubDomains
```

- **Max Age**: 1 year (31536000 seconds)
- **Include Subdomains**: Yes
- **Purpose**: Forces browsers to use HTTPS

### Content Security Policy

CSP is configured to work with HTTPS:

```
Content-Security-Policy: default-src 'self'; ...
```

## Reverse Proxy Setup

### Nginx

```nginx
server {
    listen 443 ssl;
    server_name atlas.example.com;

    ssl_certificate /etc/ssl/certs/atlas.crt;
    ssl_certificate_key /etc/ssl/private/atlas.key;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

### Apache

```apache
<VirtualHost *:443>
    ServerName atlas.example.com
    
    SSLEngine on
    SSLCertificateFile /etc/ssl/certs/atlas.crt
    SSLCertificateKeyFile /etc/ssl/private/atlas.key

    ProxyPass / http://localhost:8080/
    ProxyPassReverse / http://localhost:8080/
    
    RequestHeader set X-Forwarded-Proto "https"
</VirtualHost>
```

## Troubleshooting

### Certificate Not Found

```
TLS configuration error: TLS certificate file not found: /path/to/cert.pem
```

**Solution**: Verify certificate file path and permissions.

### Certificate/Key Mismatch

```
TLS configuration error: load TLS certificate: tls: private key does not match public key
```

**Solution**: Ensure certificate and key files match.

### Certificate Expired

```
TLS handshake error: x509: certificate has expired or is not yet valid
```

**Solution**: Renew certificate or use a valid certificate.

### Port Already in Use

```
listen tcp :8443: bind: address already in use
```

**Solution**: Change port or stop conflicting service.

## Best Practices

### 1. Use Valid Certificates

- **Production**: Use certificates from trusted CAs (Let's Encrypt, commercial CAs)
- **Development**: Self-signed certificates are acceptable
- **Testing**: Use test certificates with short expiration

### 2. Certificate Renewal

- **Monitor Expiration**: Set up alerts for certificate expiration
- **Auto-Renewal**: Use tools like `certbot` for Let's Encrypt
- **Graceful Reload**: Restart service after certificate renewal

### 3. Key Security

- **Permissions**: Restrict key file permissions (`chmod 600`)
- **Ownership**: Use dedicated user for key file
- **Storage**: Store keys securely, never commit to version control

### 4. TLS Configuration

- **Minimum Version**: TLS 1.2 or higher
- **Cipher Suites**: Use strong cipher suites only
- **HSTS**: Enable HSTS for production

### 5. Reverse Proxy

- **Terminate TLS**: Terminate TLS at reverse proxy for better performance
- **Forward Headers**: Forward `X-Forwarded-Proto` header
- **Health Checks**: Allow HTTP for health checks

## Compliance

### SRS Requirement

Per SRS section 5.3 Security:
- **HTTPS SHALL be enforced for the web UI** ✅

This implementation:
- ✅ Supports TLS/HTTPS
- ✅ Enforces HTTPS when TLS is enabled
- ✅ Provides secure cipher suites
- ✅ Includes HSTS headers
- ✅ Validates certificates

## Future Enhancements

1. **Certificate Auto-Renewal**: Automatic certificate renewal
2. **OCSP Stapling**: Online Certificate Status Protocol stapling
3. **Certificate Rotation**: Seamless certificate rotation
4. **TLS 1.4 Support**: Support for future TLS versions
5. **Client Certificate Authentication**: Mutual TLS (mTLS)
6. **Certificate Monitoring**: Certificate expiration monitoring