atlas/docs/HTTPS_TLS.md

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:

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):

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)

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

Production (HTTPS)

# 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

# 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:

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

Use it:

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

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

<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