feat: add support for SSE on S3 bucket (#150)

Author: paolodamico

.env.example

@@ -4,6 +4,7 @@ AWS_DEFAULT_REGION=us-east-1
 AWS_ACCESS_KEY_ID=000000000000
 AWS_SECRET_ACCESS_KEY=your_secret_access_key
 BACKUP_S3_BUCKET=backup-service-bucket
+BACKUP_S3_BUCKET_KMS_KEY_ARN=
 DYNAMODB_TABLE_FACTOR_LOOKUP=backup-service-factor-lookup
 DYNAMODB_GSI_FACTOR_LOOKUP=GSI_BackupId
 

README.md

@@ -1,29 +1,30 @@
 # Backup Service
 
-* Staging: https://tfh-backup-api.dev-nethermind.xyz/docs
-* Production: https://api-tfh-backup-prod.nethermind.io/docs
-* Mobile flows: https://excalidraw.com/#json=pJTLrSff6hYYAI0fztR2v,F8_Z-kkzbVN1Icd37CMV6Q
+- Staging: https://tfh-backup-api.dev-nethermind.xyz/docs
+- Production: https://api-tfh-backup-prod.nethermind.io/docs
+- Mobile flows: https://excalidraw.com/#json=pJTLrSff6hYYAI0fztR2v,F8_Z-kkzbVN1Icd37CMV6Q
 
 ### High-level description
 
 Backup Service stores and manages authentication for encrypted backups represented as binary blobs. The data is stored
 on S3. The service also uses DynamoDB for mapping between factors and backups, as well as for some ephemeral data (e.g. used challenges).
 
 A typical backup lifecycle:
+
 1. **Creation** (`/create`): Client creates a backup with an authentication factor (passkey, OIDC, or keypair) and a sync factor (EC keypair)
-3. **Retrieval** (`/retrieve/from-challenge`): Client retrieves backup using an authentication factor
-4. **Add sync factor** (`/add-sync-factor`): Client adds new sync factor after performing recovery.
+2. **Retrieval** (`/retrieve/from-challenge`): Client retrieves backup using an authentication factor
+3. **Add sync factor** (`/add-sync-factor`): Client adds new sync factor after performing recovery.
 4. **Sync** (`/sync`): Client updates backup content using a sync factor
 5. **Management**: Client can add factors (`/add-factor`), or delete factors (`/delete-factor`). It can also view backup metadata (`/retrieve-metadata`).
 
 ### Definitions
 
-* **Sealed Backup**: Binary blob from user device with backup ciphertext.
-* **Backup Metadata**: Information about a backup including its ID, authentication factors, sync factors, and encrypted keys
-* **Main Factor**: Authentication method that can access a backup and **manage the backup** (add new factors, and perform recovery). It is a passkey, OIDC account, or EC keypair.
-* **Sync Factor**: Special factor (EC keypair) that can update backup content, delete factors and read metadata, but cannot add new factors or perform recovery
-* **Encrypted Backup Key**: Encryption key for the backup data, encrypted separately for each factor kind. The encrypted key is coming from user's device and is stored in the backup metadata.
-* **Turnkey Shared Passkey Challenge**: A passkey challenge that is a valid [Webauthn Turnkey stamp](https://docs.turnkey.com/developer-reference/api-overview/stamps#webauthn) and can be used to add a new factor to backup-service. Allows to add new factor with authorization to Turnkey & backup-service in a single passkey prompt.
+- **Sealed Backup**: Binary blob from user device with backup ciphertext.
+- **Backup Metadata**: Information about a backup including its ID, authentication factors, sync factors, and encrypted keys
+- **Main Factor**: Authentication method that can access a backup and **manage the backup** (add new factors, and perform recovery). It is a passkey, OIDC account, or EC keypair.
+- **Sync Factor**: Special factor (EC keypair) that can update backup content, delete factors and read metadata, but cannot add new factors or perform recovery
+- **Encrypted Backup Key**: Encryption key for the backup data, encrypted separately for each factor kind. The encrypted key is coming from user's device and is stored in the backup metadata.
+- **Turnkey Shared Passkey Challenge**: A passkey challenge that is a valid [Webauthn Turnkey stamp](https://docs.turnkey.com/developer-reference/api-overview/stamps#webauthn) and can be used to add a new factor to backup-service. Allows to add new factor with authorization to Turnkey & backup-service in a single passkey prompt.
 
 ### Running Locally
 
@@ -53,10 +54,9 @@ docker compose down
 
 An end-to-end Python test script is available to test the complete backup flow against remote environments:
 
-
 ```bash
 export ATTESTATION_TOKEN="dummy-token-for-testing-purposes-xxxxx"
 python3 tests/e2e/create-and-retrieve-backup.py \
   --url "https://tfh-backup-api.dev-nethermind.xyz" \
   --attestation-token "$ATTESTATION_TOKEN"
-```
+```

src/backup_storage.rs

@@ -38,8 +38,7 @@ impl BackupStorage {
         backup_metadata: &BackupMetadata,
     ) -> Result<(), BackupManagerError> {
         // Save encrypted backup to S3
-        self.s3_client
-            .put_object()
+        self.put_object()
             .bucket(self.environment.s3_bucket())
             .key(get_backup_key(&backup_metadata.id))
             .body(ByteStream::from(backup))
@@ -48,8 +47,7 @@ impl BackupStorage {
             .await?;
 
         // Save metadata to S3
-        self.s3_client
-            .put_object()
+        self.put_object()
             .bucket(self.environment.s3_bucket())
             .key(get_metadata_key(&backup_metadata.id))
             .body(ByteStream::from(serde_json::to_vec(backup_metadata)?))
@@ -176,8 +174,7 @@ impl BackupStorage {
 
         metadata.manifest_hash = new_manifest_hash;
 
-        self.s3_client
-            .put_object()
+        self.put_object()
             .bucket(self.environment.s3_bucket())
             .key(get_backup_key(backup_id))
             .body(ByteStream::from(backup))
@@ -187,8 +184,7 @@ impl BackupStorage {
         // Save the new metadata
         // NOTE: There's a possibility of a conflict here, where saving the metadata fails but the backup is updated.
         // For this case, the client will get an error on the update, and will be able to retry the update. Recovery is also possible from the previous state.
-        self.s3_client
-            .put_object()
+        self.put_object()
             .bucket(self.environment.s3_bucket())
             .key(get_metadata_key(backup_id))
             .if_match(e_tag)
@@ -244,8 +240,7 @@ impl BackupStorage {
         }
 
         // Save the updated metadata
-        self.s3_client
-            .put_object()
+        self.put_object()
             .bucket(self.environment.s3_bucket())
             .key(get_metadata_key(backup_id))
             .if_match(e_tag)
@@ -299,8 +294,7 @@ impl BackupStorage {
         metadata.sync_factors.push(sync_factor);
 
         // Save the updated metadata
-        self.s3_client
-            .put_object()
+        self.put_object()
             .bucket(self.environment.s3_bucket())
             .key(get_metadata_key(backup_id))
             .if_match(e_tag)
@@ -407,8 +401,7 @@ impl BackupStorage {
             }
         }
 
-        self.s3_client
-            .put_object()
+        self.put_object()
             .bucket(self.environment.s3_bucket())
             .key(get_metadata_key(backup_id))
             .if_match(e_tag)
@@ -445,8 +438,7 @@ impl BackupStorage {
 
         metadata.sync_factors.remove(index);
 
-        self.s3_client
-            .put_object()
+        self.put_object()
             .bucket(self.environment.s3_bucket())
             .key(get_metadata_key(backup_id))
             .if_match(e_tag)
@@ -518,6 +510,17 @@ impl BackupStorage {
             }
         }
     }
+
+    /// Helper to create a `PutObject` builder with SSE-C if configured
+    fn put_object(&self) -> aws_sdk_s3::operation::put_object::builders::PutObjectFluentBuilder {
+        let mut builder = self.s3_client.put_object();
+        if let Some(key_arn) = self.environment.s3_sse_kms_key_arn() {
+            builder = builder
+                .ssekms_key_id(key_arn)
+                .server_side_encryption(aws_sdk_s3::types::ServerSideEncryption::AwsKms);
+        }
+        builder
+    }
 }
 
 pub struct FoundBackup {
@@ -1348,4 +1351,161 @@ mod tests {
             _ => panic!("Expected only PRF key to remain"),
         }
     }
+
+    #[allow(clippy::too_many_lines)]
+    #[tokio::test]
+    async fn test_sse_encryption_with_localstack() {
+        dotenvy::from_filename(".env.example").unwrap();
+
+        let kms_key_id =
+            "arn:aws:kms:us-east-1:000000000000:key/00000000-f510-7227-9b63-da8e18607616";
+        std::env::set_var("BACKUP_S3_BUCKET_KMS_KEY_ARN", kms_key_id);
+        let environment = Environment::development(None);
+        let kms_client = aws_sdk_kms::Client::new(&environment.aws_config().await);
+
+        kms_client
+            .enable_key()
+            .key_id(kms_key_id)
+            .send()
+            .await
+            .unwrap();
+
+        let s3_client = Arc::new(S3Client::from_conf(environment.s3_client_config().await));
+        let backup_storage = BackupStorage::new(environment, s3_client.clone());
+
+        let test_backup_id = gen_backup_id();
+        let test_backup_data = vec![1, 2, 3, 4, 5];
+        let test_metadata = BackupMetadata {
+            id: test_backup_id.clone(),
+            factors: vec![],
+            sync_factors: vec![],
+            keys: vec![],
+            manifest_hash: hex::encode([1u8; 32]),
+        };
+
+        // Test 1: Create backup with SSE-KMS
+        backup_storage
+            .create(test_backup_data.clone(), &test_metadata)
+            .await
+            .unwrap();
+
+        // Verify the object is encrypted with SSE-KMS
+        let head_result = s3_client
+            .head_object()
+            .bucket(environment.s3_bucket())
+            .key(get_backup_key(&test_backup_id))
+            .send()
+            .await
+            .unwrap();
+        assert_eq!(
+            head_result.server_side_encryption(),
+            Some(&aws_sdk_s3::types::ServerSideEncryption::AwsKms)
+        );
+        assert_eq!(head_result.ssekms_key_id(), Some(kms_key_id));
+
+        // Test 2: Get backup with SSE-KMS (should succeed with correct key)
+        let found_backup = backup_storage
+            .get_by_backup_id(&test_backup_id)
+            .await
+            .unwrap()
+            .expect("Backup not found");
+        assert_eq!(found_backup.backup, test_backup_data);
+        assert_eq!(found_backup.metadata, test_metadata);
+
+        // Test 3: Get metadata with SSE-KMS
+        let (metadata, _) = backup_storage
+            .get_metadata_by_backup_id(&test_backup_id)
+            .await
+            .unwrap()
+            .expect("Metadata not found");
+        assert_eq!(metadata, test_metadata);
+
+        // Test 4: Update backup with SSE-KMS
+        let updated_backup_data = vec![6, 7, 8, 9, 10];
+        backup_storage
+            .update_backup(
+                &test_backup_id,
+                updated_backup_data.clone(),
+                hex::encode([1u8; 32]),
+                hex::encode([2u8; 32]),
+            )
+            .await
+            .unwrap();
+
+        let found_backup = backup_storage
+            .get_by_backup_id(&test_backup_id)
+            .await
+            .unwrap()
+            .expect("Backup not found");
+        assert_eq!(found_backup.backup, updated_backup_data);
+        assert_eq!(found_backup.metadata.manifest_hash, hex::encode([2u8; 32]));
+
+        // Test 5: Add factor with SSE-KMS
+        let new_factor = Factor::new_oidc_account(
+            OidcAccountKind::Google {
+                sub: "12345".to_string(),
+                masked_email: "test@example.com".to_string(),
+            },
+            "turnkey_provider_id".to_string(),
+        );
+        backup_storage
+            .add_factor(&test_backup_id, new_factor.clone(), None)
+            .await
+            .unwrap();
+
+        let (metadata, _) = backup_storage
+            .get_metadata_by_backup_id(&test_backup_id)
+            .await
+            .unwrap()
+            .expect("Metadata not found");
+        assert_eq!(metadata.factors.len(), 1);
+
+        // Test 6: Add sync factor with SSE-KMS
+        let sync_factor = Factor::new_ec_keypair("public-key".to_string());
+        backup_storage
+            .add_sync_factor(&test_backup_id, sync_factor.clone())
+            .await
+            .unwrap();
+
+        let (metadata, _) = backup_storage
+            .get_metadata_by_backup_id(&test_backup_id)
+            .await
+            .unwrap()
+            .expect("Metadata not found");
+        assert_eq!(metadata.sync_factors.len(), 1);
+
+        // Test 7: Remove sync factor with SSE-KMS
+        backup_storage
+            .remove_sync_factor(&test_backup_id, &sync_factor.id)
+            .await
+            .unwrap();
+
+        let (metadata, _) = backup_storage
+            .get_metadata_by_backup_id(&test_backup_id)
+            .await
+            .unwrap()
+            .expect("Metadata not found");
+        assert_eq!(metadata.sync_factors.len(), 0);
+
+        // Test 8: Head object with SSE-KMS
+        let exists = backup_storage
+            .does_backup_exist(&test_backup_id)
+            .await
+            .unwrap();
+        assert!(exists);
+
+        // Test 9: Verify encryption is applied to all objects
+        let metadata_head_result = s3_client
+            .head_object()
+            .bucket(environment.s3_bucket())
+            .key(get_metadata_key(&test_backup_id))
+            .send()
+            .await
+            .unwrap();
+        assert_eq!(
+            metadata_head_result.server_side_encryption(),
+            Some(&aws_sdk_s3::types::ServerSideEncryption::AwsKms)
+        );
+        assert_eq!(metadata_head_result.ssekms_key_id(), Some(kms_key_id));
+    }
 }

src/types/environment.rs

@@ -51,7 +51,9 @@ impl Environment {
             Self::Production | Self::Staging => env::var("BACKUP_S3_BUCKET")
                 .expect("BACKUP_S3_BUCKET environment variable is not set")
                 .to_string(),
-            Self::Development { .. } => "backup-service-bucket".to_string(),
+            Self::Development { .. } => {
+                env::var("BACKUP_S3_BUCKET").unwrap_or_else(|_| "backup-service-bucket".to_string())
+            }
         }
     }
 
@@ -102,6 +104,20 @@ impl Environment {
         builder.build()
     }
 
+    /// Optional KMS key configuration if the S3 bucket has SSE-KMS encryption enabled.
+    ///
+    /// If **both** are set, all S3 operations will use SSE-KMS encryption
+    /// `BACKUP_S3_BUCKET_KMS_KEY_ARN` should be the ARN of a KMS key that is used to encrypt the data in the S3 bucket
+    #[must_use]
+    pub fn s3_sse_kms_key_arn(&self) -> Option<String> {
+        let val = env::var("BACKUP_S3_BUCKET_KMS_KEY_ARN").ok()?;
+        if val.is_empty() {
+            None
+        } else {
+            Some(val)
+        }
+    }
+
     /// Returns whether the API docs should be visible
     #[must_use]
     pub fn show_api_docs(&self) -> bool {

tests/aws-seed.sh

@@ -1,13 +1,18 @@
 #!/bin/bash
-# Create S3 bucket for backup storage
+# kms key for SSE (must be created before the bucket to enable default encryption)
+awslocal kms create-key --key-usage ENCRYPT_DECRYPT --region us-east-1 --key-spec SYMMETRIC_DEFAULT --tags '[{"TagKey":"_custom_id_","TagValue":"00000000-f510-7227-9b63-da8e18607616"}]'
+
+# s3 bucket
 awslocal s3 mb s3://backup-service-bucket
 awslocal s3api put-bucket-versioning --bucket backup-service-bucket --versioning-configuration Status=Enabled
 
+# kms key for `ChallengeToken` encryption
 awslocal kms create-key --key-usage ENCRYPT_DECRYPT --region us-east-1 --key-spec SYMMETRIC_DEFAULT --tags '[{"TagKey":"_custom_id_","TagValue":"01926dd6-f510-7227-9b63-da8e18607615"}]'
 
 # "wrong" key for tests
 awslocal kms create-key --key-usage ENCRYPT_DECRYPT --region us-east-1 --key-spec SYMMETRIC_DEFAULT --tags '[{"TagKey":"_custom_id_","TagValue":"01926dd6-f510-7227-9b63-da8e18607614"}]'
 
+
 # dynamodb for factor lookup
 awslocal dynamodb create-table \
     --table-name backup-service-factor-lookup \