package org.signal.chat.backup

Get desktop application:
View/edit binary Protocol Buffers messages

Service for backup operations that require account authentication. Most actual backup operations operate on the backup-id and cannot be linked to the caller's account, but setting up anonymous credentials and changing backup tier requires account authentication.

• rpc GetBackupAuthCredentials (GetBackupAuthCredentialsRequest, GetBackupAuthCredentialsResponse)

  backups.proto:61

  After setting a blinded backup-id with PUT /v1/archives/, this fetches credentials that can be used to perform operations against that backup-id. Clients may (and should) request up to 7 days of credentials at a time. The redemption_start and redemption_end seconds must be UTC day aligned, and must not span more than 7 days. Each credential contains a receipt level which indicates the backup level the credential is good for. If the account has paid backup access that expires at some point in the provided redemption window, credentials with redemption times after the expiration may be on a lower backup level. Clients must validate the receipt level on the credential matches a known receipt level before using it.

  message GetBackupAuthCredentialsRequest

  backups.proto:99

  • int64 redemption_start = 1

    The redemption time for the first credential. This must be a day-aligned seconds since epoch in UTC.

  • int64 redemption_stop = 2

    The redemption time for the last credential. This must be a day-aligned seconds since epoch in UTC. The span between redemptionStart and redemptionEnd must not exceed 7 days.

  message GetBackupAuthCredentialsResponse

  backups.proto:110

  • optional GetBackupAuthCredentialsResponse.Credentials credentials = 1

    The requested credentials. If absent, there was no existing blinded backup id associated with the provided account.

• rpc RedeemReceipt (RedeemReceiptRequest, RedeemReceiptResponse)

  backups.proto:45

  Redeem a receipt acquired from /v1/subscription/{subscriberId}/receipt_credentials to mark the account as eligible for the paid backup tier. After successful redemption, subsequent requests to GetBackupAuthCredentials will return credentials with the level on the provided receipt until the expiration time on the receipt.

  message RedeemReceiptRequest

  backups.proto:81

  • bytes presentation = 1

    Presentation for a previously acquired receipt, serialized with libsignal

  message RedeemReceiptResponse

  backups.proto:86

  • oneof response

    • google.protobuf.Empty success = 1

      The receipt was successfully redeemed

    • errors.FailedPrecondition account_missing_commitment = 2

      The target account does not have a backup-id commitment

    • errors.FailedPrecondition invalid_receipt = 3

      The provided receipt presentation was malformed or expired

• rpc SetBackupId (SetBackupIdRequest, SetBackupIdResponse)

  backups.proto:37

  Set (blinded) backup-id(s) for the account. Each account may have a single active backup-id for each credential type that can be used to store and retrieve backups. Once the backup-id is set, BackupAuthCredentials can be generated using GetBackupAuthCredentials. The blinded backup-id and the key-pair used to blind it must be derived from a recoverable secret. At least one of the credential types must be set on the request. Only the primary device can set a blinded backup-id.

  message SetBackupIdRequest

  backups.proto:64

  • bytes messages_backup_auth_credential_request = 1

    A BackupAuthCredentialRequest containing a blinded encrypted backup-id, encoded in standard padded base64. This backup-id should be used for message backups only, and must have the message backup type set on the credential. If absent, the message credential request will not be updated.

  • bytes media_backup_auth_credential_request = 2

    A BackupAuthCredentialRequest containing a blinded encrypted backup-id, encoded in standard padded base64. This backup-id should be used for media only, and must have the media type set on the credential. If absent, the media credential request will not be updated.

  message SetBackupIdResponse

  backups.proto:78

  (message has no fields)

Service for backup operations with anonymous credentials This service never requires account authentication. It instead requires a backup-id authenticated with an anonymous credential that cannot be linked to the account. To register an anonymous credential: 1. Set a backup-id on the authenticated channel via Backups::SetBackupId 2. Retrieve BackupAuthCredentials via Backups::GetBackupAuthCredentials 3. Generate a key pair and set the public key via BackupsAnonymous::SetPublicKey Unless otherwise noted, requests for this service require a SignedPresentation, which includes: - a presentation generated from a BackupAuthCredential issued by GetBackupAuthCredentials - a signature of that presentation using the private key of a key pair previously set with SetPublicKey.

