Files that are encrypted using server-side encryption may be accessed using the same API calls as other B2 files (using either the B2 Native API or the S3 Compatible API).

You have two options for encrypting data with Backblaze B2 Server-Side Encryption. Both options use an extensively tested and widely trusted block cipher, 256-bit Advanced Encryption Standard (AES-256), to encrypt the data at rest.

Server-Side Encryption with Backblaze-Managed Keys (SSE-B2)

The data of each file that is stored using Server-Side Encryption with Backblaze-Managed Keys (SSE-B2) is encrypted using a unique encryption key; each file’s encryption key is additionally encrypted with a global key before being saved to decrypt the data when each file is accessed.

Server-Side Encryption with Customer-Managed Keys (SSE-C)

Using Server-Side Encryption with Customer-Managed Keys (SSE-C) with your B2 files means the data of each file is encrypted with a unique encryption key; each file’s encryption key is additionally encrypted with the AES-256 encryption key that you manage. Backblaze B2 manages the encryption process using the key that you provide when uploading or accessing each file.

Security Details

Warning: Do not include Protected Health Information (PHI) or Personally Identifiable Information (PII) in bucket names, object/file/folder names, or other metadata. Such metadata is not encrypted in a way that meets Health Insurance Portability and Accountability Act (HIPAA) protection requirements for PHI/PII data and is not generally encrypted in client-side encryption architectures.

With either SSE-B2 or SSE-C, Backblaze B2 Server-Side Encryption encrypts your file data at rest but not the file metadata. After a file has been uploaded, the only time the data is decrypted is when a client accesses the file (e.g., downloading or copying the file via API calls).

If you use SSE-C to encrypt a file, then you must manage and protect your encryption keys yourself. Backblaze does not store the encryption keys for SSE-C files; instead, it stores a secure hash value that is used to validate future requests, but which cannot be used to derive the original encryption key or decrypt your file data. As a result, if you lose the encryption key for a file encrypted with SSE-C, Backblaze will not be able to recover your key or decrypt the data.

To protect the confidentiality of your data, files encrypted with server-side encryption are not currently available for direct download via the Backblaze B2 Browse Files page or included in snapshots created from that page.

Note that you must use API version v2 or later in b2_list_file_names and b2_list_file_versions in order to view server-side encryption information.

Default Bucket Encryption

If you want server-side encryption for all of the files that are uploaded to a bucket, you can enable SSE-B2 encryption as a default setting for the bucket. All uploads to that bucket, from the time default encryption is enabled onward, will then be encrypted with SSE-B2 by default unless you explicitly specify SSE-C encryption for a given file at upload time. Note that existing files in the bucket are not affected by default bucket encryption settings.

Permission to read and write default bucket encryption settings are determined by the readBucketEncryption and writeBucketEncryption application key capabilities, respectively. Default bucket encryption may be enabled or disabled via either the web application or API calls.

B2 Native API SSE Parameters

Default Bucket Encryption

To enable default bucket encryption (SSE-B2) through the B2 Native API, use the defaultServerSideEncryption parameter when calling b2_update_bucket:

      "defaultServerSideEncryption": {
        "mode": "SSE-B2",
        "algorithm": "AES256"
      }

To disable default bucket encryption, use the same parameter with mode set to null:

      "defaultServerSideEncryption": {
        "mode": null
      }

To access default bucket encryption settings, the client must have the readBucketEncryption application key capability. In that case, the responses of API calls that return bucket information (e.g., b2_list_buckets) will include a defaultServerSideEncryption field which includes a isClientAuthorizedToRead boolean set to true and a value field which contains the actual bucket encryption settings, e.g.,

      "defaultServerSideEncryption": {
        "isClientAuthorizedToRead" : true,
        "value": {
          "algorithm" : "AES256",
          "mode" : "SSE-B2"
        }
      }

If default bucket encryption is disabled, then algorithm and mode will both be null. If the client does not have readBucketEncryption application key capability, then isClientAuthorizedToRead will be false and value will be null.

Uploading and Accessing SSE-B2 Files

To request SSE-B2 encryption for regular files with the B2 Native API, see the documentation for b2_upload_file regarding the X-Bz-Server-Side-Encryption header.

To request SSE-B2 encryption for large files with the B2 Native API, call b2_start_large_file with the following JSON parameters:

    "serverSideEncryption": {
      "mode": "SSE-B2",
      "algorithm": "AES256"
    }

When uploading large file parts for large files that have been started with SSE-B2 encryption, all parts will be encrypted with SSE-B2 encryption. For SSE-B2 large files, no further SSE parameters are needed when uploading parts. Similarly, new SSE-B2 large file parts created using b2_copy_part do not require any specific SSE parameters.

Downloading files that are encrypted with SSE-B2 is transparent; no SSE parameters are needed. Similarly, copying source files that are encrypted with SSE-B2 using b2_copy_file or b2_copy_part is transparent, and requires no additional parameters.

To request SSE-B2 encryption for copied (destination) files when calling b2_copy_file, use the JSON parameter destinationServerSideEncryption, i.e.:

    "destinationServerSideEncryption": {
      "mode": "SSE-B2",
      "algorithm": "AES256"
    }

Uploading and Accessing SSE-C Files

To request SSE-C encryption for regular files with the B2 Native API, see the documentation for b2_upload_file regarding the X-Bz-Server-Side-Encryption-Customer-Algorithm, X-Bz-Server-Side-Encryption-Customer-Key, and X-Bz-Server-Side-Encryption-Customer-Key-Md5 headers.

To request SSE-C encryption for large files with the B2 Native API, use the following JSON parameters with b2_start_large_file:

    "serverSideEncryption": {
      "mode": "SSE-C",
      "algorithm": "AES256",
      "customerKey": "<base64-encoded AES-256 encryption key>",
      "customerKeyMd5": "<base64-encoded MD5 digest of the key>"
    }

When uploading large file parts for large files that have been started with SSE-C encryption, the encryption parameters of the parts must match those specified when calling b2_start_large_file. For more details, see the documentation for b2_upload_part regarding the X-Bz-Server-Side-Encryption-Customer-Algorithm, X-Bz-Server-Side-Encryption-Customer-Key, and X-Bz-Server-Side-Encryption-Customer-Key-Md5 headers.

To use the B2 Native API to download files that are encrypted with SSE-C you can call b2_download_file_by_id or b2_download_file_by_name with the X-Bz-Server-Side-Encryption-Customer-Algorithm, X-Bz-Server-Side-Encryption-Customer-Key, and X-Bz-Server-Side-Encryption-Customer-Key-Md5 headers or with the following JSON parameters:

    "serverSideEncryption": {
      "mode": "SSE-C",
      "algorithm": "AES256",
      "customerKey": "<base64-encoded AES-256 encryption key>",
      "customerKeyMd5": "<base64-encoded MD5 digest of the key>"
    }

When copying from source files/parts encrypted with SSE-C and/or requesting SSE-C encryption for destination files/parts while calling b2_copy_file or b2_copy_part , use the JSON parameters sourceServerSideEncryption and/or destinationServerSideEncryption instead of serverSideEncryption, e.g.:

    "sourceServerSideEncryption": {
      "mode": "SSE-C",
      "algorithm": "AES256",
      "customerKey": "<base64-encoded AES-256 encryption key>",
      "customerKeyMd5": "<base64-encoded MD5 digest of the key>"
    },
    "destinationServerSideEncryption": {
      "mode": "SSE-C",
      "algorithm": "AES256",
      "customerKey": "<base64-encoded AES-256 encryption key>",
      "customerKeyMd5": "<base64-encoded MD5 digest of the key>"
    }