File Lock
Backblaze B2 File Lock prevents files from being deleted during a customer-determined retention period.
File Lock (also known as Object Lock) is a feature that allows Backblaze B2 customers to make data immutable by preventing a file from being changed or deleted until a given date, whether to protect data stored in Backblaze B2 Cloud Storage from threats like ransomware or for regulatory compliance.
How does File Lock work?
File Lock must be enabled on a bucket at the time the bucket is created. For files in File Lock-enabled buckets, you can assign File Lock settings to files either at upload time or afterward. Attempts to delete the file or make any changes to it before the end of the retention period will fail.
Backblaze B2 File Lock retention settings can be configured in either governance or compliance mode. File Lock retention settings for files protected in governance mode can be modified or overridden by clients with appropriate application key capabilities. File Lock retention settings for files protected in compliance mode cannot be removed by any user, but their retention dates can be extended by clients with appropriate application key capabilities.
In addition, Backblaze B2 File Lock supports protecting files from deletion with a legal hold, which is not bound by a predetermined expiration date. Legal hold protections are configured separately from governance- or compliance-mode retention settings.
Legal hold and retention settings function independently to protect B2 files from unwanted deletion. If either legal hold or retention settings, or even both, are active for a given file, then that file is protected from being deleted.
Note that you must use API version v2
or later in
b2_list_file_names
and
b2_list_file_versions
in order to view legal hold and retention settings.
Default Bucket Retention
To set default File Lock retention settings for all files uploaded to a File Lock-enabled bucket, you can configure default bucket retention settings for that bucket. All files uploaded or copied to that bucket, from that time onward, will be protected by those File Lock retention settings by default. The default settings can be overridden for individual files at upload time (and, in some cases, after upload).
The bucket must be File Lock-enabled at creation time to configure default bucket retention settings. Note that existing files in the bucket are not affected by updated default bucket retention settings, and that you cannot enable legal hold by default at the bucket level. If no default retention settings are configured on the bucket, then uploaded files will not be protected by File Lock by default.
Permissions to read and write default bucket retention settings are
determined by the readBucketRetentions
and
writeBucketRetentions
application key capabilities,
respectively. Default bucket retention may be configured via either
the web application or API calls.
B2 Native API File Lock Parameters
Default Bucket Retention
To configure default bucket retention settings
through the B2 Native API, use
the defaultRetention
parameter when
calling
b2_update_bucket
, e.g.:
"defaultRetention": { "mode": "compliance", "period": { "duration": 7, "unit": "days" } }
The default retention mode
must be
either "compliance"
or "governance"
. The
default retention period
is specified as
a duration
(which must be a positive integer) and
a unit
of time (either "days"
or "years"
).
To disable default bucket retention, use the
same parameter with mode
set to null
:
"defaultRetention": { "mode": null }
To access bucket file lock and default retention
settings, the client must have the
readBucketRetentions
application key capability. In that
case, the responses of API calls that return bucket information
(e.g., b2_list_buckets
)
will include a
fileLockConfiguration
field which includes an
isClientAuthorizedToRead
boolean set to true
and a value
field which contains the actual bucket
File Lock settings, e.g.:
"fileLockConfiguration": { "isClientAuthorizedToRead": true, "value": { "defaultRetention": { "mode": "governance", "period": { "duration": 2, "unit": "years" } }, "isFileLockEnabled": true } }
If default bucket retention is disabled, then mode
and period
will both be null
, e.g.:
"fileLockConfiguration": { "isClientAuthorizedToRead": true, "value": { "defaultRetention": { "mode": null, "period": null }, "isFileLockEnabled": true } }
If the bucket is not File Lock-enabled, then isFileLockEnabled
will be set to false as well, i.e.:
"fileLockConfiguration": { "isClientAuthorizedToRead": true, "value": { "defaultRetention": { "mode": null, "period": null }, "isFileLockEnabled": false } }
If the client does not have readBucketRetentions
application key capability, then isClientAuthorizedToRead
will be false
and value
will be null
,
i.e.:
"fileLockConfiguration": { "isClientAuthorizedToRead": false, "value": null }
Enabling File Lock on File Upload
You may enable File Lock retention settings (or override default
bucket retention settings) and legal hold protections for B2 files
when uploading or copying. Permissions to configure individual file
retention settings and legal hold protections are determined by the
writeFileRetentions
and writeFileLegalHolds
application key capabilities, respectively.
b2_upload_file
To enable File Lock retention settings for a predetermined period of time
when calling b2_upload_file
,
use the following headers:
X-Bz-File-Retention-Mode
for File Lock retention mode. Valid values aregovernance
andcompliance
.X-Bz-File-Retention-Retain-Until-Timestamp
for File Lock retention timestamp in the future, after which the intended File Lock will expire. This header value must be specified as a base 10 number of milliseconds since midnight, January 1, 1970 UTC.
To enable File Lock legal hold protections for a file
when calling b2_upload_file
,
use the following header:
X-Bz-File-Legal-Hold
for specifying the legal hold status of the file being uploaded. Valid values areon
andoff
.
b2_copy_file / b2_start_large_file
To enable File Lock retention settings or legal hold protections
for the destination file when calling
b2_copy_file
or when starting a large file
upload (
b2_start_large_file
), use the fileRetention
and/or legalHold
JSON parameters, e.g.:
"fileRetention": { "mode": "compliance", "retainUntilTimestamp": 1628942493000 }, "legalHold": "on"
fileRetention
has two fields, mode
(which
must be either "compliance"
or "governance"
to enable retention)
and retainUntilTimestamp
(which must be a future
timestamp, specified as a base 10 number of milliseconds since
midnight, January 1, 1970 UTC). Valid values for
legalHold
are "on"
and "off"
.
Configuring File Lock After File Upload
b2_update_file_retention
To configure File Lock retention settings for Backblaze B2 files
after upload, call
b2_update_file_retention
with the fileName
,
fileId
, and fileRetention
parameters. Updating
file retention settings requires the writeFileRetentions
application key capability.
{ "fileName": "example.txt", "fileId": "4_zb2f6f21365e1d29f6c59018f_f10076875fe98d4af_d20210514_m223128_c002_v0001108_t0050", "fileRetention": { "mode": "governance", "retainUntilTimestamp": 1628942493000 } }
fileRetention
has two fields, mode
(which
must be either "compliance"
or "governance"
to enable retention)
and retainUntilTimestamp
(which must be a future
timestamp, specified as a base 10 number of milliseconds since
midnight, January 1, 1970 UTC).
To shorten or remove an existing governance mode retention setting,
the bypassGovernance
parameter must also be specified
and set to true
, and the client must have
the bypassGovernance
application key capability.
To remove an existing governance mode retention setting,
the mode
should be set to null
, e.g.:
{ "fileName": "example.txt", "fileId": "4_zb2f6f21365e1d29f6c59018f_f10076875fe89ea3c_d20210514_m223128_c002_v0001108_t0050", "fileRetention": { "mode": null }, "bypassGovernance": true }
b2_update_file_legal_hold
To enable or disable File Lock legal hold for Backblaze B2
files after upload, call
b2_update_file_legal_hold
with the fileName
,
fileId
, and legalHold
parameters. Updating
legal hold settings requires the writeFileLegalHolds
application key capability.
{ "fileName": "example.txt", "fileId": "4_zb2f6f21365e1d29f6c59018f_f10076875fe89ea3c_d20210514_m223128_c002_v0001108_t0050", "legalHold": "on" }
Valid values for legalHold
are "on"
and
"off"
.
Accessing File Retention and Legal Hold Settings
To access individual file retention and legal hold settings when
listing, uploading, or copying B2 files (e.g.,
calling
b2_list_file_names
,
b2_get_file_info
,
b2_upload_file
, etc.), the
client must have the readFileRetentions
and readFileLegalHolds
application key capabilities,
respectively.
If the client has those capabilities, then the responses for such
API calls will include fileRetention
and legalHold
fields which include
an isClientAuthorizedToRead
boolean set
to true
and a value
field which contains
the actual value of the setting, e.g.:
"fileRetention": { "isClientAuthorizedToRead": true, "value": { "mode": "governance", "retainUntilTimestamp": 1628942493000 } }
"legalHold": { "isClientAuthorizedToRead": true, "value": "off" }
If the client does not have the readFileRetentions
and/or readFileLegalHolds
application key capability,
then isClientAuthorizedToRead
will be false
and value
will be null
for the respective
field, e.g.:
"fileRetention": { "isClientAuthorizedToRead": false, "value": null }