• rpc CopyMedia (CopyMediaRequest, stream CopyMediaResponse)

  backups.proto:189

  Copy and re-encrypt media from the attachments cdn into the backup cdn. The original, already encrypted, attachments will be encrypted with the provided key material before being copied. The copy operation is not atomic and responses will be returned as copy operations complete with detailed information about the outcome. If an error is encountered, not all requests may be reflected in the responses. On retries, a particular destination media id must not be reused with a different source media id or different encryption parameters. The response stream may be closed with STREAM_CLOSED error reason. In this case, a BackupStreamClosed message will be present in the error details.

  message CopyMediaRequest

  backups.proto:425

  • optional SignedPresentation signed_presentation = 1

  • repeated CopyMediaItem items = 2

    Items to copy

  message CopyMediaResponse

  backups.proto:432

  • bytes media_id = 1

    The 15-byte media_id from the corresponding CopyMediaItem in the request

  • oneof response

    • CopyMediaResponse.CopySuccess success = 2

      The media item was successfully copied into the backup

    • CopyMediaResponse.SourceNotFound source_not_found = 3

      The source object was not found

    • CopyMediaResponse.WrongSourceLength wrong_source_length = 4

      The provided object length was incorrect

    • CopyMediaResponse.OutOfSpace out_of_space = 5

      All media capacity has been consumed. Free some space to continue.

• rpc DeleteAll (DeleteAllRequest, DeleteAllResponse)

  backups.proto:207

  Delete all backup metadata, objects, and stored public key. To use backups again, a public key must be resupplied.

  message DeleteAllRequest

  backups.proto:522

  • optional SignedPresentation signed_presentation = 1

  message DeleteAllResponse

  backups.proto:525

  • oneof response

    • google.protobuf.Empty success = 1

      The backup was successfully scheduled for deletion

    • errors.FailedZkAuthentication failed_authentication = 2

      The provided backup auth credential presentation could not be authenticated. Either, the presentation could not be verified, or the public key signature was invalid, or there is no backup associated with the backup-id in the presentation.

• rpc DeleteMedia (DeleteMediaRequest, stream DeleteMediaResponse)

  backups.proto:203

  Delete media objects stored with this backup-id. Streams the locations of media items back when the item has successfully been removed. The response stream may be closed with STREAM_CLOSED error reason. In this case, a BackupStreamClosed message will be present in the error details.

  message DeleteMediaRequest

  backups.proto:546

  • optional SignedPresentation signed_presentation = 1

  • repeated DeleteMediaItem items = 2

  message DeleteMediaResponse

  backups.proto:552

  • optional DeleteMediaItem deleted_item = 1

• rpc GetCdnCredentials (GetCdnCredentialsRequest, GetCdnCredentialsResponse)

  backups.proto:152

  Retrieve credentials used to read objects stored on the backup cdn

  message GetCdnCredentialsRequest

  backups.proto:243

  • optional SignedPresentation signed_presentation = 1

  • uint32 cdn = 2

  message GetCdnCredentialsResponse

  backups.proto:247

  • oneof response

    • GetCdnCredentialsResponse.CdnCredentials cdn_credentials = 1

      Headers to include with requests to the read from the backup CDN. Includes time limited read-only credentials.

    • errors.FailedZkAuthentication failed_authentication = 2

      The provided backup auth credential presentation could not be authenticated. Either, the presentation could not be verified, or the public key signature was invalid, or there is no backup associated with the backup-id in the presentation.

• rpc GetMediaBackupInfo (GetBackupInfoRequest, GetMediaBackupInfoResponse)

  backups.proto:161

  Retrieve information about the currently stored media backup

  message GetMediaBackupInfoResponse

  backups.proto:320

  • oneof response

    • GetMediaBackupInfoResponse.MediaBackupInfo backup_info = 1

    • errors.FailedZkAuthentication failed_authentication = 2

      The provided backup auth credential presentation could not be authenticated. Either, the presentation could not be verified, or the public key signature was invalid, or there is no backup associated with the backup-id in the presentation.

• rpc GetMessageBackupInfo (GetBackupInfoRequest, GetMessageBackupInfoResponse)

  backups.proto:158

  Retrieve information about the currently stored message backup

  message GetMessageBackupInfoResponse

  backups.proto:291

  • oneof response

    • GetMessageBackupInfoResponse.MessageBackupInfo backup_info = 1

    • errors.FailedZkAuthentication failed_authentication = 2

      The provided backup auth credential presentation could not be authenticated. Either, the presentation could not be verified, or the public key signature was invalid, or there is no backup associated with the backup-id in the presentation.

