This commit is contained in:
297
docs/HTTPS_TLS.md
Normal file
297
docs/HTTPS_TLS.md
Normal file
@@ -0,0 +1,297 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user