Skip to main content
A newer release of this product is available.

Use S3 REST API to configure S3 Object Lock

Contributors netapp-madkat netapp-perveilerk ssantho3
PDFs

If the global S3 Object Lock setting is enabled for your StorageGRID system, you can create buckets with S3 Object Lock enabled. You can specify default retention for each bucket or retention settings for each object version.

How to enable S3 Object Lock for a bucket

If the global S3 Object Lock setting is enabled for your StorageGRID system, you can optionally enable S3 Object Lock when you create each bucket.

S3 Object Lock is a permanent setting that can only be enabled when you create a bucket. You can't add or disable S3 Object Lock after a bucket is created.

To enable S3 Object Lock for a bucket, use either of these methods:

  • Create the bucket using the Tenant Manager. See Create S3 bucket.

  • Create the bucket using a PUT Bucket request with the x-amz-bucket-object-lock-enabled request header. See Operations on buckets.

S3 Object Lock requires bucket versioning, which is enabled automatically when the bucket is created. You can't suspend versioning for the bucket. See Object versioning.

Default retention settings for a bucket

When S3 Object Lock is enabled for a bucket, you can optionally enable default retention for the bucket and specify a default retention mode and default retention period.

Default retention mode

  • In COMPLIANCE mode:

    • The object can't be deleted until its retain-until-date is reached.

    • The object's retain-until-date can be increased, but it can't be decreased.

    • The object's retain-until-date can't be removed until that date is reached.

  • In GOVERNANCE mode:

    • Users with the s3:BypassGovernanceRetention permission can use the x-amz-bypass-governance-retention: true request header to bypass retention settings.

    • These users can delete an object version before its retain-until-date is reached.

    • These users can increase, decrease, or remove an object's retain-until-date.

Default retention period

Each bucket can have a default retention period specified in years or days.

How to set default retention for a bucket

To set the default retention for a bucket, use either of these methods:

PUT Object Lock Configuration

The PUT Object Lock Configuration request allows you to set and modify the default retention mode and default retention period for a bucket that has S3 Object Lock enabled. You can also remove previously configured default retention settings.

When new object versions are ingested to the bucket, the default retention mode is applied if x-amz-object-lock-mode and x-amz-object-lock-retain-until-date aren't specified. The default retention period is used to calculate the retain-until-date if x-amz-object-lock-retain-until-date is not specified.

If the default retention period is modified after ingest of an object version, the retain-until-date of the object version remains the same and is not recalculated using the new default retention period.

You must have the s3:PutBucketObjectLockConfiguration permission, or be account root, to complete this operation.

The Content-MD5 request header must be specified in the PUT request.

Request example

This example enables S3 Object Lock for a bucket and sets the default retention mode to COMPLIANCE and the default retention period to 6 years.

PUT /bucket?object-lock HTTP/1.1
Accept-Encoding: identity
Content-Length: 308
Host: host
Content-MD5: request header
User-Agent: s3sign/1.0.0 requests/2.24.0 python/3.8.2
X-Amz-Date: date
X-Amz-Content-SHA256: authorization-string
Authorization: authorization-string

<ObjectLockConfiguration>
    <ObjectLockEnabled>Enabled</ObjectLockEnabled>
    <Rule>
        <DefaultRetention>
            <Mode>COMPLIANCE</Mode>
            <Years>6</Years>
        </DefaultRetention>
    </Rule>
</ObjectLockConfiguration>

How to determine the default retention for a bucket

To determine if S3 Object Lock is enabled for a bucket and to see the default retention mode and retention period, use either of these methods:

  • View the bucket in the Tenant Manager. See View S3 buckets.

  • Issue a GET Object Lock Configuration request.

GET Object Lock Configuration

The GET Object Lock Configuration request allows you to determine if S3 Object Lock is enabled for a bucket and, if it is enabled, see if there is a default retention mode and retention period configured for the bucket.

When new object versions are ingested to the bucket, the default retention mode is applied if x-amz-object-lock-mode is not specified. The default retention period is used to calculate the retain-until-date if x-amz-object-lock-retain-until-date is not specified.

You must have the s3:GetBucketObjectLockConfiguration permission, or be account root, to complete this operation.

Request example

GET /bucket?object-lock HTTP/1.1
Host: host
Accept-Encoding: identity
User-Agent: aws-cli/1.18.106 Python/3.8.2 Linux/4.4.0-18362-Microsoft botocore/1.17.29
x-amz-date: date
x-amz-content-sha256: authorization-string
Authorization: authorization-string

Response example

HTTP/1.1 200 OK
x-amz-id-2: iVmcB7OXXJRkRH1FiVq1151/T24gRfpwpuZrEG11Bb9ImOMAAe98oxSpXlknabA0LTvBYJpSIXk=
x-amz-request-id: B34E94CACB2CEF6D
Date: Fri, 04 Sep 2020 22:47:09 GMT
Transfer-Encoding: chunked
Server: AmazonS3