• rpc GetSvrBCredentials (GetSvrBCredentialsRequest, GetSvrBCredentialsResponse)

  backups.proto:155

  Retrieve credentials used to interact with the SecureValueRecoveryB service

  message GetSvrBCredentialsRequest

  backups.proto:264

  • optional SignedPresentation signed_presentation = 1

  message GetSvrBCredentialsResponse

  backups.proto:268

  • oneof response

    • GetSvrBCredentialsResponse.SvrBCredentials svrb_credentials = 1

    • errors.FailedZkAuthentication failed_authentication = 2

      The provided backup auth credential presentation could not be authenticated. Either, the presentation could not be verified, or the public key signature was invalid, or there is no backup associated with the backup-id in the presentation.

• rpc GetUploadForm (GetUploadFormRequest, GetUploadFormResponse)

  backups.proto:174

  Retrieve an upload form that can be used to perform a resumable upload

  message GetUploadFormRequest

  backups.proto:365

  • optional SignedPresentation signed_presentation = 1

  • oneof upload_type

    • GetUploadFormRequest.MessagesUploadType messages = 2

      Retrieve an upload form that can be used to perform a resumable upload of a message backup. The finished upload will be available on the backup cdn.

    • GetUploadFormRequest.MediaUploadType media = 3

      Retrieve an upload form for a temporary location that can be used to perform a resumable upload of an attachment. After uploading, the attachment can be copied into the backup via CopyMedia. Behaves identically to the account authenticated version at /attachments.

  • uint64 uploadLength = 4

    The length of the attachment for the requested upload form. Uploads performed with this form will be limited to the provided length.

  message GetUploadFormResponse

  backups.proto:387

  • oneof response

    • common.UploadForm upload_form = 1

    • errors.FailedZkAuthentication failed_authentication = 2

      The provided backup auth credential presentation could not be authenticated. Either, the presentation could not be verified, or the public key signature was invalid, or there is no backup associated with the backup-id in the presentation.

    • errors.FailedPrecondition exceeds_max_upload_length = 3

      The request size was larger than the maximum supported upload size. The maximum upload size is subject to change and is governed by `global.attachments.maxBytes`

• rpc ListMedia (ListMediaRequest, ListMediaResponse)

  backups.proto:196

  Retrieve a page of media objects stored for this backup-id. A client may have previously stored media objects that are no longer referenced in their current backup. To reclaim storage space used by these orphaned objects, perform a list operation and remove any unreferenced media objects via DeleteMedia.

  message ListMediaRequest

  backups.proto:470

  • optional SignedPresentation signed_presentation = 1

  • optional string cursor = 2

    A cursor returned by a previous call to ListMedia, absent on the first call

  • optional uint32 limit = 3

    If provided, the maximum number of entries to return in a page. If absent, a server-chosen default is used.

  message ListMediaResponse

  backups.proto:481

  • oneof response

    • ListMediaResponse.ListResult list_result = 1

    • errors.FailedZkAuthentication failed_authentication = 2

      The provided backup auth credential presentation could not be authenticated. Either, the presentation could not be verified, or the public key signature was invalid, or there is no backup associated with the backup-id in the presentation.

• rpc Refresh (RefreshRequest, RefreshResponse)

  backups.proto:171

  Refresh the backup, indicating that the backup is still active. Clients must periodically upload new backups or perform a refresh. If a backup has not been active for 30 days, it may be deleted.

  message RefreshRequest

  backups.proto:349

  • optional SignedPresentation signed_presentation = 1

  message RefreshResponse

  backups.proto:352

  • oneof response

    • google.protobuf.Empty success = 1

      The backup was successfully refreshed

    • errors.FailedZkAuthentication failed_authentication = 2

      The provided backup auth credential presentation could not be authenticated. Either, the presentation could not be verified, or the public key signature was invalid, or there is no backup associated with the backup-id in the presentation.

• rpc SetPublicKey (SetPublicKeyRequest, SetPublicKeyResponse)

  backups.proto:166

  Permanently set the public key of an ED25519 key-pair for the backup-id. All requests (including this one!) must sign their BackupAuthCredential presentations with the private key corresponding to the provided public key.

  message SetPublicKeyRequest

  backups.proto:220

  • optional SignedPresentation signed_presentation = 1

  • bytes public_key = 2

    The public key, serialized in libsignal's elliptic-curve public key format.

  message SetPublicKeyResponse

  backups.proto:227

  • oneof response

    • google.protobuf.Empty success = 1

      The public key was successfully set

    • errors.FailedZkAuthentication failed_authentication = 2

      The provided backup auth credential presentation could not be authenticated. Either, the presentation could not be verified, or the public key signature was invalid, or there is no backup associated with the backup-id in the presentation. This may also be returned if there was an existing public key and the provided public key did not match.

The reason why a media stream RPC is being prematurely closed by the server.

