Workflow

Edit online

Refer to the IBM Cloud Storage Object API 2.5 Development Guide for additional specific API information for the scenarios discussed in this chapter.

Enable Object Lock on a bucket

Object Lock can be enabled on a bucket in two ways.

Enable object lock during bucket creation.
Enable object lock on an existing bucket.

During bucket creation, clients can specify an additional Object Lock configuration header (x-amz-bucket-object-lock-enabled) to enable the feature on the bucket.

Note: When clients enable Object Lock during bucket creation, Object Versioning will be automatically enabled on the bucket.

After bucket creation, clients can enable Object Lock on the bucket that uses the PUT bucket?object-lock request. When enabling Object Lock to on an existing bucket, object versioning must be enabled before enabling Object Lock.

Once Object Lock is enabled on a bucket, it cannot be disabled.

Adding/Modifying Default Configuration on a bucket

After bucket creation, clients can add or modify Object Lock Configuration to an existing bucket. Now clients can choose to do one of the following:

Enable Object Lock (if not done during bucket creation)
Enable Object Lock and configure Object Lock Default Retention.
Modify the existing Object Lock Default Retention on the bucket.

When a Default Retention is configured on the bucket, objects that are uploaded to the bucket have the default retention that is applied to the object at the time of object write, unless the object write request includes retention or legal hold headers. If the Default Retention is not configured for a bucket with object lock enabled, object versions that are written without retention or legal hold headers cannot be protected. Any changes to the bucket Default Retention only impact object versions added after the change. Existing objects in the bucket will not be impacted by such changes.

Important: See the IBM Cloud Storage Object API 2.5 Development Guide for more information on configuring Default Retention on an Object Lock enabled bucket.

Note: Only Bucket Owners are allowed to configure and view a bucket’s Object Lock Configuration.

Note: When an object write request is performed with one or more of the properly formatted Object Lock headers listed below, the Bucket Default Retention, if present, will NOT be applied to the object.

x-amz-object-lock-mode
x-amz-object-lock-retain-until-date
x-amz-object-lock-legal-hold

Object Upload

Objects Uploaded to an Object Lock enabled bucket can have the following protection states.

Object Protection State	Related Headers for Object Upload	Notes
Protected with Object specific Retention	x-amz-object-lock-retain-until-date x-amz-object-lock-mode	Supported modes are COMPLIANCE and GOVERNANCE. The object version can be deleted only after the retain-until-date has elapsed in case of COMPLIANCE. However, with GOVERNANCE mode it can be shortened or deleted with x-amz-bypass-governance-retention header and appropriate BypassGovernanceRetention permission.
Protected with Legal Hold	x-amz-object-lock-legal-hold	The header value must be set to ON to enable the protection for the object version. The object version can be deleted only after the legal hold has been set to OFF or removed for the object version.
Protected with Retention and Legal Hold	x-amz-object-lock-retain-until-date x-amz-object-lock-mode x-amz-object-lock-legal-hold	The object version can be deleted only after the retain-until-date has elapsed and the legal hold has been set to OFF or removed, for the object version.
Protected with Bucket Default Retention	None	If the bucket is configured with a default retention configuration and an object version is uploaded without any retention or legal hold headers, the object inherits the default retention configuration of the bucket.
Unprotected	None	If the object version is uploaded without any retention or legal hold headers AND the bucket has object lock enabled, but does not have a default retention configuration, then the object version is left unprotected.

Note: To ensure data integrity, if an object is uploaded to an Object Lock Enabled bucket and have Object Lock Protection applied to the object either through retention headers or default retention, the object upload request must include either a Content-MD5 or a x-amz-checksum- header or use V4 signing with a signed payload.

Note: Only Bucket Owners are allowed to configure Object Protection on an object. Thus, only bucket owners are allowed to use the object lock headers. Users with object write permissions can still upload objects to an Object Lock enabled bucket and have the object inherit the bucket’s Default Object Lock Retention of the bucket.

Add/remove/modify Protection After Object Upload

Clients can choose to add or modify Protection on an object version that uses the PUT object?retention or PUT object?legal-hold commands.

When using the PUT Object?retention request, clients can update the retain until date of an object, provided the new date is later than the current time and later than the existing retain until date. However, if the object is in GOVERNANCE mode, and the requester has the BypassGovernanceRetention permission along with the x-amz-bypass-governance-retention: true header, the retain until date can also be shortened, or entirely removed.

When using the PUT object?legal-hold request, clients can enable or disable the legal hold on the object.

Note: Only Bucket Owners are allowed to configure Object Protection on an object by means of the legal-hold and retention commands. Bucket Owners can add Protection to objects uploaded by other users. Non-bucket owners can upload objects to an Object Lock enabled bucket and those objects inherit the default retention if it is configured on the bucket.

Reading Object Lock Protection for Objects

When reading objects from an Object Lock Enabled Bucket, only bucket owners see object lock response headers.

Object Deletion

Object versions that are protected with either Active Retention Period or an Active Legal Hold or both, cannot be deleted. Object versions can only be deleted when the time of the delete request has exceeded the Retain Until Date for the object version and the Legal Hold has been removed from the object. However, if object is in GOVERNANCE mode and Legal Hold is off, object can be deleted even before Retain Until Date when the requester has the necessary BypassGovernanceRetention permission, and the x-amz-bypass-governance-retention: true header included in the request. In all cases, deletion must reference the specific version of the object to be removed.