Enable Server-Side Encryption with the Native API

You can enable server-side encryption (SSE) on your Backblaze B2 Cloud Storage buckets using the Native API.

For information about how to enable SSE using the command-line interface, click here.

Enable and Manage SSE-B2

Use the following procedures to use SSE-B2.

Enable SSE-B2

Before you begin: Create an authorization token by calling b2_authorize_account with an application key.

Use the defaultServerSideEncryption parameter when you call the b2_update_bucket operation as in the following example:

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

The following example shows you how to enable SSE-B2 using cURL:

curl \
   -H 'Authorization: ACCOUNT_AUTHORIZATION_TOKEN' \
   -d '{ "accountId": "ACCOUNT_ID", "bucketId": "BUCKET_ID", 
        "bucketType": "BUCKET_TYPE", 
        "defaultServerSideEncryption": { 
        "mode": "SSE-B2", "algorithm": "AES256" }}' \
   https://apiNNN.backblazeb2.com/b2api/v2/b2_update_bucket

Disable SSE-B2

Before you begin: Create an authorization token by calling b2_authorize_account with an application key.

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

"defaultServerSideEncryption": {
   "mode": null
}

The following example shows you how to disable SSE-B2 using cURL:

curl \
   -H 'Authorization: ACCOUNT_AUTHORIZATION_TOKEN' \
   -d '{ "accountId": "ACCOUNT_ID", "bucketId": "BUCKET_ID",
         "bucketType": "BUCKET_TYPE",
         "defaultServerSideEncryption": { "mode": null }}' \
   https://apiNNN.backblazeb2.com/b2api/v2/b2_update_bucket

Access Default Bucket Encryption Settings

The client must have the readBucketEncryption app key capability. The API response returns bucket information, b2_list_buckets, and a defaultServerSideEncryption field that includes a isClientAuthorizedToRead Boolean value that is set to true and a value field that contains the actual bucket encryption settings.

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

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

Upload and Access SSE-B2 Files

Even without the setting turned on at the bucket level, you can enable it on individual file uploads by using the appropriate header information.

You must call b2_get_upload_url for the UPLOAD_URL and the UPLOAD_AUTHORIZATION_TOKEN.

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"
 }

The following example shows you how to upload SSE-B2 files using cURL:

FILE_TO_UPLOAD=/path/to/myfile
SHA1_OF_FILE=$(openssl dgst -sha1 ${FILE_TO_UPLOAD} | awk '{print $2;}')
UPLOAD_URL=...                 # from b2_get_upload_url call
UPLOAD_AUTHORIZATION_TOKEN=... # from b2_get_upload_url call

curl \
   -H "Authorization: ${UPLOAD_AUTHORIZATION_TOKEN}" \
   -H "X-Bz-File-Name: ${FILE_TO_UPLOAD}" \
   -H "X-Bz-Content-Sha1: ${SHA1_OF_FILE}" \
   -H "X-Bz-Server-Side-Encryption: AES256" \
   --data-binary "@${FILE_TO_UPLOAD}" \
   ${UPLOAD_URL}

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.

Download Files Encrypted with SSE-B2

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.

Request Destination Files Encrypted with SSE-B2

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"
 }

Enable and Manage SSE-C

Use the following procedures to use SSE-C.

Upload and Access SSE-C Files

You must call b2_get_upload_url for the UPLOAD_URL and the UPLOAD_AUTHORIZATION_TOKEN.

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.

This example shows you how to upload SSE-C Files using cURL:

FILE_TO_UPLOAD=/path/to/myfile
SHA1_OF_FILE=$(openssl dgst -sha1 ${FILE_TO_UPLOAD} | awk '{print $2;}')
UPLOAD_URL=...                 # from b2_get_upload_url call
UPLOAD_AUTHORIZATION_TOKEN=... # from b2_get_upload_url call
SSE-C-KEY=                     # Base64 Encoded AES256 key
SSE-C-KEY-MD5=                 # MD5 of AES256 key

curl \
   -H "Authorization: ${UPLOAD_AUTHORIZATION_TOKEN}" \
   -H "X-Bz-File-Name: ${FILE_TO_UPLOAD}" \
   -H "X-Bz-Content-Sha1: ${SHA1_OF_FILE}" \
   -H "X-Bz-Server-Side-Encryption-Customer-Algorithm: AES256" \
   -H "X-Bz-Server-Side-Encryption-Customer-Key: ${SSE-C-KEY}" \
   -H "X-Bz-Server-Side-Encryption-Customer-Key-Md5: ${SSE-C-KEY-MD5}" \
   --data-binary "@${FILE_TO_UPLOAD}" \
   ${UPLOAD_URL}

Request SSE-C for Large Files

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.

Download Files Encrypted with SSE-C

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>"
 }

Copy from Source Files Encrypted with SSE-C

When copying from source files/parts encrypted with SSE-C while calling b2_copy_file or b2_copy_part, use the JSON parameters sourceServerSideEncryption instead of serverSideEncryption:

"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>"
}

The following cURL example shows you how to copy source files/parts encrypted with SSE-C:

curl \
   -H 'Authorization: ACCOUNT_AUTHORIZATION_TOKEN' \
   -d '{ "sourceFileId":"myfile", "fileName":"myfile-copy", 
         "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 AES-256 encryption key>", 
           "customerKeyMd5": "<base64 MD5 digest of the key>" }}' \
   https://apiNNN.backblazeb2.com/b2api/v2/b2_copy_file

Request SSE-C Encryption for Destination Files

When requesting SSE-C encryption for destination files/parts while calling b2_copy_file or b2_copy_part, use the JSON parameters destinationServerSideEncryption instead of serverSideEncryption.

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