<?xml version="1.0" encoding="UTF-8"?>
<ObjectLockConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <ObjectLockEnabled>Enabled</ObjectLockEnabled>
    <Rule>
        <DefaultRetention>
            <Mode>COMPLIANCE</Mode>
            <Years>6</Years>
        </DefaultRetention>
    </Rule>
</ObjectLockConfiguration>

How to specify retention settings for an object

A bucket with S3 Object Lock enabled can contain a combination of objects with and without S3 Object Lock retention settings.

Object-level retention settings are specified using the S3 REST API. The retention settings for an object override any default retention settings for the bucket.

You can specify the following settings for each object:

  • Retention mode: Either COMPLIANCE or GOVERNANCE.

  • Retain-until-date: A date specifying how long the object version must be retained by StorageGRID.

    • In COMPLIANCE mode, if the retain-until-date is in the future, the object can be retrieved, but it can't be modified or deleted. The retain-until-date can be increased, but this date can't be decreased or removed.

    • In GOVERNANCE mode, users with special permission can bypass the retain-until-date setting. They can delete an object version before its retention period has elapsed. They can also increase, decrease, or even remove the retain-until-date.

  • Legal hold: Applying a legal hold to an object version immediately locks that object. For example, you might need to put a legal hold on an object that is related to an investigation or legal dispute. A legal hold has no expiration date, but remains in place until it is explicitly removed.

    The legal hold setting for an object is independent of the retention mode and the retain-until-date. If an object version is under a legal hold, no one can delete that version.

To specify S3 Object Lock settings when adding an object version to a bucket, issue a PUT Object, PUT Object - Copy, or Initiate Multipart Upload request.

You can use the following:

  • x-amz-object-lock-mode, which can be COMPLIANCE or GOVERNANCE (case sensitive).

    Note If you specify x-amz-object-lock-mode, you must also specify x-amz-object-lock-retain-until-date.

  • x-amz-object-lock-retain-until-date

    • The retain-until-date value must be in the format 2020-08-10T21:46:00Z. Fractional seconds are allowed, but only 3 decimal digits are preserved (milliseconds precision). Other ISO 8601 formats aren't allowed.

    • The retain-until-date must be in the future.

  • x-amz-object-lock-legal-hold

    If legal hold is ON (case-sensitive), the object is placed under a legal hold. If legal hold is OFF, no legal hold is placed. Any other value results in a 400 Bad Request (InvalidArgument) error.

If you use any of these request headers, be aware of these restrictions:

  • The Content-MD5 request header is required if any x-amz-object-lock-* request header is present in the PUT Object request. Content-MD5 is not required for PUT Object - Copy or Initiate Multipart Upload.

  • If the bucket does not have S3 Object Lock enabled and a x-amz-object-lock-* request header is present, a 400 Bad Request (InvalidRequest) error is returned.

  • The PUT Object request supports the use of x-amz-storage-class: REDUCED_REDUNDANCY to match AWS behavior. However, when an object is ingested into a bucket with S3 Object Lock enabled, StorageGRID will always perform a dual-commit ingest.

  • A subsequent GET or HEAD Object version response will include the headers x-amz-object-lock-mode, x-amz-object-lock-retain-until-date, and x-amz-object-lock-legal-hold, if configured and if the request sender has the correct s3:Get* permissions.

You can use the s3:object-lock-remaining-retention-days policy condition key to limit the minimum and maximum allowable retention periods for your objects.

How to update retention settings for an object

If you need to update the legal hold or retention settings for an existing object version, you can perform the following object subresource operations:

  • PUT Object legal-hold

    If the new legal-hold value is ON, the object is placed under a legal hold. If the legal-hold value is OFF, the legal hold is lifted.

  • PUT Object retention

    • The mode value can be COMPLIANCE or GOVERNANCE (case sensitive).

    • The retain-until-date value must be in the format 2020-08-10T21:46:00Z. Fractional seconds are allowed, but only 3 decimal digits are preserved (milliseconds precision). Other ISO 8601 formats aren't allowed.

    • If an object version has an existing retain-until-date, you can only increase it. The new value must be in the future.

How to use GOVERNANCE mode

Users who have the s3:BypassGovernanceRetention permission can bypass the active retention settings of an object that uses GOVERNANCE mode. Any DELETE or PUT Object retention operations must include the x-amz-bypass-governance-retention:true request header. These users can perform these additional operations:

  • Perform DELETE Object or DELETE Multiple Objects operations to delete an object version before its retention period has elapsed.

    Objects that are under a legal hold can't be deleted. Legal hold must be OFF.

  • Perform PUT Object retention operations that change an object version's mode from GOVERNANCE to COMPLIANCE before the object's retention period has elapsed.

    Changing the mode from COMPLIANCE to GOVERNANCE is never allowed.

  • Perform PUT Object retention operations to increase, decrease, or remove an object version's retention period.

Related information