# Cosmian KMS Task Service

## Overview

The KMS task service provides a complete installation and configuration of [Cosmian KMS](https://cosmian.com/), a comprehensive Key Management Service that offers advanced cryptographic capabilities including post-quantum security, attribute-based encryption, and secure multi-party computation. This enterprise-grade solution is designed for organizations requiring the highest levels of data protection and compliance.

## Features

### Core Capabilities
- **Key Management** - Comprehensive lifecycle management for cryptographic keys
- **Post-Quantum Cryptography** - Future-proof security algorithms
- **Attribute-Based Encryption** - Fine-grained access control encryption
- **Secure Multi-Party Computation** - Privacy-preserving computations
- **FIPS 140-2 Support** - Government-grade cryptographic compliance

### Database Support
- **SQLite** (default) - Simple, file-based database for development
- **PostgreSQL** - Production-ready relational database
- **MySQL** - Alternative relational database option
- **Redis** - High-performance in-memory database

### Authentication & Security
- **JWT Authentication** - Industry-standard token-based authentication
- **OpenID Connect** - Integration with identity providers
- **TLS/SSL Support** - Encrypted communication channels
- **Access Control** - Fine-grained permission management
- **Audit Logging** - Comprehensive security event logging

### Management Features
- **Systemd Integration** - Full service management and monitoring
- **Health Monitoring** - Built-in health check endpoints
- **Configuration Management** - Flexible TOML-based configuration
- **Multi-tenancy** - Support for multiple isolated tenants

## Configuration

### Basic Configuration
```kcl
kms: CosmianKMS = {
    name: "kms-dev"
    version: "4.5.0"
    run_user: {
        name: "kms"
        home: "/home/kms"
    }
    bind_addr: "0.0.0.0"
    bind_port: 9998
    database: {
        typ: "sqlite"
        path: "/var/lib/kms/kms.db"
    }
}
```

### Production Configuration
```kcl
kms: CosmianKMS = {
    name: "kms-prod"
    version: "4.5.0"
    run_user: {
        name: "kms"
        group: "kms"
        home: "/opt/kms"
    }
    work_path: "/var/lib/kms"
    config_path: "/etc/kms"
    bind_addr: "0.0.0.0"
    bind_port: 9998
    database: {
        typ: "postgresql"
        host: "postgres.company.com"
        port: 5432
        database: "cosmian_kms"
        username: "kms_user"
        password: "secure_database_password"
        ssl_mode: "require"
    }
    auth: {
        enabled: true
        jwt_issuer_uri: "https://auth.company.com"
        jwks_uri: "https://auth.company.com/.well-known/jwks.json"
        jwt_audience: "kms-service"
    }
    tls: {
        enabled: true
        cert_file: "/etc/ssl/certs/kms.crt"
        key_file: "/etc/ssl/private/kms.key"
        ca_cert_file: "/etc/ssl/certs/ca.crt"
    }
    fips_mode: true
    log_level: "info"
}
```

### High Availability Configuration
```kcl
kms: CosmianKMS = {
    name: "kms-ha"
    # ... base configuration
    database: {
        typ: "postgresql"
        host: "postgres-cluster.company.com"
        port: 5432
        database: "cosmian_kms"
        username: "kms_user"
        password: "secure_password"
        ssl_mode: "require"
    }
    cluster: {
        enabled: true
        nodes: [
            "kms-node-1.company.com:9998",
            "kms-node-2.company.com:9998",
            "kms-node-3.company.com:9998"
        ]
        shared_secret: "cluster_shared_secret"
    }
}
```

## Usage

### Deploy KMS Server
```bash
./core/nulib/provisioning taskserv create kms --infra <infrastructure-name>
```

### List Available Task Services
```bash
./core/nulib/provisioning taskserv list
```

### SSH to KMS Server
```bash
./core/nulib/provisioning server ssh <kms-server>
```

### Service Management
```bash
# Check KMS server status
systemctl status cosmian-kms

# Start/stop KMS server
systemctl start cosmian-kms
systemctl stop cosmian-kms
systemctl restart cosmian-kms

# View KMS logs
journalctl -u cosmian-kms -f

# Check KMS configuration
sudo -u kms cosmian_kms_server --help
```

### Health Check
```bash
# Check server health
curl http://localhost:9998/health

# Check detailed status
curl http://localhost:9998/status

# Verify TLS configuration (if enabled)
curl -k https://localhost:9998/health
```

### CLI Usage
```bash
# Install Cosmian CLI
curl -o cosmian https://package.cosmian.com/cosmian_cli/latest/linux-x86_64/cosmian
chmod +x cosmian
sudo mv cosmian /usr/local/bin/

# Connect to KMS server
cosmian kms config --server-url https://kms.company.com:9998

# Create symmetric key
cosmian kms create-key --algorithm AES --key-length 256 --key-id my-aes-key

# Create RSA key pair
cosmian kms create-key-pair --algorithm RSA --key-length 2048 --private-key-id my-rsa-private --public-key-id my-rsa-public

# Encrypt data
echo "sensitive data" | cosmian kms encrypt --key-id my-aes-key --output encrypted.bin

# Decrypt data
cosmian kms decrypt --key-id my-aes-key --input encrypted.bin
```

## Architecture

### System Architecture
```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Applications  │────│   Cosmian KMS    │────│    Database     │
│                 │    │                  │    │                 │
│ • REST API      │    │ • Key Management │    │ • PostgreSQL    │
│ • CLI Tools     │────│ • Cryptographic  │────│ • MySQL         │
│ • SDK Clients   │    │   Operations     │    │ • SQLite        │
│ • Web Console   │    │ • Access Control │    │ • Redis         │
└─────────────────┘    └──────────────────┘    └─────────────────┘
```

### Network Ports
- **HTTPS/HTTP (9998)** - Main KMS API endpoint
- **Health Check** - Same port as main API
- **Metrics** - Prometheus metrics on main port

### File Structure
```
/var/lib/kms/               # Main working directory
├── kms.db                 # SQLite database (if used)
├── keys/                  # Key storage directory
├── certificates/          # Certificate storage
├── logs/                  # Application logs
└── backups/              # Automated backups

/etc/kms/                 # Configuration directory
├── kms.toml              # Main configuration file
├── certificates/         # TLS certificates
└── policies/             # Access control policies

/home/kms/                # Service user home
├── .config/              # User configuration
└── .cosmian/             # CLI configuration
```

## Supported Operating Systems

- Ubuntu 20.04+ / Debian 11+
- CentOS 8+ / RHEL 8+ / Fedora 35+

## System Requirements

### Minimum Requirements
- **RAM**: 2GB (4GB recommended)
- **Storage**: 10GB (varies with key storage needs)
- **CPU**: 2 cores (4 cores recommended)
- **Network**: Internet access for initial setup

### Production Requirements
- **RAM**: 8GB+ (for high-throughput operations)
- **Storage**: 100GB+ SSD (for performance and key storage)
- **CPU**: 4+ cores (for cryptographic operations)
- **Database**: External PostgreSQL recommended
- **Load Balancer**: For high availability deployments

### FIPS Mode Requirements
- **Hardware Security Module (HSM)** - For FIPS 140-2 Level 3/4
- **Certified Hardware** - FIPS-validated cryptographic modules
- **Secure Boot** - Hardware-based secure boot process

## Key Management Operations

### Symmetric Keys
```bash
# Create AES key
cosmian kms create-key --algorithm AES --key-length 256 --key-id prod-aes-256

# Rotate key
cosmian kms rotate-key --key-id prod-aes-256

# Export key (with proper permissions)
cosmian kms export-key --key-id prod-aes-256 --output-file aes-key.bin

# Import existing key
cosmian kms import-key --algorithm AES --key-file existing-key.bin --key-id imported-aes
```

### Asymmetric Keys
```bash
# Create RSA key pair
cosmian kms create-key-pair --algorithm RSA --key-length 4096 \
    --private-key-id company-rsa-private \
    --public-key-id company-rsa-public

# Create ECDSA key pair
cosmian kms create-key-pair --algorithm ECDSA --curve P-384 \
    --private-key-id company-ecdsa-private \
    --public-key-id company-ecdsa-public

# Export public key
cosmian kms export-key --key-id company-rsa-public --output-file public-key.pem
```

### Post-Quantum Keys
```bash
# Create Kyber key pair (post-quantum)
cosmian kms create-key-pair --algorithm Kyber --variant Kyber1024 \
    --private-key-id pq-kyber-private \
    --public-key-id pq-kyber-public

# Create Dilithium key pair (post-quantum signatures)
cosmian kms create-key-pair --algorithm Dilithium --variant Dilithium5 \
    --private-key-id pq-dilithium-private \
    --public-key-id pq-dilithium-public
```

## Cryptographic Operations

### Encryption/Decryption
```bash
# Symmetric encryption
echo "confidential data" | cosmian kms encrypt --key-id my-aes-key --output data.enc

# Asymmetric encryption
echo "secret message" | cosmian kms encrypt --key-id rsa-public-key --output message.enc

# Attribute-based encryption
echo "classified info" | cosmian kms abe-encrypt \
    --policy "department::security AND clearance::top-secret" \
    --output classified.enc
```

### Digital Signatures
```bash
# Create digital signature
echo "document content" | cosmian kms sign --key-id signing-private-key --output document.sig

# Verify signature
cosmian kms verify --key-id signing-public-key --signature document.sig --input document.txt

# Post-quantum signature
echo "future-proof document" | cosmian kms sign --key-id dilithium-private --output pq-document.sig
```

### Key Derivation
```bash
# HKDF key derivation
cosmian kms derive-key --algorithm HKDF --master-key-id master-key \
    --info "application-specific-info" --derived-key-id derived-key

# PBKDF2 key derivation
cosmian kms derive-key --algorithm PBKDF2 --password "user-password" \
    --salt "random-salt" --iterations 100000 --derived-key-id user-key
```

## Troubleshooting

### Service Issues
```bash
# Check KMS server status
systemctl status cosmian-kms

# View recent logs
journalctl -u cosmian-kms -n 100

# Check configuration syntax
sudo -u kms cosmian_kms_server --config /etc/kms/kms.toml --check-config

# Test database connection
sudo -u kms cosmian_kms_server --config /etc/kms/kms.toml --test-db
```

### Database Issues
```bash
# SQLite issues
ls -la /var/lib/kms/kms.db
sudo -u kms sqlite3 /var/lib/kms/kms.db ".schema"

# PostgreSQL connection test
sudo -u kms psql -h <host> -U <user> -d <database> -c "SELECT version();"

# Check database migrations
sudo -u kms cosmian_kms_server --migrate-db
```

### Authentication Issues
```bash
# Test JWT token validation
curl -H "Authorization: Bearer <jwt-token>" http://localhost:9998/health

# Verify JWKS endpoint
curl https://auth.provider.com/.well-known/jwks.json

# Test OIDC discovery
curl https://auth.provider.com/.well-known/openid-configuration
```

### Cryptographic Issues
```bash
# Test cryptographic operations
cosmian kms create-key --algorithm AES --key-length 256 --key-id test-key
echo "test data" | cosmian kms encrypt --key-id test-key --output test.enc
cosmian kms decrypt --key-id test-key --input test.enc

# Verify FIPS mode
sudo -u kms cosmian_kms_server --fips-status

# Check hardware entropy
cat /proc/sys/kernel/random/entropy_avail
```

### Network Connectivity
```bash
# Check if KMS is listening
netstat -tlnp | grep :9998

# Test API endpoint
curl -I http://localhost:9998/health

# Test TLS configuration
openssl s_client -connect localhost:9998 -servername kms.company.com
```

## Security Considerations

### Server Security
- **TLS/SSL** - Always use HTTPS in production
- **Certificate Management** - Use proper certificate authorities
- **Firewall Rules** - Limit access to necessary ports only
- **Regular Updates** - Keep KMS server updated with security patches

### Key Security
- **Key Rotation** - Implement regular key rotation policies
- **Access Control** - Use fine-grained access permissions
- **Audit Logging** - Enable comprehensive audit trails
- **Backup Encryption** - Encrypt key backups with separate keys

### Database Security
- **Encryption at Rest** - Encrypt database storage
- **Connection Security** - Use encrypted database connections
- **Access Control** - Limit database user permissions
- **Regular Backups** - Implement secure backup procedures

### FIPS Compliance
- **FIPS Mode** - Enable FIPS 140-2 validated algorithms only
- **Hardware Validation** - Use FIPS-validated hardware
- **Compliance Auditing** - Regular FIPS compliance audits
- **Documentation** - Maintain compliance documentation

## Performance Optimization

### Server Performance
- **Database Tuning** - Optimize database settings for KMS workload
- **Connection Pooling** - Configure appropriate connection pools
- **Memory Allocation** - Allocate sufficient memory for key cache
- **Storage Performance** - Use high-IOPS storage for database

### Cryptographic Performance
- **Hardware Acceleration** - Use AES-NI and other CPU features
- **Algorithm Selection** - Choose appropriate algorithms for use case
- **Key Caching** - Configure key caching for frequently used keys
- **Batch Operations** - Use bulk operations where possible

### Network Performance
- **TLS Optimization** - Configure TLS for performance
- **Load Balancing** - Distribute load across multiple instances
- **CDN Integration** - Use CDN for geographically distributed access
- **Connection Reuse** - Enable HTTP/2 and connection pooling

## Backup and Recovery

### Backup Procedure
```bash
# Stop KMS service
systemctl stop cosmian-kms

# Backup database (SQLite)
cp /var/lib/kms/kms.db /backup/kms-db-$(date +%Y%m%d).db

# Backup database (PostgreSQL)
pg_dump -h host -U user database > /backup/kms-db-$(date +%Y%m%d).sql

# Backup configuration and keys
tar -czf /backup/kms-config-$(date +%Y%m%d).tar.gz \
    /etc/kms/ \
    /var/lib/kms/keys/ \
    /var/lib/kms/certificates/

# Restart service
systemctl start cosmian-kms
```

### Recovery Procedure
1. **Stop KMS service**
2. **Restore database** from backup
3. **Restore configuration** and key files
4. **Verify file permissions** and ownership
5. **Start KMS service**
6. **Test cryptographic operations**
7. **Verify audit logs**

### Disaster Recovery
- **Geographic Replication** - Maintain replicas in different regions
- **Cross-Platform Backups** - Store backups on different platforms
- **Recovery Testing** - Regularly test recovery procedures
- **Documentation** - Maintain detailed recovery procedures

## Integration Examples

### Application Integration
```python
# Python SDK example
from cosmian_kms import KmsClient

# Initialize client
client = KmsClient(server_url="https://kms.company.com:9998")

# Authenticate with JWT
client.authenticate(jwt_token="your-jwt-token")

# Create and use key
key_id = client.create_symmetric_key(algorithm="AES", key_length=256)
plaintext = b"sensitive data"
ciphertext = client.encrypt(key_id, plaintext)
decrypted = client.decrypt(key_id, ciphertext)
```

### REST API Integration
```bash
# Create key via REST API
curl -X POST https://kms.company.com:9998/keys \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm": "AES",
    "key_length": 256,
    "key_id": "app-encryption-key"
  }'

# Encrypt data
curl -X POST https://kms.company.com:9998/encrypt \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key_id": "app-encryption-key",
    "plaintext": "c2Vuc2l0aXZlIGRhdGE="
  }'
```

### Monitoring Integration
```bash
# Prometheus metrics
curl http://localhost:9998/metrics

# Custom health check
#!/bin/bash
HEALTH=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:9998/health)
if [ $HEALTH -ne 200 ]; then
    echo "KMS is unhealthy: HTTP $HEALTH"
    # Send alert
fi
```

## Resources

- **Official Documentation**: [docs.cosmian.com](https://docs.cosmian.com)
- **GitHub Repository**: [Cosmian/kms](https://github.com/Cosmian/kms)
- **Support**: [support.cosmian.com](https://support.cosmian.com)
- **SDK Downloads**: [package.cosmian.com](https://package.cosmian.com)