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 are governance and compliance.
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 are on and off.

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

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
      }