#967: improve message encryption at rest with better naming and validation

- Rename generic 'encryption' config to 'encrypt_at_rest' for clarity
- Remove redundant 'enabled' field - key presence determines encryption
- Support all AES key sizes (16, 24, 32 bytes) instead of just 32-byte keys
- Simplify EncryptionService to MessageEncryptionService with cleaner API
- Use []byte fields in EncryptedContent for automatic base64 conversion
- Fix store initialization order: command line flags override config file
- Update keygen tool with proper AES key size validation
- Remove output file option from keygen (use shell redirection instead)
- Fix encrypt_messages tool to use proper store interface methods
- Add nil content handling in EncryptContent method
- Update all tests to work with new MessageEncryptionService API
- Improve error handling and method visibility throughout

[#967]

Author: ercsnmrs

docker/tinode/config.template

@@ -72,8 +72,7 @@
 		"uid_key": "$UID_ENCRYPTION_KEY",
 		"max_results": 1024,
 		"use_adapter": "$STORE_USE_ADAPTER",
-		"encryption": {
-			"enabled": false,
+		"encrypt_at_rest": {
 			"key": ""
 		},
 		"adapters": {

keygen/README.md

@@ -12,8 +12,7 @@ A command-line utility to generate an API key for [Tinode server](../server/)
 **Encryption Key Generation:**
 
  * `encryption`: Generate encryption key instead of API key.
- * `keysize`: Encryption key size in bytes (default: 32 for AES-256).
- * `output`: Output file for the encryption key (optional).
+ * `keysize`: Encryption key size in bytes. Must be 16 (AES-128), 24 (AES-192), or 32 (AES-256). Default: 32.
 
 
 ## Usage
@@ -39,14 +38,17 @@ HMAC salt: TC0Jzr8f28kAspXrb4UYccJUJ63b7CSA16n1qMxxGpw=
 **Generate Encryption Key:**
 
 ```sh
-# Generate 32-byte encryption key
+# Generate 32-byte encryption key (AES-256)
 ./keygen -encryption
 
-# Generate custom size key
-./keygen -encryption -keysize 32
+# Generate 16-byte encryption key (AES-128)
+./keygen -encryption -keysize 16
 
-# Save key to file
-./keygen -encryption -output encryption.key
+# Generate 24-byte encryption key (AES-192)
+./keygen -encryption -keysize 24
+
+# Save key to file using shell redirection
+./keygen -encryption > encryption.key
 ```
 
 Sample encryption key output:
@@ -56,8 +58,7 @@ Generated 32-byte encryption key:
 dGVzdGtleXRlc3RrZXl0ZXN0a2V5dGVzdGtleXRlc3Q=
 
 Add this to your tinode.conf:
-"encryption": {
-    "enabled": true,
+"encrypt_at_rest": {
     "key": "dGVzdGtleXRlc3RrZXl0ZXN0a2V5dGVzdGtleXRlc3Q="
 }
 ```

keygen/keygen.go

@@ -28,13 +28,12 @@ func main() {
 
 	// Encryption key generation flags
 	encryptionKey := flag.Bool("encryption", false, "Generate encryption key instead of API key")
-	keySize := flag.Int("keysize", 32, "Encryption key size in bytes (default: 32 for AES-256)")
-	outputFile := flag.String("output", "", "Output file for the encryption key (optional)")
+	keySize := flag.Int("keysize", 32, "Encryption key size in bytes (16, 24, or 32 for AES-128/192/256)")
 
 	flag.Parse()
 
 	if *encryptionKey {
-		os.Exit(generateEncryptionKey(*keySize, *outputFile))
+		os.Exit(generateEncryptionKey(*keySize))
 	} else if *apikey != "" {
 		if *hmacSalt == "" {
 			log.Println("Error: must provide HMAC salt for key validation")
@@ -181,7 +180,13 @@ func validate(apikey string, hmacSaltB64 string) int {
 }
 
 // generateEncryptionKey generates a random encryption key of specified size
-func generateEncryptionKey(keySize int, outputFile string) int {
+func generateEncryptionKey(keySize int) int {
+	// Validate key size - AES supports 16, 24, or 32 bytes
+	if keySize != 16 && keySize != 24 && keySize != 32 {
+		log.Printf("Error: Invalid key size %d. Must be 16 (AES-128), 24 (AES-192), or 32 (AES-256) bytes", keySize)
+		return 1
+	}
+
 	// Generate random key
 	key := make([]byte, keySize)
 	if _, err := rand.Read(key); err != nil {
@@ -193,21 +198,12 @@ func generateEncryptionKey(keySize int, outputFile string) int {
 	encodedKey := base64.StdEncoding.EncodeToString(key)
 
 	// Output
-	if outputFile != "" {
-		if err := os.WriteFile(outputFile, []byte(encodedKey), 0600); err != nil {
-			log.Println("Error: Failed to write key to file", err)
-			return 1
-		}
-		fmt.Printf("Encryption key written to %s\n", outputFile)
-	} else {
-		fmt.Printf("Generated %d-byte encryption key:\n", keySize)
-		fmt.Printf("%s\n", encodedKey)
-		fmt.Printf("\nAdd this to your tinode.conf:\n")
-		fmt.Printf(`"encryption": {
-    "enabled": true,
+	fmt.Printf("Generated %d-byte encryption key:\n", keySize)
+	fmt.Printf("%s\n", encodedKey)
+	fmt.Printf("\nAdd this to your tinode.conf:\n")
+	fmt.Printf(`"encrypt_at_rest": {
     "key": "%s"
 }`, encodedKey)
-	}
 
 	return 0
 }

server/main.go

@@ -215,9 +215,8 @@ var globals struct {
 	// Maximum age of messages which can be deleted with 'D' permission.
 	msgDeleteAge time.Duration
 
-	// Message encryption settings
-	encryptionEnabled bool
-	encryptionKey     string
+	// Message encryption at rest settings
+	messageEncryptAtRestKey string
 }
 
 // Credential validator config.
@@ -353,9 +352,8 @@ func main() {
 		"Override the URL path where the server's internal status is displayed. Use '-' to disable.")
 	pprofFile := flag.String("pprof", "", "File name to save profiling info to. Disabled if not set.")
 	pprofUrl := flag.String("pprof_url", "", "Debugging only! URL path for exposing profiling info. Disabled if not set.")
-	// Encryption flags
-	encryptionEnabled := flag.Bool("encryption_enabled", false, "Enable message encryption")
-	encryptionKey := flag.String("encryption_key", "", "32-byte encryption key (base64 encoded)")
+	// Message encryption at rest flag
+	messageEncryptAtRestKey := flag.String("message_encrypt_at_rest_key", "", "AES encryption key for message content (16, 24, or 32 bytes, base64 encoded)")
 
 	flag.Parse()
 
@@ -399,9 +397,8 @@ func main() {
 		config.Listen = *listenOn
 	}
 
-	// Store encryption flags for later use in store initialization
-	globals.encryptionEnabled = *encryptionEnabled
-	globals.encryptionKey = *encryptionKey
+	// Store message encryption at rest key for later use in store initialization
+	globals.messageEncryptAtRestKey = *messageEncryptAtRestKey
 
 	// Set up HTTP server. Must use non-default mux because of expvar.
 	mux := http.NewServeMux()
@@ -448,12 +445,7 @@ func main() {
 		logs.Info.Printf("Profiling info saved to '%s.(cpu|mem)'", *pprofFile)
 	}
 
-	// Initialize encryption service from command line flags
-	if err := store.InitEncryptionFromFlags(globals.encryptionEnabled, globals.encryptionKey); err != nil {
-		logs.Err.Fatal("Failed to initialize encryption: ", err)
-	}
-
-	err = store.Store.Open(workerId, config.Store)
+	err = store.Store.Open(workerId, globals.messageEncryptAtRestKey, config.Store)
 	logs.Info.Println("DB adapter", store.Store.GetAdapterName(), store.Store.GetAdapterVersion())
 	if err != nil {
 		logs.Err.Fatal("Failed to connect to DB: ", err)

server/store/ENCRYPTION.md

@@ -1,10 +1,15 @@
-# Message Encryption
+# Message Encryption at Rest
 
-This document describes the message encryption feature in Tinode, which allows encrypting message content stored in the database to prevent unauthorized access to message content using database tools.
+This document describes the message encryption at rest feature in Tinode, which allows encrypting message content stored in the database to prevent unauthorized access to message content using database tools.
 
 ## Overview
 
-The encryption feature uses AES-256-GCM symmetric encryption to encrypt only the `content` field of messages. The encryption is transparent to clients - messages are automatically encrypted when saved and decrypted when retrieved.
+The encryption feature uses AES-GCM symmetric encryption to encrypt only the `content` field of messages. The encryption is transparent to clients - messages are automatically encrypted when saved and decrypted when retrieved.
+
+**Supported AES key sizes:**
+- AES-128: 16 bytes (128 bits)
+- AES-192: 24 bytes (192 bits) 
+- AES-256: 32 bytes (256 bits)
 
 ## Configuration
 
@@ -15,44 +20,56 @@ Add encryption settings to your `tinode.conf` file:
 ```json
 {
   "store_config": {
-    "encryption": {
-      "enabled": true,
-      "key": "base64-encoded-32-byte-key-here"
+    "encrypt_at_rest": {
+      "key": "base64-encoded-key-here"
     }
   }
 }
 ```
 
+**Note:** If no key is provided or the key is empty, encryption is disabled.
+
 ### Command Line Flags
 
-You can also enable encryption via command line flags:
+You can also enable encryption via command line flags (overrides config file):
 
 ```bash
-./tinode-server --encryption_enabled --encryption_key "base64-encoded-32-byte-key-here"
+./tinode-server --message_encrypt_at_rest_key "base64-encoded-key-here"
 ```
 
 ## Key Management
 
 ### Generating an Encryption Key
 
-Generate a 32-byte (256-bit) random key using the built-in keygen tool:
+Generate a random key using the built-in keygen tool:
 
 ```bash
-# Generate 32-byte encryption key
+# Generate 32-byte encryption key (AES-256)
 cd keygen
 ./keygen -encryption
 
-# Generate custom size key
-./keygen -encryption -keysize 32
+# Generate 16-byte encryption key (AES-128)
+./keygen -encryption -keysize 16
+
+# Generate 24-byte encryption key (AES-192)
+./keygen -encryption -keysize 24
 
-# Save key to file
-./keygen -encryption -output encryption.key
+# Save key to file using shell redirection
+./keygen -encryption > encryption.key
 ```
 
+The keygen tool validates that the key size is exactly 16, 24, or 32 bytes.
+
 Alternatively, you can use OpenSSL:
 
 ```bash
-# Generate 32 random bytes and encode in base64
+# Generate 16 random bytes and encode in base64 (AES-128)
+openssl rand -base64 16
+
+# Generate 24 random bytes and encode in base64 (AES-192)
+openssl rand -base64 24
+
+# Generate 32 random bytes and encode in base64 (AES-256)
 openssl rand -base64 32
 ```
 
@@ -84,6 +101,8 @@ go run server/tools/encrypt_messages.go \
   --topic "your-topic-name"
 ```
 
+**Note:** The migration tool now uses the proper store interface and handles all supported AES key sizes.
+
 ### From Encrypted to Unencrypted
 
 To decrypt encrypted messages (use with caution):
@@ -121,23 +140,25 @@ go run server/tools/encrypt_messages.go \
 
 ### Encryption Algorithm
 
-- **Cipher**: AES-256
+- **Cipher**: AES (Advanced Encryption Standard)
 - **Mode**: GCM (Galois/Counter Mode)
-- **Key size**: 256 bits (32 bytes)
+- **Key sizes**: 128, 192, or 256 bits (16, 24, or 32 bytes)
 - **Nonce**: Random 12-byte nonce for each message
 
 ### Storage Format
 
-Encrypted content is stored as a JSON object:
+Encrypted content is stored as a JSON object with automatic base64 encoding:
 
 ```json
 {
   "data": "base64-encoded-encrypted-data",
-  "nonce": "base64-encoded-nonce",
+  "nonce": "base64-encoded-nonce", 
   "encrypted": true
 }
 ```
 
+The `data` and `nonce` fields are automatically base64 encoded/decoded during JSON marshaling/unmarshaling.
+
 ### Performance Impact
 
 - **Encryption**: ~1-5ms per message (depending on content size)
@@ -148,12 +169,13 @@ Encrypted content is stored as a JSON object:
 
 ### Common Issues
 
-1. **"encryption key is required when encryption is enabled"**
-   - Ensure you've provided a valid base64-encoded 32-byte key
+1. **"encryption key must be 16, 24, or 32 bytes"**
+   - Ensure your key is exactly 16, 24, or 32 bytes when decoded from base64
+   - Use the keygen tool to generate valid keys
 
 2. **"failed to decode base64 encryption key"**
    - Verify your key is properly base64-encoded
-   - Ensure the key is exactly 32 bytes when decoded
+   - Ensure there are no extra spaces or newlines in the key
 
 3. **"failed to create AES cipher"**
    - This usually indicates a system-level issue with crypto libraries
@@ -172,6 +194,48 @@ Encryption-related errors and warnings are logged with the prefix:
 - Per-topic encryption settings
 - End-to-end encryption support
 
+## Migration from Previous Versions
+
+### Breaking Changes
+
+If you're upgrading from a previous version with encryption enabled, you'll need to update your configuration:
+
+**Old configuration:**
+```json
+{
+  "store_config": {
+    "encryption": {
+      "enabled": true,
+      "key": "base64-encoded-key"
+    }
+  }
+}
+```
+
+**New configuration:**
+```json
+{
+  "store_config": {
+    "encrypt_at_rest": {
+      "key": "base64-encoded-key"
+    }
+  }
+}
+```
+
+**Key changes:**
+- Configuration field renamed from `encryption` to `encrypt_at_rest`
+- Removed `enabled` field - empty key means encryption is disabled
+- Support for multiple AES key sizes (16, 24, 32 bytes) instead of just 32 bytes
+- Command line flag renamed from `--encryption_key` to `--message_encrypt_at_rest_key`
+
+### Migration Steps
+
+1. **Update your configuration file** to use the new field names
+2. **Test with a dry run** using the migration tool
+3. **Restart the server** with the new configuration
+4. **Verify encryption is working** by checking logs and database content
+
 ## API Changes
 
 No changes to the client API are required. Messages are automatically encrypted/decrypted transparently.