Server-Side Encryption
Server-side encryption protects your data by encrypting it before it is stored on disk by Backblaze B2 Cloud Storage.
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>" }