Immediately after a restore, use the same enc_salt/pw_salt for the next backup.

Co-authored-by: Jordan Rose <[email protected]>

Author: gram-signal

Cargo.lock

@@ -37,7 +37,7 @@ default-members = [
 resolver = "2" # so that our dev-dependency features don't leak into products
 
 [workspace.package]
-version = "0.77.2"
+version = "0.78.0"
 authors = ["Signal Messenger LLC"]
 license = "AGPL-3.0-only"
 rust-version = "1.83.0"

Cargo.toml

@@ -5,7 +5,7 @@
 
 Pod::Spec.new do |s|
   s.name             = 'LibSignalClient'
-  s.version          = '0.77.2'
+  s.version          = '0.78.0'
   s.summary          = 'A Swift wrapper library for communicating with the Signal messaging service.'
 
   s.homepage         = 'https://github.com/signalapp/libsignal'

LibSignalClient.podspec

@@ -1,2 +1,8 @@
-v0.77.2
+v0.78.0
 
+## SVR-B
+
+- Operations have been consistently renamed to `store` and `restore`.
+- `restore` now returns an object containing both the BackupForwardSecrecyToken for decryption, and "secret data" to be used in the first `store` after restoration.
+
+## Other changes

RELEASE_NOTES.md

@@ -16,7 +16,7 @@ plugins {
 }
 
 allprojects {
-    version = "0.77.2"
+    version = "0.78.0"
     group   = "org.signal"
 
     tasks.withType(KotlinCompile).configureEach {

java/build.gradle

@@ -31,7 +31,7 @@ import org.signal.libsignal.messagebackup.BackupKey
  *
  * 1. Create a [Network] instance and get the [SvrB] service via [Network.svrB]
  * 2. Call [SvrB.store]
- *    - Pass the secret data from the last **successful** [SvrB.store] call
+ *    - Pass the `nextBackupSecretData` from the last **successful** [SvrB.store] or [SvrB.restore] call
  *    - If no previous backup exists or the secret data is unavailable, pass `null`
  * 3. Use the returned forward secrecy token to derive encryption keys
  * 4. Encrypt and upload the backup data to the user's remote, off-device storage location, including the
@@ -42,8 +42,8 @@ import org.signal.libsignal.messagebackup.BackupKey
  * ## Secret handling
  *
  * When calling [SvrB.store], the `previousSecretData` parameter
- * must be from the last call to [SvrB.store] that
- * succeeded. The returned secret from a successful `store()` call should
+ * must be from the last call to [SvrB.store] or [SvrB.restore] that
+ * succeeded. The returned secret from a successful `store()` or `restore()` call should
  * be persisted until it is overwritten by the value from a subsequent
  * successful call. The caller should pass `null` as `previousSecretData`
  * only for the very first backup from a device.
@@ -52,9 +52,10 @@ import org.signal.libsignal.messagebackup.BackupKey
  *
  * 1. Create a [Network] instance and get the [SvrB] service via [Network.svrB]
  * 2. Fetch the backup metadata from storage
- * 3. Call [SvrB.fetchForwardSecrecyTokenFromServer] to get the forward secrecy token
+ * 3. Call [SvrB.restore] to get the forward secrecy token
  * 4. Use the token to derive decryption keys
  * 5. Decrypt and restore the backup data
+ * 6. Store the [SvrBRestoreResponse.nextBackupSecretData] locally.
  *
  * ## Usage
  * ```kotlin
@@ -85,9 +86,8 @@ public class SvrB internal constructor(
    *
    * @param backupKey The backup key derived from the Account Entropy Pool (AEP).
    * @param previousSecretData Optional secret data from the most recent previous backup.
-   * **Critical**: This MUST be the [SvrBStoreResponse.nextBackupSecretData] data
-   * from the last [store] whose returned [SvrBStoreResponse.metadata] was
-   * successfully uploaded, and whose `nextBackupSecretData` was persisted.
+   * **Critical**: This MUST be the secret data from the last [store] or [restore]
+   * whose returned `metadata` was successfully uploaded, and whose `nextBackupSecretData` was persisted.
    * If `null`, starts a new chain and renders any prior backups unretrievable; this should
    * only be used for the very first backup from a device.
    * @return a [CompletableFuture] that completes with:
@@ -96,7 +96,6 @@ public class SvrB internal constructor(
    *   - [Result.failure] containing [NetworkException] if the network operation fails (connection, service, or timeout errors)
    *   - [Result.failure] containing [NetworkProtocolException] if there is a protocol error
    *   - [Result.failure] containing [AttestationFailedException] if enclave attestation fails
-   *   - [Result.failure] containing [DataMissingException] if the request fails with MISSING status
    *   - [Result.failure] containing [SvrException] for other SVR request failures
    */
   public fun store(
@@ -117,14 +116,14 @@ public class SvrB internal constructor(
     }
 
     return nativeFuture.thenApply { backupResponseHandle ->
-      val response = BackupResponse(backupResponseHandle)
+      val response = BackupStoreResponse(backupResponseHandle)
       response.guardedMap { _ ->
         SvrBStoreResponse(
           forwardSecrecyToken = BackupForwardSecrecyToken(
-            response.guardedMapChecked(Native::BackupResponse_GetForwardSecrecyToken),
+            response.guardedMapChecked(Native::BackupStoreResponse_GetForwardSecrecyToken),
           ),
-          nextBackupSecretData = response.guardedMapChecked(Native::BackupResponse_GetNextBackupSecretData),
-          metadata = response.guardedMapChecked(Native::BackupResponse_GetOpaqueMetadata),
+          nextBackupSecretData = response.guardedMapChecked(Native::BackupStoreResponse_GetNextBackupSecretData),
+          metadata = response.guardedMapChecked(Native::BackupStoreResponse_GetOpaqueMetadata),
         )
       }
     }.toResultFuture()
@@ -142,6 +141,7 @@ public class SvrB internal constructor(
    * 2. Call this function to retrieve the forward secrecy token from SVR-B
    * 3. Use the token to derive message backup keys
    * 4. Decrypt and restore the backup data
+   * 5. Store the returned [SvrBRestoreResponse.nextBackupSecretData] locally.
    *
    * @param backupKey The backup key derived from the Account Entropy Pool (AEP).
    * @param metadata The metadata that was stored in a header in the backup file during backup creation.
@@ -155,10 +155,10 @@ public class SvrB internal constructor(
    *   - [Result.failure] containing [AttestationFailedException] if enclave attestation fails
    *   - [Result.failure] containing [SvrException] for other SVR request failures
    */
-  public fun fetchForwardSecrecyTokenFromServer(
+  public fun restore(
     backupKey: BackupKey,
     metadata: ByteArray,
-  ): CompletableFuture<Result<BackupForwardSecrecyToken>> {
+  ): CompletableFuture<Result<SvrBRestoreResponse>> {
     val nativeFuture = network.asyncContext.guardedMap { asyncContextHandle ->
       network.connectionManager.guardedMap { connectionManagerHandle ->
         Native.SecureValueRecoveryForBackups_RestoreBackupFromServer(
@@ -172,20 +172,39 @@ public class SvrB internal constructor(
       }
     }
 
-    return nativeFuture.thenApply { bytes ->
-      BackupForwardSecrecyToken(bytes)
+    return nativeFuture.thenApply { backupResponseHandle ->
+      val response = BackupRestoreResponse(backupResponseHandle)
+      response.guardedMap { _ ->
+        SvrBRestoreResponse(
+          forwardSecrecyToken = BackupForwardSecrecyToken(
+            response.guardedMapChecked(Native::BackupRestoreResponse_GetForwardSecrecyToken),
+          ),
+          nextBackupSecretData = response.guardedMapChecked(Native::BackupRestoreResponse_GetNextBackupSecretData),
+        )
+      }
     }.toResultFuture()
   }
 }
 
 /**
  * Native handle wrapper for backup response from the store operation.
  */
-private class BackupResponse internal constructor(
+private class BackupStoreResponse internal constructor(
+  nativeHandle: Long,
+) : NativeHandleGuard.SimpleOwner(nativeHandle) {
+  override fun release(nativeHandle: Long) {
+    Native.BackupStoreResponse_Destroy(nativeHandle)
+  }
+}
+
+/**
+ * Native handle wrapper for backup response from the restore operation.
+ */
+private class BackupRestoreResponse internal constructor(
   nativeHandle: Long,
 ) : NativeHandleGuard.SimpleOwner(nativeHandle) {
   override fun release(nativeHandle: Long) {
-    Native.BackupResponse_Destroy(nativeHandle)
+    Native.BackupRestoreResponse_Destroy(nativeHandle)
   }
 }
 
@@ -226,3 +245,31 @@ public data class SvrBStoreResponse(
    */
   public val metadata: ByteArray,
 )
+
+/**
+ * The result of restoring a backup.
+ *
+ * This context contains all the necessary components to decrypt a backup using a
+ * key derived from both the user's Account Entropy Pool and the SVR-B-protected
+ * Forward Secrecy Token.
+ *
+ * @see [BackupForwardSecrecyToken]
+ */
+public data class SvrBRestoreResponse(
+  /**
+   * The forward secrecy token used to derive [MessageBackupKey] instances.
+   *
+   * This token provides forward secrecy guarantees by ensuring that compromise of the backup key
+   * alone is insufficient to decrypt backups. Each backup is protected by a value stored on
+   * the SVR-B server that must be retrieved during restoration.
+   */
+  public val forwardSecrecyToken: BackupForwardSecrecyToken,
+
+  /**
+   * Opaque value that must be persisted and provided to the next call to [SvrB.store].
+   *
+   * See the [SvrB] documentation for lifecycle and persistence handling
+   * for this value.
+   */
+  public val nextBackupSecretData: ByteArray,
+)

java/client/src/main/java/org/signal/libsignal/net/SvrB.kt

@@ -119,17 +119,17 @@ class SecureValueRecoveryBackupTest {
     val firstSecretData = firstResponse.nextBackupSecretData
     assertFalse(firstSecretData.isEmpty())
 
-    val firstRestoreResult = svrB.fetchForwardSecrecyTokenFromServer(
+    val firstRestoreResult = svrB.restore(
       testBackupKey,
       firstResponse.metadata,
     ).get(ASYNC_TIMEOUT_SECONDS, TimeUnit.SECONDS)
 
     assertTrue("First restore should succeed", firstRestoreResult.isSuccess)
-    val restoredFirstToken = firstRestoreResult.getOrThrow()
-    assertNotNull("Restored first token should not be null", restoredFirstToken)
+    val restoredFirst = firstRestoreResult.getOrThrow()
+    assertNotNull("Restored first token should not be null", restoredFirst)
 
     val firstTokenBytes = firstToken.serialize()
-    val restoredFirstTokenBytes = restoredFirstToken.serialize()
+    val restoredFirstTokenBytes = restoredFirst.forwardSecrecyToken.serialize()
     assertTrue(
       "Restored first token should match stored token",
       firstTokenBytes.contentEquals(restoredFirstTokenBytes),
@@ -149,17 +149,17 @@ class SecureValueRecoveryBackupTest {
     val secondSecretData = secondResponse.nextBackupSecretData
     assertFalse(secondSecretData.isEmpty())
 
-    val secondRestoreResult = svrB.fetchForwardSecrecyTokenFromServer(
+    val secondRestoreResult = svrB.restore(
       testBackupKey,
       secondResponse.metadata,
     ).get(ASYNC_TIMEOUT_SECONDS, TimeUnit.SECONDS)
 
     assertTrue("Second restore should succeed", secondRestoreResult.isSuccess)
-    val restoredSecondToken = secondRestoreResult.getOrThrow()
-    assertNotNull("Restored second token should not be null", restoredSecondToken)
+    val restoredSecond = secondRestoreResult.getOrThrow()
+    assertNotNull("Restored second token should not be null", restoredSecond)
 
     val secondTokenBytes = secondToken.serialize()
-    val restoredSecondTokenBytes = restoredSecondToken.serialize()
+    val restoredSecondTokenBytes = restoredSecond.forwardSecrecyToken.serialize()
     assertTrue(
       "Restored second token should match stored token",
       secondTokenBytes.contentEquals(restoredSecondTokenBytes),

java/client/src/test/java/org/signal/libsignal/net/SecureValueRecoveryBackupTest.kt

@@ -206,10 +206,14 @@ private Native() {}
   public static native byte[] BackupKey_DeriveMediaId(byte[] backupKey, String mediaName);
   public static native byte[] BackupKey_DeriveThumbnailTransitEncryptionKey(byte[] backupKey, byte[] mediaId);
 
-  public static native void BackupResponse_Destroy(long handle);
-  public static native byte[] BackupResponse_GetForwardSecrecyToken(long response) throws Exception;
-  public static native byte[] BackupResponse_GetNextBackupSecretData(long response);
-  public static native byte[] BackupResponse_GetOpaqueMetadata(long response) throws Exception;
+  public static native void BackupRestoreResponse_Destroy(long handle);
+  public static native byte[] BackupRestoreResponse_GetForwardSecrecyToken(long response) throws Exception;
+  public static native byte[] BackupRestoreResponse_GetNextBackupSecretData(long response);
+
+  public static native void BackupStoreResponse_Destroy(long handle);
+  public static native byte[] BackupStoreResponse_GetForwardSecrecyToken(long response) throws Exception;
+  public static native byte[] BackupStoreResponse_GetNextBackupSecretData(long response);
+  public static native byte[] BackupStoreResponse_GetOpaqueMetadata(long response) throws Exception;
 
   public static native void BridgedStringMap_Destroy(long handle);
   public static native void BridgedStringMap_insert(long map, String key, String value);
@@ -611,7 +615,7 @@ private Native() {}
   public static native byte[] SealedSessionCipher_MultiRecipientEncrypt(long[] recipients, long[] recipientSessions, byte[] excludedRecipients, long content, IdentityKeyStore identityKeyStore) throws Exception;
   public static native byte[] SealedSessionCipher_MultiRecipientMessageForSingleRecipient(byte[] encodedMultiRecipientMessage) throws Exception;
 
-  public static native CompletableFuture<byte[]> SecureValueRecoveryForBackups_RestoreBackupFromServer(long asyncRuntime, byte[] backupKey, byte[] metadata, long connectionManager, String username, String password);
+  public static native CompletableFuture<Long> SecureValueRecoveryForBackups_RestoreBackupFromServer(long asyncRuntime, byte[] backupKey, byte[] metadata, long connectionManager, String username, String password);
   public static native CompletableFuture<Long> SecureValueRecoveryForBackups_StoreBackup(long asyncRuntime, byte[] backupKey, byte[] previousSecretData, long connectionManager, String username, String password);
 
   public static native long SenderCertificate_Deserialize(byte[] data) throws Exception;

java/shared/java/org/signal/libsignal/internal/Native.java

@@ -228,9 +228,11 @@ export function BackupKey_DeriveLocalBackupMetadataKey(backupKey: Uint8Array): U
 export function BackupKey_DeriveMediaEncryptionKey(backupKey: Uint8Array, mediaId: Uint8Array): Uint8Array;
 export function BackupKey_DeriveMediaId(backupKey: Uint8Array, mediaName: string): Uint8Array;
 export function BackupKey_DeriveThumbnailTransitEncryptionKey(backupKey: Uint8Array, mediaId: Uint8Array): Uint8Array;
-export function BackupResponse_GetForwardSecrecyToken(response: Wrapper<BackupResponse>): Uint8Array;
-export function BackupResponse_GetNextBackupSecretData(response: Wrapper<BackupResponse>): Uint8Array;
-export function BackupResponse_GetOpaqueMetadata(response: Wrapper<BackupResponse>): Uint8Array;
+export function BackupRestoreResponse_GetForwardSecrecyToken(response: Wrapper<BackupRestoreResponse>): Uint8Array;
+export function BackupRestoreResponse_GetNextBackupSecretData(response: Wrapper<BackupRestoreResponse>): Uint8Array;
+export function BackupStoreResponse_GetForwardSecrecyToken(response: Wrapper<BackupStoreResponse>): Uint8Array;
+export function BackupStoreResponse_GetNextBackupSecretData(response: Wrapper<BackupStoreResponse>): Uint8Array;
+export function BackupStoreResponse_GetOpaqueMetadata(response: Wrapper<BackupStoreResponse>): Uint8Array;
 export function BridgedStringMap_insert(map: Wrapper<BridgedStringMap>, key: string, value: string): void;
 export function BridgedStringMap_new(initialCapacity: number): BridgedStringMap;
 export function CallLinkAuthCredentialPresentation_CheckValidContents(presentationBytes: Uint8Array): void;
@@ -501,8 +503,8 @@ export function SealedSender_DecryptToUsmc(ctext: Uint8Array, identityStore: Ide
 export function SealedSender_Encrypt(destination: Wrapper<ProtocolAddress>, content: Wrapper<UnidentifiedSenderMessageContent>, identityKeyStore: IdentityKeyStore): Promise<Uint8Array>;
 export function SealedSender_MultiRecipientEncrypt(recipients: Wrapper<ProtocolAddress>[], recipientSessions: Wrapper<SessionRecord>[], excludedRecipients: Uint8Array, content: Wrapper<UnidentifiedSenderMessageContent>, identityKeyStore: IdentityKeyStore): Promise<Uint8Array>;
 export function SealedSender_MultiRecipientMessageForSingleRecipient(encodedMultiRecipientMessage: Uint8Array): Uint8Array;
-export function SecureValueRecoveryForBackups_RestoreBackupFromServer(asyncRuntime: Wrapper<TokioAsyncContext>, backupKey: Uint8Array, metadata: Uint8Array, connectionManager: Wrapper<ConnectionManager>, username: string, password: string): CancellablePromise<Uint8Array>;
-export function SecureValueRecoveryForBackups_StoreBackup(asyncRuntime: Wrapper<TokioAsyncContext>, backupKey: Uint8Array, previousSecretData: Uint8Array, connectionManager: Wrapper<ConnectionManager>, username: string, password: string): CancellablePromise<BackupResponse>;
+export function SecureValueRecoveryForBackups_RestoreBackupFromServer(asyncRuntime: Wrapper<TokioAsyncContext>, backupKey: Uint8Array, metadata: Uint8Array, connectionManager: Wrapper<ConnectionManager>, username: string, password: string): CancellablePromise<BackupRestoreResponse>;
+export function SecureValueRecoveryForBackups_StoreBackup(asyncRuntime: Wrapper<TokioAsyncContext>, backupKey: Uint8Array, previousSecretData: Uint8Array, connectionManager: Wrapper<ConnectionManager>, username: string, password: string): CancellablePromise<BackupStoreResponse>;
 export function SenderCertificate_Deserialize(data: Uint8Array): SenderCertificate;
 export function SenderCertificate_GetCertificate(obj: Wrapper<SenderCertificate>): Uint8Array;
 export function SenderCertificate_GetDeviceId(obj: Wrapper<SenderCertificate>): number;
@@ -719,7 +721,8 @@ export function initLogger(maxLevel: LogLevel, callback: (level: LogLevel, targe
 export function test_only_fn_returns_123(): number;
 interface Aes256GcmSiv { readonly __type: unique symbol; }
 interface AuthenticatedChatConnection { readonly __type: unique symbol; }
-interface BackupResponse { readonly __type: unique symbol; }
+interface BackupRestoreResponse { readonly __type: unique symbol; }
+interface BackupStoreResponse { readonly __type: unique symbol; }
 interface BridgedStringMap { readonly __type: unique symbol; }
 interface CdsiLookup { readonly __type: unique symbol; }
 interface ChatConnectionInfo { readonly __type: unique symbol; }