• oneof reason

  • errors.FailedZkAuthentication failed_authentication = 1

    The provided backup auth credential presentation could not be authenticated. Either, the presentation could not be verified, or the public key signature was invalid, or there is no backup associated with the backup-id in the presentation.

Used in: CopyMediaRequest

• uint32 source_attachment_cdn = 1

  The attachment cdn of the object to copy into the backup

• string source_key = 2

  The attachment key of the object to copy into the backup

• uint64 object_length = 3

  The length of the source attachment before the encryption applied by the copy operation

• bytes media_id = 4

  media_id to copy on to the backup CDN

• bytes hmac_key = 5

  A 32-byte key for the MAC

• bytes encryption_key = 6

  A 32-byte encryption key for AES

Used in: CopyMediaResponse

• uint32 cdn = 1

  The backup cdn where this media object is stored

Used in: CopyMediaResponse

(message has no fields)

Used in: CopyMediaResponse

(message has no fields)

Used in: CopyMediaResponse

(message has no fields)

Used in: DeleteMediaRequest, DeleteMediaResponse

• uint32 cdn = 1

  The backup cdn where this media object is stored

• bytes media_id = 2

  The media_id of the object to delete

Used in: GetBackupAuthCredentialsResponse

• map<int64, common.ZkCredential> message_credentials = 1

  The requested message backup ZkCredentials indexed by the start of their validity period. The smallest key should be for the requested redemption_start, the largest for the requested redemption_end.

• map<int64, common.ZkCredential> media_credentials = 2

  The requested media backup ZkCredentials indexed by the start of their validity period. The smallest key should be for the requested redemption_start, the largest for the requested redemption_end.

Used as request type in: BackupsAnonymous.GetMediaBackupInfo, BackupsAnonymous.GetMessageBackupInfo

• optional SignedPresentation signed_presentation = 1

Used in: GetCdnCredentialsResponse

• map<string, string> headers = 1

Used in: GetMediaBackupInfoResponse

• string backup_dir = 1

  The base directory of your backup data on the cdn. Always non-empty, even if no media has been stored to the cdn or the credential is for a tier that does not support media.

• string media_dir = 2

  The prefix path component for media objects on a cdn. Stored media for a media_id can be found at /backup_dir/media_dir/media_id, where the media_id is encoded in unpadded url-safe base64. Always non-empty, even if no media has been stored to the cdn or the credential is for a tier that does not support media.

• uint64 used_space = 3

  The amount of space used to store media

Used in: GetMessageBackupInfoResponse

• string backup_dir = 1

  The base directory of your backup data on the cdn. Always non-empty, even if a backup has not actually been stored to the cdn. If a backup was previously uploaded and has not expired, it can be found in the returned cdn at /backup_dir/backup_name.

• uint32 cdn = 2

  The CDN type where the message backup is stored. Media may be stored elsewhere.

• string backup_name = 3

  The location of the message backup on the cdn. Always non-empty, even if a backup has not actually been stored to the cdn. If a backup was previously uploaded and has not expired, it can be found in the returned cdn at /backup_dir/backup_name.

Used in: GetSvrBCredentialsResponse

• string username = 1

  A username that can be presented to authenticate with SVRB

• string password = 2

  A password that can be presented to authenticate with SVRB

Used in: GetUploadFormRequest

(message has no fields)

Used in: GetUploadFormRequest

(message has no fields)

Used in: ListResult

• uint32 cdn = 1

  The backup cdn where this media object is stored

• bytes media_id = 2

  The media_id of the object

• uint64 length = 3

  The length of the object in bytes

Used in: ListMediaResponse

• repeated ListEntry page = 1

  A page of media objects stored for this backup ID

• string backup_dir = 2

  The base directory of the backup data on the cdn. The stored media can be found at /backup_dir/media_dir/media_id, where the media_id is encoded with unpadded url-safe base64.

• string media_dir = 3

  The prefix path component for the media objects. The stored media for media_id can be found at /backup_dir/media_dir/media_id, where the media_id is encoded with unpadded url-safe base64.

• optional string cursor = 4

  If set, the cursor value to pass to the next list request to continue listing. If absent, all objects have been listed

Used in: CopyMediaRequest, DeleteAllRequest, DeleteMediaRequest, GetBackupInfoRequest, GetCdnCredentialsRequest, GetSvrBCredentialsRequest, GetUploadFormRequest, ListMediaRequest, RefreshRequest, SetPublicKeyRequest

• bytes presentation = 1

  Presentation of a BackupAuthCredential previously retrieved from GetBackupAuthCredentials on the authenticated channel

• bytes presentation_signature = 2

  The presentation signed with the private key corresponding to the public key set with SetPublicKey