Enable Object Lock with the Native API

You can configure default bucket retention settings using the Backblaze B2 Cloud Storage Native API. For more information, see Object Lock.

Call the b2_update_bucket operation using the defaultRetention parameter as in the following example:

      "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 (for example, b2_list_buckets) include a fileLockConfiguration field that includes an isClientAuthorizedToRead Boolean value that is set to true and a value field that contains the actual bucket Object Lock settings.

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

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

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

      "fileLockConfiguration": {
        "isClientAuthorizedToRead": false,
        "value": null
      }

Enable Object Lock on File Upload

You can enable Object Lock retention settings (or override default bucket retention settings) and legal hold protections for Backblaze 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.

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 expires. 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.

Enable Object Lock for the Destination 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".

Configure Object Lock After File Upload

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

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 as in the following example. 

  {
    "fileName": "example.txt",
    "fileId": "4_zb2f6f21365e1d29f6c59018f_f10076875fe89ea3c_d20210514_m223128_c002_v0001108_t0050",
    "fileRetention": {
      "mode": null
    },
    "bypassGovernance": true
  }

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.

Configure Legal Hold After File Upload

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

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.

Enable 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.

Access 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 as in the example below. 

      "fileRetention": {
        "isClientAuthorizedToRead": false,
        "value": null
      }

Legal Hold

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.

Timestamp

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.