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. This "chaining" is used to construct each backup file so that it can be decrypted with either the previous token stored in SVR-B, or the next one, which is important in case the overall backup upload is ever interrupted.

    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