298 lines
6.8 KiB
Markdown
298 lines
6.8 KiB
Markdown
# 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
|