Object Lock
In this article:
Object Lock#
Object Lock protects object versions from being deleted or overwritten. It uses a Write Once Read Many (WORM) mechanism for an object storage. Object Lock can be used to comply with legal requirements for data retention periods, prevent data modifications, and protect data against cyberattacks, such as encryption by ransomware.
Object versions can be locked either for a predefined period of time (Retention Period) or for an unlimited term (Legal Hold). These locking methods are independent of each other and can be applied to the same object version simultaneously. For different versions of the same object, different locking periods can be set and perpetual locking can be enabled or disabled.
When locking for a definite period, two modes are supported: Compliance and Governance. The first provides for strict locking: no one can delete or overwrite the protected version of the object. In addition, the locking mode cannot be changed, and the retention period of the version can only be increased. In the second mode, the retention period can be changed by any user with rights to the object storage, so it makes sense to use this mode only for protection against accidental deletions, but not cyber threats.
Object locking is only available for those buckets for which it was explicitly enabled at creation using –object-lock-enabled-for-bucket option (see bucket creation example). When such a bucket is created, object versioning is enabled, which cannot be suspended. To automatically lock all uploaded objects, set a default policy.
You can override locking settings for a particular object when uploading it (see :ref`example of uploading an object with the preset locking policy <PutAndLockObject>`). Individual locking can also be used when the default policy for a bucket is not specified. The default policy can be modified or canceled, but its modification does not affect locking of already uploaded object versions.
When uploading an object with the same name (key in S3 terminology) to a bucket, a new version of the object is created. The previous version remains locked according to the specified locking parameters. When deleting a locked object, a delete marker is created for the latest version of the object, just like when deleting an unlocked object. However, the version is just marked for deletion, but still protected therefrom.
In Compliance mode, a locked version of an object cannot be deleted until the retention period expires. In Governance mode, a version can be deleted by bypassing the lock (option x-amz-bypass-governance-retention). If an object version is also subject to Legal Hold, it must be removed before deleting the version (see example of deleting an object version).
Locking can also be set up using aws s3api utility.
PutObjectLockConfiguration#
It specifies the default policy for locking objects in a bucket. This policy applies to all objects being uploaded unless other locking parameters are specified for them.
You can omit setting a default policy and specify locking parameters for each object separately when uploading it. Even with a default policy set, you can also specify your own locking parameters for a particular object when uploading it (see example of a request with the locking of the uploaded object).
This method can also be used to modify the default policy. To cancel the default locking, pass an empty rule in the request body.
Request example (setting a default policy)#
Example of setting a policy to lock the uploaded objects for 365 days in GOVERNANCE mode. Instead of retention days, you can specify years.
Note
If an object version is subject to an object lock in GOVERNANCE mode, such version can only be deleted when its retention period expires. However, you can extend the retention period using PutObjectRetention method.
Request
PUT /bucket1?object-lock=null HTTP/1.1
Host: s3.k2.cloud
Content-MD5: iaaXsYKGHBn4bP0RmNeHkQ==
Content-Type: application/json
X-Amz-Content-Sha256: beaead3198f7da1e70d03ab969765e0821b24fc913697e929e726aeaebf0eba3
X-Amz-Date: 20240805T113757Z
Authorization: AWS4-HMAC-SHA256 Credential=project:user@company/20220530/{region}/s3/aws4_request, SignedHeaders=content-length;content-md5;content-type;host;x-amz-content-sha256;x-amz-date, Signature=fe36e9908d98bd1c31de9018c3bb1190927519b6caafbdc603a9348b15ad241a
Content-Length: 289
<ObjectLockConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<ObjectLockEnabled>Enabled</ObjectLockEnabled>
<Rule>
<DefaultRetention>
<Days>365</Days>
<Mode>COMPLIANCE</Mode>
</DefaultRetention>
</Rule>
</ObjectLockConfiguration>
Sample Response#
Response
HTTP/1.1 200
x-amz-request-id: tx000009502b4d37552e406-0066b0c117-b929c455-default
content-length: 0
date: Mon, 05 Aug 2024 08:33:28 GMT
Request example (canceling the default policy)#
Request
PUT /bucket1?object-lock=null HTTP/1.1
Host: s3.k2.cloud
Content-MD5: plNlCWpKYPtD4d/5BLjIsg==
Content-Type: application/json
X-Amz-Content-Sha256: beaead3198f7da1e70d03ab969765e0821b24fc913697e929e726aeaebf0eba3
X-Amz-Date: 20240805T120234Z
Authorization: AWS4-HMAC-SHA256 Credential=project:user@company/20220530/{region}/s3/aws4_request, SignedHeaders=content-length;content-md5;content-type;host;x-amz-content-sha256;x-amz-date, Signature=74c19d49039c2f6acd13b0f38a3cbfacf9676a2d620602c7e4b500c530ae06d3
Content-Length: 152
<ObjectLockConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<ObjectLockEnabled>Enabled</ObjectLockEnabled>
</ObjectLockConfiguration>
Sample Response#
Response
HTTP/1.1 200
x-amz-request-id: tx00000c9727a514fb22d88-0066b0bf22-b9ce00b3-default
content-length: 0
date: Mon, 05 Aug 2024 08:33:28 GMT
GetObjectLockConfiguration#
It returns the default policy for locking objects in a bucket.
Sample Request#
Request
GET /bucket1?object-lock=null HTTP/1.1
Host: s3.k2.cloud
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
X-Amz-Date: 20240805T083424Z
Authorization: AWS4-HMAC-SHA256 Credential=project:user@company/20220530/{region}/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=b6eb4c29f82a14deb13cb1aaf669c29d5cd3e4ef3f85047ee5d15b6e375235a6
Sample Response#
Example of a response if Object Lock was disabled when the bucket was created
HTTP/1.1 404 Not Found
content-length: 269
x-amz-request-id: tx00000f6e86038c86ccae0-0066b0b822-b9cde984-default
accept-ranges: bytes
content-type: application/xml
date: Mon, 05 Aug 2024 08:33:28 GMT
<?xml version="1.0" encoding="UTF-8"?>
<Error>
<Code>ObjectLockConfigurationNotFoundError</Code>
<Message></Message>
<BucketName>doc-test</BucketName>
<RequestId>tx00000f6e86038c86ccae0-0066b0b822-b9cde984-default</RequestId>
<HostId>b9cde984-default-default</HostId>
</Error>
Example of a response if no default policy is set for the bucket
HTTP/1.1 200 OK
x-amz-request-id: tx00000d3bd8035ad65d9a4-0066b08e58-b929c455-default
content-type: application/xml
content-length: 135
date: Mon, 05 Aug 2024 08:33:28 GMT
<?xml version="1.0" encoding="UTF-8"?>
<ObjectLockConfiguration>
<ObjectLockEnabled>Enabled</ObjectLockEnabled>
</ObjectLockConfiguration>
Example of a response if a default policy is set for the bucket
HTTP/1.1 200 OK
x-amz-request-id: tx00000445ea64132709e83-0066b0b8ad-b929d8f0-default
content-type: application/xml
content-length: 224
date: Mon, 05 Aug 2024 08:33:28 GMT
<?xml version="1.0" encoding="UTF-8"?>
<ObjectLockConfiguration>
<ObjectLockEnabled>Enabled</ObjectLockEnabled>
<Rule>
<DefaultRetention>
<Mode>COMPLIANCE</Mode>
<Days>365</Days>
</DefaultRetention>
</Rule>
</ObjectLockConfiguration>
PutObjectRetention#
The request allows you to increase the retention period for an object version in COMPLIANCE mode, or to change the lock mode and retention period for an object version in GOVERNANCE mode. If the version is not specified, the lock parameters are changed for the latest version of the object.
If COMPLIANCE mode is set for the object version, then any attempt to reduce the retention period or change the lock mode will result in an Access denied error. If GOVERNANCE mode is set for the object version, then in order to reduce the retention period or change the lock mode, pass x-amz-bypass-governance-retention header with true value to bypass the lock.
Attention
Locking parameters of an object version with GOVERNANCE mode can be modified by any project user with full privileges for the object storage (if S3FullAccess policy is assigned to a user or he/she is a member of IAM group, to which such a policy is assigned).
Sample Request#
Request
PUT /bucket1/image.svg?retention=null HTTP/1.1
Host: s3.k2.cloud
x-amz-bypass-governance-retention: true
Content-Type: application/json
X-Amz-Content-Sha256: beaead3198f7da1e70d03ab969765e0821b24fc913697e929e726aeaebf0eba3
X-Amz-Date: 20240806T070611Z
Authorization: AWS4-HMAC-SHA256 Credential=project:user@company/20240806/{region}/s3/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-bypass-governance-retention;x-amz-content-sha256;x-amz-date, Signature=7d10fc5ef6ead8008cf91e3420032660932760eb11dd89443da9c566602a8470
Content-Length: 158
<?xml version="1.0" encoding="UTF-8"?>
<Retention>
<Mode>GOVERNANCE</Mode>
<RetainUntilDate>2024-09-01T01:00:00.00Z</RetainUntilDate>
</Retention>
Response
HTTP/1.1 200
x-amz-request-id: tx00000f5497cf18231800b-0066b1cb2b-b929c455-default
content-length: 0
date: Mon, 05 Aug 2024 08:33:28 GMT
GetObjectRetention#
Request for information about the lock mode (COMPLIANCE or GOVERNANCE) and retention period of the object version. If the version is not specified, the request returns information about the lock parameters for the latest version.
Sample Request#
Request
GET /bucket1/image.jpg?retention=null&versionId=Qy1mg2c2a0gbssjcAMbYVY4w.FB0.we HTTP/1.1
Host: s3.k2.cloud
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
X-Amz-Date: 20240806T062315Z
Authorization: AWS4-HMAC-SHA256 Credential=project:user@company/20240806/{region}/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=5bfaa54a63cb0226beb63e631a0d782de61c13c9ddac8b7c363336b84ca81656
Response
HTTP/1.1 200
x-amz-request-id: tx0000075c5d7514860b31b-0066b1c11b-b9b75b52-default
content-type: application/xml
content-length: 149
date: Mon, 05 Aug 2024 08:33:28 GMT
<?xml version="1.0" encoding="UTF-8"?>
<Retention>
<Mode>COMPLIANCE</Mode>
<RetainUntilDate>2024-11-20T00:00:00.000000000Z</RetainUntilDate>
</Retention>
PutObjectLegalHold#
It sets/removes Legal Hold for an object version. If the version is not specified, the lock status of the latest version is changed.
Attention
The Legal Hold status can be modified by any project user with full privileges for the object storage (if S3FullAccess policy is attached to the user or he/she is a member of IAM group, to which such a policy is attached).
Sample Request#
Request
PUT /bucket1/image.svg?legal-hold=null&versionId=N7Xv5VGagklPKnyOq9DHHfVzaAH4Zlj HTTP/1.1
Host: s3.k2.cloud
Content-Type: application/json
X-Amz-Content-Sha256: beaead3198f7da1e70d03ab969765e0821b24fc913697e929e726aeaebf0eba3
X-Amz-Date: 20240806T061057Z
Authorization: AWS4-HMAC-SHA256 Credential=project:user@company/20240806/{region}/s3/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-content-sha256;x-amz-date, Signature=5e6e5ebc15979fc61a7665d148de6f567ceea699a46c00d5f57e9645bd37a2c4
Content-Length: 97
<LegalHold xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>ON</Status>
</LegalHold>
Sample Response#
Response
HTTP/1.1 200
x-amz-request-id: tx0000085068c14cd954f6a-0066b1be39-b9b75b52-default
content-length: 0
date: Mon, 05 Aug 2024 08:33:28 GMT
GetObjectLegalHold#
Request for information about the Legal Hold status of an object version. If the version is not specified, the request returns information about the lock status of the latest version. If the lock status is not defined, the Object Lock Configuration Not Found error is returned.
Sample Request#
Request
GET /bucket1/image.svg?legal-hold=null&versionId=N7Xv5VGagklPKnyOq9DHHfVzaAH4Zlj HTTP/1.1
Host: s3.k2.cloud
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
X-Amz-Date: 20240806T054235Z
Authorization: AWS4-HMAC-SHA256 Credential=project:user@company/20240806/{region}/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=1b46638a5f455bcbe743ca23d6c63c80ec54b087a67a2b483138bde06932a55f
Sample Response#
Response
HTTP/1.1 200
x-amz-request-id: tx00000cb71e50c1724baa3-0066b1b8a6-b9b5e844-default
content-type: application/xml
content-length: 80
date: Mon, 05 Aug 2024 08:33:28 GMT
<?xml version="1.0" encoding="UTF-8"?>
<LegalHold>
<Status>ON</Status>
</LegalHold>