Encryption & Secrets
Relevant source files
The following files were used as context for generating this wiki page:
The Harbor Satellite project implements a robust security layer focused on protecting configuration data, verifying identities, and securing communication between edge Satellites and the central Ground Control service. This system encompasses cryptographic primitives for data-at-rest encryption, SPIFFE-based zero-trust identity for data-in-transit, and multi-layered authentication mechanisms.
The security architecture ensures that sensitive credentials, such as registry passwords and access tokens, are never stored in plaintext on edge devices. By leveraging device-specific fingerprints and industry-standard algorithms like AES-GCM and Argon2id, the system provides strong guarantees for confidentiality and integrity in potentially hostile edge environments.
Cryptographic Providers
The project uses a provider-based pattern for cryptographic operations, allowing for different implementations based on build tags or security requirements.
AES Provider
The primary implementation is the AESProvider, which utilizes AES-256-GCM for encryption and Argon2id for key derivation. This provider follows OWASP-recommended parameters to ensure high resistance against brute-force attacks.
| Parameter | Value | Description |
|---|---|---|
| AES Key Size | 32 bytes | AES-256 requirement |
| Nonce Size | 12 bytes | Standard GCM nonce length |
| Argon2 Time | 3 | Iterations for key derivation |
| Argon2 Memory | 64 MB | Memory usage for Argon2id |
| Argon2 Threads | 4 | Parallelism for Argon2id |
Sources: internal/crypto/aes_provider.go:16-25
Key Derivation and Hashing
Key derivation is performed using the DeriveKey function, which takes an input (often a device fingerprint) and a salt to produce a deterministic key of a specified length. The system also supports SHA-256 hashing for data integrity checks and ECDSA for signing and verifying data.
Sources: internal/crypto/aes_provider.go:81-105, internal/crypto/aes_provider.go:138-141
Secure Configuration Management
The ConfigEncryptor handles the encryption and decryption of satellite configuration files, ensuring that the config.json remains unreadable to unauthorized users on the edge node.
Encryption Flow
When a configuration is saved, the system derives a unique key using a combination of a random salt and the unique identity of the device (fingerprint).
The EncryptedConfig structure wraps the sensitive data with necessary metadata:
- Version: Format version (currently 1).
- Salt: The salt used for that specific encryption operation.
- Encrypted: The actual ciphertext.
Sources: internal/secure/config.go:42-63, internal/secure/config.go:119-129
Device-Bound Security
Encryption is tied to the hardware via the identity.DeviceIdentity interface. This prevents a configuration file from being moved to and decrypted on a different device, as the key derivation relies on a hardware-specific fingerprint.
Sources: internal/secure/config.go:140-151
Authentication & Identity
The system supports multiple authentication methods for both administrative access and Satellite-to-Ground-Control communication.
Middleware and Access Control
Ground Control employs an AuthMiddleware that evaluates requests using two primary methods:
- Bearer Tokens: Validated against active sessions in the database.
- Basic Auth: Fallback for administrative or automated requests.
SPIFFE Identity
For production environments, the project recommends SPIFFE/SPIRE for zero-trust identity. When enabled, Satellites use X.509 SVIDs (SPIFFE Verifiable Identity Documents) for mutual TLS (mTLS) authentication.
| Feature | Description |
|---|---|
| Enabled Check | Verified via cm.config.AppConfig.SPIFFE.Enabled |
| SVID Usage | Provides cryptographic identity for mTLS |
| Rotation | Managed automatically by SPIRE agents |
Sources: pkg/config/getters.go:148-156, deploy/quickstart/README.md:9-15
Configuration Validation
To prevent insecure setups, the ValidateAndEnforceDefaults function inspects security-related configuration fields.
- TLS Validation: Ensures that if a certificate is provided, a corresponding private key is also present. It also checks for the existence of CA files.
- Unsecure Mode: Users can explicitly allow unsecure connections via the
USE_UNSECUREenvironment variable or theuse_unsecureconfig field, though this triggers a warning. - File Permissions: Files encrypted via
EncryptToFileare written with0600permissions (read/write only by owner).
Sources: pkg/config/validate.go:108-142, internal/secure/config.go:102-108
Conclusion
Harbor Satellite implements a comprehensive security model that integrates hardware-bound encryption for data-at-rest with modern zero-trust identity frameworks for data-in-transit. By abstracting cryptographic operations through a provider interface, the system maintains flexibility while enforcing rigorous security standards for protecting registry credentials and configuration state at the edge.