Package org.signal.libsignal.net

Class SvrB

  • All Implemented Interfaces:
    
public final class SvrB

    Service for Secure Value Recovery for Backups (SVR-B) operations.

    This service provides forward secrecy for Signal backups using SVR-B. Forward secrecy ensures that even if the user's Account Entropy Pool or Backup Key is compromised, the attacker can decrypt a very small number of past backups. This is achieved by storing a token in a secure enclave inside the SVR-B server, which provably attests that it only stores a single token at a time for each user.

    To achieve these properties, a secret token is required to derive the actual encryption keys for the backup. At backup time, this token must be stored in the SVR-B server, overwriting the previous token. At restore time, the token must be retrieved from the SVR-B server, and used to derive the encryption keys for the backup.

    • Create a Network instance and get the SvrB service via Network.svrB

    • If this is a fresh install, call SvrB.createNewBackupChain and store the result locally. Otherwise, retrieve the secret data from the last successful backup operation (store or restore).

    • Call SvrB.store

    • Use the returned forward secrecy token to derive encryption keys

    • Encrypt and upload the backup data to the user's remote, off-device storage location, including the returned SvrBStoreResponse.metadata. The upload must succeed before proceeding or the previous backup might become unretrievable.

    • Store the SvrBStoreResponse.nextBackupSecretData locally, overwriting any previously-saved value.

    When calling SvrB.store, the previousSecretData parameter 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 use SvrB.createNewBackupChain only for the very first backup with a particular backup key.

    val net = Network(Network.Environment.PRODUCTION, "Signal Android")
val auth = Network.Auth(username = "myUsername", password = "myPassword")
val svrB = net.svrB(auth)

// Prepare a backup
val stored = svrB.store(myKey, previousSecretData).get().getOrThrow()
// ... store backup with stored.forwardSecrecyToken remotely ...
// Securely persist stored.nextBackupSecretData for the next backup

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description

    • Field Summary

      Fields 
      Modifier and Type Field Description

    • Constructor Summary

      Constructors 
      Constructor Description

    • Enum Constant Summary

      Enum Constants 
      Enum Constant Description

    • Constructor Detail

    • Method Detail

      • createNewBackupChain

         final ByteArray createNewBackupChain(BackupKey backupKey)

        Generates backup "secret data" for a fresh install.

        Should not be used if any previous backups exist for this backupKey, whether uploaded or restored by the local device. See SvrB for more information.

      • restore

         final CompletableFuture<Result<SvrBRestoreResponse>> restore(BackupKey backupKey, ByteArray metadata)

        Fetches the forward secrecy token needed to decrypt a backup.

        This function makes a network call to the SVR-B server to retrieve the forward secrecy token associated with a specific backup. The token is required to derive the message backup keys for decryption.

        The typical restore flow:

        • Fetch the backup metadata (stored in a header in the backup file)

        • Call this function to retrieve the forward secrecy token from SVR-B

        • Use the token to derive message backup keys

        • Decrypt and restore the backup data

        • Store the returned SvrBRestoreResponse.nextBackupSecretData locally.

        Parameters:
        backupKey - The backup key derived from the Account Entropy Pool (AEP).
        metadata - The metadata that was stored in a header in the backup file during backup creation.
        Returns:

        a CompletableFuture that completes with: