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.

NOTE: The Object Lock feature was previously referred to as "File Lock". The B2 API and documentation may still refer to this legacy term in some places.

How does Object Lock work?

Object Lock can be enabled on a bucket at the time the bucket is created, or as a one-time operation using b2_update_bucket. However, once enabled on a bucket, Object Lock cannot be disabled. For files in Object Lock-enabled buckets, you can assign Object 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. You cannot enable Object Lock on a restricted bucket (e.g. share buckets, snapshot) or on a bucket that contains source replication configuration.

Backblaze B2 Object Lock retention settings can be configured in either governance or compliance mode. Object Lock retention settings for files protected in governance mode can be modified or overridden by clients with appropriate application key capabilities. Object 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 Object 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.

After enabling Object Lock on a bucket containing files with metadata over the lower 2,048 byte limit, API requests to b2_update_file_retention and b2_update_file_legal_hold will be rejected. This is because setting file retention or legal hold on a file adds additional headers when the file is downloaded, for example, with b2_download_file_by_name. In such cases, you can use b2_copy_file with a REPLACE metadataDirective to copy the file, give it less metadata, and also specify the fileRetention and legalHold parameters. The original file can then be deleted with b2_delete_file_version.

NOTE: 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.

NOTE: If you customize the upload timestamp, then the Object Lock retention calculation (for retention set via the bucket default retention) will be based on the customized upload timestamp. Otherwise, this calculation will be based on the current date and time. For more information about custom upload timestamps, see b2_upload_file and b2_start_large_file.

Default Bucket Retention

To set default Object Lock retention settings for all files uploaded to an Object 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 Object 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 Object 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 Object Lock by default.

Replica files are created with the same upload timestamp as their source file. If the destination bucket has a default object lock retention period set, the retention period is calculated based on the timestamp inherited from the source file.

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 Object 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 a bucket's Object 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 Object 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 Object 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 Object Lock on File Upload

You may enable Object 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 Object Lock retention settings for a predetermined period of time when calling b2_upload_file, use the following headers:

X-Bz-File-Retention-Mode for Object Lock retention mode. Valid values are governance and compliance.
X-Bz-File-Retention-Retain-Until-Timestamp for Object Lock retention timestamp in the future, after which the intended Object Lock will expire. This header value must be specified as a base 10 number of milliseconds since midnight, January 1, 1970 UTC.

To enable Object 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 are on and off.

b2_copy_file / b2_start_large_file

To enable Object 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 Object Lock After File Upload

b2_update_file_retention

To configure Object 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
    }  
  }

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 Object 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".

Enabling Object Lock on an Existing Bucket

To enable Object Lock on an existing S3 Compatible bucket, call b2_update_bucket and set the fileLockEnabled parameter to true:

  {
    "accountId": "12f634bf3cbz",
    "bucketId": "e1256f0973908bfc71ed0c1z",
    "fileLockEnabled": true
  }

Once Object Lock is enabled on a bucket, a fileLockEnabled parameter value of false will not be accepted.

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
      }