S3 Object Locking

S3 Object Locking Overview

S3 object locking is a feature that helps prevent objects from being deleted or overwritten for a fixed amount of time or indefinitely.

S3 object locking can be enabled on an S3 bucket provided that the bucket's view is not simultaneously enabled for access via other protocols (SMB, NFS, NFSv4.1). Once S3 object locking is enabled on a view, it cannot be disabled. S3 object versioning is automatically enabled with S3 object locking.

There are two levels of protection with S3 object locking, called retention modes:

Governance mode, in which users can't overwrite or delete an object version or alter its lock settings unless they have special permissions. With governance mode, you protect objects against being deleted by most users, but you can still grant some users permission to alter the retention settings or delete the object if necessary. You can also use governance mode to test retention-period settings before creating a compliance-mode retention period.
To override or remove governance-mode retention settings, a user must have the s3:BypassGovernanceRetention permission and must explicitly include x-amz-bypass-governance-retention:true as a request header with any request that requires overriding governance mode.
Compliance mode, in which a protected object version can't be overwritten or deleted by any user. When an object is locked in compliance mode, its retention mode can't be changed, and its retention period can't be shortened. Compliance mode helps ensure that an object version can't be overwritten or deleted for the duration of the retention period.

There are two ways to manage object retention with object locking:

Retention period, which specifies a fixed period of time during which an object remains locked. During this period, your object is WORM-protected. This means that when an object is deleted or replaced, the version that was deleted or replaced is protected from being removed from the bucket, although it does cease to be the latest version and can only be accessed by its version ID.
Legal hold, which provides the same protection as a retention period, but it has no expiration date. Instead, a legal hold remains in place until you explicitly remove it. Legal holds are independent from retention periods.

When object locking is enabled on a bucket, each object in the bucket can have no lock, a retention lock or a legal hold. If you configure a default retention period, object versions that are placed in the bucket are automatically protected with a retention lock.

For detailed information about how object locking works, see the AWS S3 documentation page, How S3 Object Lock works.

For information about supported ways to manage object locking on buckets and objects, see the following sections:

Managing Object Locking via VMS

The following object locking features for buckets are available in VMS.

Caution
Once you enable object locking on a bucket, you cannot disable it or suspend versioning for that bucket.

Task	VAST Web UI Procedure
Enable object locking on a new bucket. Caution When you enable object locking on a bucket, object versioning is automatically enabled on the bucket as well.	When you create a new bucket via VMS directly, by creating a view and selecting S3 Bucket from the protocol options, you can enable locking with the Object Lock setting. This is only supported for views that are not exposed to other protocols. You can also set a default retention period with the S3 Retention Period setting. Without the default retention period, the object versions in the bucket are not automatically protected by a retention period or legal hold. With a default retention period, all object versions placed in the bucket are protected with that retention period.
Enable object locking on an existing bucket, set a default retention period, and set the retention mode.	When modifying a view via the VMS GUI, enable object locking on the S3 tab under S3 Features using the Object Lock setting, set the default retention period for objects in the S3 Retention Period field, and select a retention mode from the Retention Mode dropdown.
View object locking status.	See which views have object locking enabled in the S3 Locks column of the Views page in the VAST Web UI.

Task

VAST Web UI Procedure

Enable object locking on a new bucket.

Caution
When you enable object locking on a bucket, object versioning is automatically enabled on the bucket as well.

When you create a new bucket via VMS directly, by creating a view and selecting S3 Bucket from the protocol options, you can enable locking with the Object Lock setting. This is only supported for views that are not exposed to other protocols. You can also set a default retention period with the S3 Retention Period setting. Without the default retention period, the object versions in the bucket are not automatically protected by a retention period or legal hold. With a default retention period, all object versions placed in the bucket are protected with that retention period.

Enable object locking on an existing bucket, set a default retention period, and set the retention mode.

When modifying a view via the VMS GUI, enable object locking on the S3 tab under S3 Features using the Object Lock setting, set the default retention period for objects in the S3 Retention Period field, and select a retention mode from the Retention Mode dropdown.

View object locking status.

See which views have object locking enabled in the S3 Locks column of the Views page in the VAST Web UI.

Managing Object Locking via S3 Client Requests

You can send requests by S3 API to do the tasks described below for configuring and viewing object locking configurations on buckets and objects.

Bucket Operations

You can manage object lock configuration on buckets using the following API requests and headers. The operations require user permissions which must be granted through identity policies.

Task	S3 API Operation	S3 Permission Required
Enable object locking on a new bucket. Caution When you enable object locking on a bucket, object versioning is automatically enabled on the bucket as well.	Include the `x-amz-bucket-object-lock-enabled` header in the CreateBucket request. Caution Once you enable object locking on a bucket, you cannot disable it or suspend versioning for that bucket.	s3:PutBucketObjectLockConfiguration
Enable object locking on an existing bucket and set a default retention period	PutObjectLockConfiguration	s3:PutBucketObjectLockConfiguration
Get the Object Lock configuration of a bucket	GetObjectLockConfiguration	s3:GetObjectLockConfiguration

Task

S3 API Operation

S3 Permission Required

Enable object locking on a new bucket.

Caution
When you enable object locking on a bucket, object versioning is automatically enabled on the bucket as well.

Include the x-amz-bucket-object-lock-enabled header in the CreateBucket request.

Caution
Once you enable object locking on a bucket, you cannot disable it or suspend versioning for that bucket.

s3:PutBucketObjectLockConfiguration

Enable object locking on an existing bucket and set a default retention period

PutObjectLockConfiguration

s3:PutBucketObjectLockConfiguration

Get the Object Lock configuration of a bucket

GetObjectLockConfiguration

s3:GetObjectLockConfiguration

Object Operations

Task	S3 API Operations	Notes	S3 Permission Required
Retention Period Tasks
Set a retention configuration on an object.	PutObjectRetention	This includes setting the retention mode and setting an explicit retention period on the object. The explicit retention period overrides a default retention period set on the bucket.	s3:PutObjectRetention
Extend a retention period after setting a retention configuration on an object version.		To do this, submit a new lock request for the object version with a `Retain Until Date` that is later than the one currently configured for the object version.	s3:PutObjectRetention
Get the retention settings of an object.	GetObjectRetention	This includes the date and time and the retention mode.	s3:GetObjectRetention
Get the date and time when an object's lock is due to expire, along with other object information.	GetObject, HeadObject	The response includes the `x-amz-object-lock-retain-until-date` header if the user has the required permission to view it. This header indicates the date and time that the object's lock is due to expire, if applicable.	s3:GetObjectRetention
Get an object's retention mode, along with other object information.	GetObject, HeadObject	The response includes the `x-amz-object-lock-mode` header if the user has the required permission to view it. This header indicates the object's lock mode, if applicable. Compliance mode is not supported. Therefore, object lock mode is always `governance` if applicable.	s3:GetObjectRetention
Legal Hold Tasks
Apply a legal hold configuration to an object.	PutObjectLegalHold	Placing a legal hold on an object version doesn't affect the retention mode or retention period for that object version.	s3:PutObjectLegalHold
Get an object's current legal hold status.	GetObjectLegalHold, GetObject	The `GetObjectLegalHold` response indicates whether the specified object has a legal hold in place. With `GetObject`, the indication is returned in the `x-amz-object-lock-legal-hold` response header which is returned if the user has the required permission.	s3:GetObjectLegalHold
Operations that Require Bypassing Governance Mode
Overwrite or delete an object version or alter its lock settings, including shortening the retention period, and removing an object lock by placing a new lock with empty parameters.		You must explicitly include `x-amz-bypass-governance-retention:true` as a request header with any request that requires overriding governance mode.	s3:BypassGovernanceRetention

Documentation Index

S3 Object Locking