How to use the S3 Object Locking feature

13 min

This guide presents the steps required for configuring and using the S3 Object Locking feature using curl and the AWS CLI.

Prerequisites

Before proceeding with configuring object locking please perform the following steps

  1. Make sure you have a Swarm 14.0+ cluster with a search feed pointing to an Elasticsearch 7+ cluster; also make sure to issue the requests in this guide through a Content Gateway 7.6 or higher.

  2. Create a tenant, a domain in that tenant and a bucket, using either the Content UI or the Content Gateway’s Management API, as follows:

    1. Create a tenant.

      curl -XPUT -i -u caringoadmin:caringo "http://192.168.8.109:9090/_admin/manage/tenants/example.tenant.com"

    2. Create a domain within that tenant.

      curl -XPUT -i -u caringoadmin:caringo "http://192.168.8.109:9090/_admin/manage/tenants/example.tenant.com/domains/locking.example.com"

    3. Create a bucket in the domain.

      curl -XPUT -i -u caringoadmin:caringo "http://192.168.8.109:9090/_admin/manage/tenants/example.tenant.com/domains/locking.example.com/buckets/b1"

  3. Enable versioning at the cluster-level. You can do that through the swarmctl utility available in our support bundle https://support.cloud.datacore.com/tools/swarm-support-tools.tgz, by running the following command from within the dist/ folder.

    ./swarmctl -C policy.versioning -V "allowed" -d <IP of any Swarm node>

  4. Enable versioning for the newly created domain.

    curl -XCOPY -i -H "Policy-Versioning: enabled" -u caringoadmin:caringo "http://192.168.8.109:9090?domain=locking.example.com&preserve"

  5. Enable versioning for the newly created bucket.

    curl -XCOPY -i -H "Policy-Versioning: enabled" -u caringoadmin:caringo "http://192.168.8.109:9090/b1?domain=locking.example.com&preserve"

  6. In order to use the S3 API, create an S3 token for the user that’s going to manage object locking on the bucket. In the following examples, that role will be played by someuser. Write down the token UUID outputted by the request below which will be your S3 AWS_ACCESS_KEY_ID and the secret that you’ve configured for this token, which will be your S3 AWS_SECRET_ACCESS_KEY.

    curl -H "x-user-secret-key-meta: somesecret" -H "x-user-token-expires-meta: +365" -H 'x-owner-meta: someuser' -XPOST "http://192.168.8.109:9090/.TOKEN/?domain=locking.example.com" -u caringoadmin:caringo

  7. The user that will manage object locking on the bucket needs to be either the bucket’s owner or a user with admin-level permissions for that bucket. The following requests grant all privileges on the bucket to someuser, which is the user that we’re going to employ in the next steps.

    curl -XPUT -u caringoadmin:caringo -H "Content-Type: application/json+policy" "http://192.168.8.109:9090/b1?domain=locking.example.com&policy" --data-binary '{ "Version": "2008-10-17", "Id": "Unnamed Policy", "Statement": [ { "Sid": "1: Custom", "Effect": "Allow", "Principal": { "user": [ "someuser" ], "group": [] }, "Action": [ "*" ], "Resource": "*" } ] }'

All the above steps need to be performed by an user that has the required administrative permissions at the tenant, domain and bucket levels. In these examples the requests were issued by the caringoadmin user which is configured as the root-level admin user.

Configuring Object Locking through the SCSP API

A. Enabling object locking on the bucket and all subsequently created objects

In this case, the object locking parameters that you will apply through the following request will be automatically applied to all the objects that you write onwards, unless you explicitly set the object-locking headers when writing an object. In the latter case, Gateway will always use the maximum of either the bucket default retention duration or the duration specified in a per-object request.

Enabling object-locking at the bucket level through SCSP requires the following steps:

  1. Do a PUT /<bucket>?objectlock=<defaultmode> [ :<defaultperiod> ] where

    1. defaultmode can be either "governance" or "compliance"

    2. defaultperiod is optional; it is a number of years (y) or days (d), eg. 1y or 20d.

      curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1?domain=locking.example.com&objectlock=compliance:20d" -u someuser:caringo

  2. (Optional) Check that object-locking was enabled at the bucket level by issuing a GET /<bucket>?objectlock and checking that the following headers exist and that the response body says: Object locking is enabled on bucket

    1. x-object-lock-meta-status: ENABLED

    2. (Optionally) x-object-lock-meta-default: <GOVERNANCE|COMPLIANCE>[:<duration>]

      curl --location-trusted -i "http://192.168.8.109:9090/b1?domain=locking.example.com&objectlock" -u someuser:caringo HTTP/1.1 200 OK Date: Mon, 25 Oct 2021 06:37:33 GMT Gateway-Request-Id: 55C57E6997420CD2 Server: CAStor Cluster/14.0.0 Via: 1.1 192.168.8.109 (Cloud Gateway SCSP/7.6.0) Gateway-Protocol: scsp X-Object-Lock-Meta-Status: ENABLED Content-Length: 39 Object locking is enabled on bucket b1

All the objects that you write/modify after this, will have the bucket-level object-locking specification automatically applied to them. To verify this do the following:

  1. Create a new object in the bucket.

    curl --location-trusted -i -XPOST --data-binary 'test' "http://192.168.8.109:9090/b1/file1?domain=locking.example.com" -u someuser:caringo

  2. Make sure the object is locked according to the locking configuration defined at the bucket level, namely that it has the following headers:

    1. X-Object-Lock-Meta-Mode: COMPLIANCE

    2. X-Object-Lock-Meta-Retain-until-date: <current date + 50 days>

      curl --location-trusted -I "http://192.168.8.109:9090/b1/file1?domain=locking.example.com" -u someuser:caringo HTTP/1.1 200 OK Date: Fri, 22 Oct 2021 08:48:16 GMT Gateway-Request-Id: 09EC017DBBD195E6 Server: CAStor Cluster/14.0.0 Via: 1.1 192.168.8.109 (Cloud Gateway SCSP/7.6.0) Gateway-Protocol: scsp Castor-System-CID: e5c51ad561fcc0f361dd7c941a004ce6 Castor-System-Cluster: swarm.demo.internal Castor-System-Created: Fri, 22 Oct 2021 08:46:39 GMT Castor-System-IsVersioned: True Castor-System-Name: file1 Castor-System-Version: 1634892399.199 Content-Type: application/x-www-form-urlencoded Last-Modified: Fri, 22 Oct 2021 08:46:39 GMT X-Last-Modified-By-Meta: someuser@ X-Owner-Meta: someuser ETag: "ba2263c7ff58ebc15526fbafc1076787" Castor-System-Path: /locking.example.com/b1/file1 Castor-System-Domain: locking.example.com Volume: fdd5be4d6b82c11a9c68e89106281fa4 Content-MD5: CY9rzUYh03PK3k6DJie09g== X-Object-Lock-Meta-Mode: COMPLIANCE X-Object-Lock-Meta-Retain-until-date: Thu, 11 Nov 2021 08:46:38 GMT Content-Length: 4

B. Enabling object locking on the bucket without automatically setting it on the objects written afterwards.

For users that want object locking enabled on the bucket, but not automatically applied to all subsequently created objects/versions, the following request needs to be performed.

curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1?domain=locking.example.com&objectlock=" -u someuser:caringo

In order to verify that object-locking is not automatically set on a new object (i.e. new objects are unlocked unless the user explicitly locks them when creating them) do the following:

  1. Create a new object.

    curl --location-trusted -i -XPOST --data-binary 'test' "http://192.168.8.109:9090/b1/file2?domain=locking.example.com" -u someuser:caringo

  2. Check that it does not have the X-Object-Lock-Meta-Mode and X-Object-Lock-Meta-Retain-until-date headers.

    curl --location-trusted -I "http://192.168.8.109:9090/b1/file2?domain=locking.example.com" -u someuser:caringo HTTP/1.1 200 OK Date: Fri, 22 Oct 2021 08:56:10 GMT Gateway-Request-Id: 36555A75CE064B5C Server: CAStor Cluster/14.0.0 Via: 1.1 192.168.8.109 (Cloud Gateway SCSP/7.6.0) Gateway-Protocol: scsp Castor-System-CID: e5c51ad561fcc0f361dd7c941a004ce6 Castor-System-Cluster: swarm.demo.internal Castor-System-Created: Fri, 22 Oct 2021 08:53:31 GMT Castor-System-IsVersioned: True Castor-System-Name: file2 Castor-System-Version: 1634892811.229 Content-Type: application/x-www-form-urlencoded Last-Modified: Fri, 22 Oct 2021 08:53:31 GMT X-Last-Modified-By-Meta: someuser@ X-Owner-Meta: someuser ETag: "321375af02fecb94ca33dee20aa17f0c" Castor-System-Path: /locking.example.com/b1/file2 Castor-System-Domain: locking.example.com Volume: eb4715ce21e9a8a20e0b4397bdc825d5 Content-MD5: CY9rzUYh03PK3k6DJie09g== Content-Length: 4

At this point you can create another object for which you can define your object-locking parameters of choice by setting the X-Object-Lock-Meta-Mode and X-Object-Lock-Meta-Retain-until-date headers, as follows:

  1. Create the object, making sure to set the aforementioned headers.

    curl --location-trusted -i -XPOST --data-binary 'test' -H "x-object-lock-meta-mode: COMPLIANCE" -H "x-object-lock-meta-retain-until-date: Sat, 23 Oct 2021 08:53:31 GMT" "http://192.168.8.109:9090/b1/file3?domain=locking.example.com" -u someuser:caringo

  2. Make sure that the object has the 2 headers, namely that it is locked.

    curl --location-trusted -I "http://192.168.8.109:9090/b1/file3?domain=locking.example.com" -u someuser:caringo HTTP/1.1 200 OK Date: Fri, 22 Oct 2021 09:04:09 GMT Gateway-Request-Id: DE2913658216FD69 Server: CAStor Cluster/14.0.0 Via: 1.1 192.168.8.109 (Cloud Gateway SCSP/7.6.0) Gateway-Protocol: scsp Castor-System-CID: e5c51ad561fcc0f361dd7c941a004ce6 Castor-System-Cluster: swarm.demo.internal Castor-System-Created: Fri, 22 Oct 2021 09:03:32 GMT Castor-System-IsVersioned: True Castor-System-Name: file3 Castor-System-Version: 1634893412.164 Content-Type: application/x-www-form-urlencoded Last-Modified: Fri, 22 Oct 2021 09:03:32 GMT X-Last-Modified-By-Meta: someuser@ X-Owner-Meta: someuser ETag: "b7bf6149bf811e057f2006b58e6dbbae" Castor-System-Path: /locking.example.com/b1/file3 Castor-System-Domain: locking.example.com Volume: eb4715ce21e9a8a20e0b4397bdc825d5 Content-MD5: CY9rzUYh03PK3k6DJie09g== X-Object-Lock-Meta-Mode: COMPLIANCE X-Object-Lock-Meta-Retain-until-date: Sat, 23 Oct 2021 08:53:31 GMT Content-Length: 4

C. Enabling legal hold for a newly written object

Enabling legal hold on a newly created object requires setting the x-object-lock-meta-legal-hold: ON header when writing the object. For this particular use case, you need to perform the following steps:

  1. Write the object with the aforementioned header.

    curl --location-trusted -i -XPOST --data-binary 'test' -H "x-object-lock-meta-legal-hold: ON" "http://192.168.8.109:9090/b1/file8?domain=locking.example.com" -u someuser:caringo

  2. Check that legal hold was applied on the object by issuing a HEAD request and confirming the presence of the following headers:

    1. X-Object-Lock-Meta-Legal-Hold: ON

    2. Lifepoint: [] deletable=no

    3. X-Object-Lock-Meta-Original-Lifepoints: <if you've added other lifepoints, they should be in this list>

      curl --location-trusted -I "http://192.168.209.84/b1/file8?domain=locking.example.com" HTTP/1.1 301 Moved Permanently Date: Mon, 25 Oct 2021 07:04:42 GMT Server: CAStor Cluster/14.0.0 Location: http://192.168.209.85:80/b1/file8?domain=locking.example.com&auth=b5bd5c429a3366969d5b57f0e2cba0cb Content-Length: 0 Keep-Alive: timeout=14400 HTTP/1.1 200 OK Castor-System-CID: e5c51ad561fcc0f361dd7c941a004ce6 Castor-System-Cluster: swarm.demo.internal Castor-System-Created: Mon, 25 Oct 2021 07:04:28 GMT Castor-System-IsVersioned: True Castor-System-Name: file8 Castor-System-Version: 1635145468.896 Content-Length: 4 Content-Type: application/x-www-form-urlencoded Last-Modified: Mon, 25 Oct 2021 07:04:28 GMT Lifepoint: [] deletable=no X-Last-Modified-By-Meta: someuser@ X-Object-Lock-Meta-Legal-Hold: ON X-Object-Lock-Meta-Original-Lifepoints: X-Owner-Meta: someuser Etag: "c52c8d4ee80b6a86b74eb95caf449582" Castor-System-Path: /locking.example.com/b1/file8 Castor-System-Domain: locking.example.com Volume: c613440c53abae81420b93211625b54b Content-MD5: CY9rzUYh03PK3k6DJie09g== Date: Mon, 25 Oct 2021 07:04:42 GMT Server: CAStor Cluster/14.0.0 Keep-Alive: timeout=14400

D. Managing the retention settings of an existing object

Managing the retention and/or legal-hold settings of an existing object is done on particular versions of that object, so the request will need to specify the version for which the retention and/or legal-hold settings are changed using the ?version=<etag of version> query argument. One needs to also take into account the specific permissions and limitations as mentioned in S3 Object Locking

The workflow for managing the retention settings of an existing object is generally the following (in these examples we will use an object for which no object locking was set, stored in a bucket that has object-locking enabled, but not enforced, namely X-Object-Lock-Meta-Retain-until-date is not set on the bucket):

  1. List the versions, noting the hash field returned by the listing requests, which is the versionId/etag of that particular version.

    curl --location-trusted -s "http://192.168.8.109:9090/b1?domain=locking.example.com&format=json&versions&name=file2&sort=tmborn:DESC,etag:DESC" -u someuser:caringo [ {"last_modified": "2021-10-25T09:10:45.768000Z", "bytes": 8, "versioned": "true", "name": "file2", "hash": "5823fac0dd0f21e32026c3ff1291c104", "written": "2021-10-25T09:10:45.768000Z", "accessed": "2021-10-25T09:10:45.768000Z", "content_type": "application/x-www-form-urlencoded"}, {"last_modified": "2021-10-22T08:53:31.228000Z", "bytes": 4, "versioned": "true", "name": "file2", "hash": "321375af02fecb94ca33dee20aa17f0c", "written": "2021-10-22T08:53:31.228000Z", "accessed": "2021-10-22T08:53:31.228000Z", "content_type": "application/x-www-form-urlencoded", "version": "321375af02fecb94ca33dee20aa17f0c"} ]

  2. Set your desired lock (governance | compliance) and the retention period on one of the versions. In this example, we will set a governance lock with a retention period of 30 days. This is done through the ?objectlock=governance:30d query argument.

    curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1/fileA1?domain=locking.example.com&version=18e9adfcfc2b102e05162fe1633118f1&objectlock=governance:30d" -u someuser:caringo

  3. Try to remove the governance lock, making sure to set the x-object-lock-meta-bypass-governance-retention: true header and the ?objectlock=retention query argument.

    curl --location-trusted -i -XDELETE -H "x-object-lock-meta-bypass-governance-retention: true" "http://192.168.8.109:9090/b1/fileA1?domain=locking.example.com&version=18e9adfcfc2b102e05162fe1633118f1&objectlock=retention" -u someuser:caringo

  4. Set the version’s locking to compliance with a retention period of 40 days.

    curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1/fileA1?domain=locking.example.com&version=18e9adfcfc2b102e05162fe1633118f1&objectlock=compliance:40d" -u someuser:caringo

  5. Try to reduce the retention period to 30 days, confirming that this is not allowed.

    curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1/fileA1?domain=locking.example.com&version=18e9adfcfc2b102e05162fe1633118f1&objectlock=compliance:30d" -u someuser:caringo HTTP/1.1 403 Forbidden Date: Mon, 25 Oct 2021 11:44:58 GMT Gateway-Request-Id: 3CAEFC561F5AB1D8 Server: CAStor Cluster/14.0.0 Via: 1.1 192.168.8.109 (Cloud Gateway SCSP/7.6.0) Gateway-Protocol: scsp Content-Length: 44 Cannot shorten compliance retention period

  6. Try to increase the retention period to 50 days, which is allowed.

    curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1/fileA1?domain=locking.example.com&version=18e9adfcfc2b102e05162fe1633118f1&objectlock=compliance:50d" -u someuser:caringo

  7. Check the version’s locking status through a GET request that includes the ?objectlock argument.

    curl --location-trusted -i "http://192.168.8.109:9090/b1/fileA1?domain=locking.example.com&version=18e9adfcfc2b102e05162fe1633118f1&objectlock" -u someuser:caringo HTTP/1.1 200 OK Date: Mon, 25 Oct 2021 11:45:13 GMT Gateway-Request-Id: 36EC45858BA0A0F5 Server: CAStor Cluster/14.0.0 Via: 1.1 192.168.8.109 (Cloud Gateway SCSP/7.6.0) Gateway-Protocol: scsp X-Object-Lock-Meta-Mode: COMPLIANCE X-Object-Lock-Meta-Retain-until-date: Tue, 14 Dec 2021 11:45:09 GMT Content-Length: 72 Object is locked in COMPLIANCE mode until Tue, 14 Dec 2021 11:45:09 GMT

  8. Change the bucket’s locking mode to compliance with a retention period that is less than what we’ve set for the object at step 6 (e.g. 30 days).

    curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1?domain=locking.example.com&objectlock=compliance:30d" -u someuser:caringo

  9. Try to change the version’s locking mode to compliance, without specifying the retention (i.e. use this query argument ?objectlock=compliance), which means that it should inherit the retention set at the bucket level. Since at the bucket level we have set retention of 30 days, which is less than the 50 days that the version currently has, this request should fail:

    curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1/fileA1?domain=locking.example.com&version=18e9adfcfc2b102e05162fe1633118f1&objectlock=compliance" -u someuser:caringo HTTP/1.1 403 Forbidden Date: Mon, 25 Oct 2021 12:07:00 GMT Gateway-Request-Id: 85349B63D10C25CF Server: CAStor Cluster/14.0.0 Via: 1.1 192.168.8.109 (Cloud Gateway SCSP/7.6.0) Gateway-Protocol: scsp Content-Length: 44 Cannot shorten compliance retention period

  10. Change the bucket’s locking mode to compliance with retention higher than what the object currently has (e.g. 60 days).

    curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1?domain=locking.example.com&objectlock=compliance:60d" -u someuser:caringo

  11. Now change the version’s locking mode to the bucket’s default (use ?objectlock=).

    curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1/fileA1?domain=locking.example.com&version=18e9adfcfc2b102e05162fe1633118f1&objectlock" -u someuser:caringo

  12. Confirm that the object has a retention period that matches the bucket’s (i.e. 60 days).

    curl --location-trusted -i "http://192.168.8.109:9090/b1/fileA1?domain=locking.example.com&version=18e9adfcfc2b102e05162fe1633118f1&objectlock" -u someuser:caringo HTTP/1.1 200 OK Date: Mon, 25 Oct 2021 12:16:26 GMT Gateway-Request-Id: F7D3C75D4223B42F Server: CAStor Cluster/14.0.0 Via: 1.1 192.168.8.109 (Cloud Gateway SCSP/7.6.0) Gateway-Protocol: scsp X-Object-Lock-Meta-Mode: COMPLIANCE X-Object-Lock-Meta-Retain-until-date: Fri, 24 Dec 2021 12:14:30 GMT Content-Length: 72 Object is locked in COMPLIANCE mode until Fri, 24 Dec 2021 12:14:30 GMT

E. Managing the legal hold settings of an existing object

In these examples we will use an object for which no object locking was set, stored in a bucket that has object-locking enabled, but not enforced, namely X-Object-Lock-Meta-Retain-until-date is not set on the bucket

The typical scenario for managing the legal hold settings of existing versions consists of the following steps:

  1. List the object’s versions.

    curl --location-trusted -s "http://192.168.8.109:9090/b1?domain=locking.example.com&format=json&versions&name=fileB1&sort=tmborn:DESC,etag:DESC" -u someuser:caringo [ {"last_modified": "2021-10-25T12:30:35.108000Z", "bytes": 4, "versioned": "true", "name": "fileB1", "hash": "fa6665b5a9189306addc007c0c57ad9b", "written": "2021-10-25T12:30:35.108000Z", "accessed": "2021-10-25T12:30:35.108000Z", "content_type": "application/x-www-form-urlencoded"}, {"last_modified": "2021-10-25T12:30:32.920000Z", "bytes": 4, "versioned": "true", "name": "fileB1", "hash": "386afd4ee45aba359c942c95bea61223", "written": "2021-10-25T12:30:32.920000Z", "accessed": "2021-10-25T12:30:32.920000Z", "content_type": "application/x-www-form-urlencoded", "version": "386afd4ee45aba359c942c95bea61223"}

  2. Set legal hold for one of the object’s version using the ?objectlock=legal-hold query argument on a PUT request.

    curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1/fileB1?domain=locking.example.com&version=386afd4ee45aba359c942c95bea61223&objectlock=legal-hold" -u someuser:caringo

  3. Check the version’s locking status through a GET request that uses the ?objectlock query argument.

    curl --location-trusted -i "http://192.168.8.109:9090/b1/fileB1?domain=locking.example.com&version=386afd4ee45aba359c942c95bea61223&objectlock" -u someuser:caringo HTTP/1.1 200 OK Date: Mon, 25 Oct 2021 12:36:20 GMT Gateway-Request-Id: 1EB296F696DEBA57 Server: CAStor Cluster/14.0.0 Via: 1.1 192.168.8.109 (Cloud Gateway SCSP/7.6.0) Gateway-Protocol: scsp X-Object-Lock-Meta-Legal-Hold: ON Content-Length: 31 Object is locked in legal hold

  4. Remove the version’s legal hold, through a DELETE request that includes the ?objectlock=legal-hold query argument.

    curl --location-trusted -i -XDELETE "http://192.168.8.109:9090/b1/fileB1?domain=locking.example.com&version=386afd4ee45aba359c942c95bea61223&objectlock=legal-hold" -u someuser:caringo

  5. Confirm that the legal hold has been removed.

    curl --location-trusted -i "http://192.168.8.109:9090/b1/fileB1?domain=locking.example.com&version=386afd4ee45aba359c942c95bea61223&objectlock" -u someuser:caringo HTTP/1.1 200 OK Date: Mon, 25 Oct 2021 12:43:09 GMT Gateway-Request-Id: FDC05254168B34A2 Server: CAStor Cluster/14.0.0 Via: 1.1 192.168.8.109 (Cloud Gateway SCSP/7.6.0) Gateway-Protocol: scsp Content-Length: 21 Object is not locked

Configuring Object Locking through the S3 API

The following examples are performed using the aws CLI. For details on how to set it up please check Using awscli v2 with Swarm S3

A. Enabling object locking on the bucket and all subsequently created objects

If you want to enable object locking on the bucket and have it applied automatically to all objects written afterwards, then the typical usage scenario is the following (NOTE: You will still be able to set object-locking on a per-object basis and the Gateway will always use the maximum of either the bucket default retention duration or the duration specified in a per-object request):

  1. Use the put-object-lock-configuration S3 API call for enabling locking using the desired mode and retention period.

    aws s3api put-object-lock-configuration --endpoint-url=http://locking.example.com:9091 --bucket=b2 --object-lock-configuration '{ "ObjectLockEnabled": "Enabled", "Rule": { "DefaultRetention": { "Mode": "COMPLIANCE", "Days": 50 }}}'

  2. Check the bucket’s locking status using the get-object-lock-configuration S3 API call.

    aws s3api get-object-lock-configuration --endpoint-url=http://locking.example.com:9091 --bucket=b2 { "ObjectLockConfiguration": { "ObjectLockEnabled": "Enabled", "Rule": { "DefaultRetention": { "Mode": "COMPLIANCE", "Days": 50 } } } }

  3. Create a new object in that bucket using the put-object API call.

    aws s3api put-object --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileA1 --body test.txt

  4. Check the object’s retention period using the get-object-retention S3 API call, making sure it matches the locking settings applied to the bucket. NOTE: This will return the retention settings of the object’s current version. If you need to check the retention settings of a different version, specify that using the --version-id CLI option.

    aws s3api get-object-retention --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileA1 { "Retention": { "Mode": "COMPLIANCE", "RetainUntilDate": "2021-12-14T13:39:35+00:00" } }

B. Enabling object locking on the bucket without automatically setting it on the objects written afterwards

If you want to enable object locking on the bucket without having it applied automatically to all objects written afterwards, then your typical usage scenario will look like this:

  1. Use the put-object-lock-configuration S3 API call for enabling locking without setting a mode or retention period.

    aws s3api put-object-lock-configuration --endpoint-url=http://locking.example.com:9091 --bucket=b2 --object-lock-configuration '{ "ObjectLockEnabled": "Enabled" }'

  2. Check the bucket’s locking status using the get-object-lock-configuration S3 API call.

    aws s3api get-object-lock-configuration --endpoint-url=http://locking.example.com:9091 --bucket=b2 { "ObjectLockConfiguration": { "ObjectLockEnabled": "Enabled" } }

  3. Create a new object in that bucket using the put-object API call.

    aws s3api put-object --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileB1 --body test.txt

  4. Check the object’s retention period using the get-object-retention S3 API call, making sure the object has no retention period set.

    aws s3api get-object-retention --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileB1 { "Retention": {} }

  5. Set a retention period for the current version of this newly written object using the put-object-retention API call.

    aws s3api put-object-retention --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileB1 --retention '{ "Mode": "Compliance", "RetainUntilDate": "2022-01-01T00:00:00" }'

  6. Using the get-object-retention S3 API call, confirm that the new retention period is now in place.

    aws s3api get-object-retention --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileB1 { "Retention": { "Mode": "COMPLIANCE", "RetainUntilDate": "2022-01-01T00:00:00+00:00" } }

  7. Alternatively, you can set the object lock mode and retention period at write time, using the --object-lock-mode and --object-lock-retain-until-date

    aws s3api put-object --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileC1 --body test.txt --object-lock-mode GOVERNANCE --object-lock-retain-until-date 2021-11-01T00:00:00+00:00

C. Enabling legal-hold on newly written objects

Using the AWS CLI, you can set legal-hold while writing an object by setting the --object-lock-legal-hold-status option to ON:

aws s3api put-object --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileD1 --body test.txt --object-lock-legal-hold-status ON

Checking the legal hold status of the newly written object can be done using the get-object-legal-hold API call:

aws s3api get-object-legal-hold --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileD1 { "LegalHold": { "Status": "ON" } }

D. Managing the locking settings of existing versions of an object

Managing the retention and/or legal-hold settings of an existing object using the S3 API is by default performed on the current version of the object. If you need to perform these actions on a particular version of an object other than the current one, you will need to specify that version using the --version-id CLI option. One needs to also take into account the specific permissions and limitations as mentioned in S3 Object Locking . In the following examples we will set the locking/legal hold parameters of versions other than the current version.

The typical workflow when managing the locking settings of an object’s version using the AWS CLI is the following:

  1. List the object’s versions using the list-object-versions API call, noting the VersionId of the version for which you want to manage the locking settings.

    aws s3api list-object-versions --endpoint-url=http://locking.example.com:9091 --bucket=b2 --prefix fileE1 { "Versions": [ { "ETag": "\"d8e8fca2dc0f896fd7cb4cb0031ba249\"", "Size": 5, "StorageClass": "STANDARD", "Key": "fileE1", "VersionId": "771c0aa2c1d8e944fa75ac8cbf780c34", "IsLatest": true, "LastModified": "2021-10-26T08:40:49.448000+00:00", "Owner": { "DisplayName": "caringoadmin@", "ID": "caringoadmin@" } }, { "ETag": "\"d8e8fca2dc0f896fd7cb4cb0031ba249\"", "Size": 5, "StorageClass": "STANDARD", "Key": "fileE1", "VersionId": "f59bbbb8a093dde1ed2cceb029a92fa2", "IsLatest": false, "LastModified": "2021-10-26T08:40:44.064000+00:00", "Owner": { "DisplayName": "caringoadmin@", "ID": "caringoadmin@" } } ] }

  2. Set a GOVERNANCE locking mode on one of the versions (in this example we will use the 2nd version) with a retention period until 2022-01-01T00:00:00. This can be done using the put-object-retention API call.

    aws s3api put-object-retention --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileE1 --version-id f59bbbb8a093dde1ed2cceb029a92fa2 --retention '{ "Mode": "Governance", "RetainUntilDate": "2022-01-01T00:00:00" }'

  3. Using the get-object-retention API call confirms that the new settings are in place.

    aws s3api get-object-retention --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileE1 --version-id f59bbbb8a093dde1ed2cceb029a92fa2 { "Retention": { "Mode": "GOVERNANCE", "RetainUntilDate": "2022-01-01T00:00:00+00:00" } }

  4. Remove the Governance lock using the put-object-retention call, with the --bypass-governance-retention flag set.

    aws s3api put-object-retention --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileE1 --bypass-governance-retention --version-id f59bbbb8a093dde1ed2cceb029a92fa2 --retention '{ "Mode": "Governance", "RetainUntilDate": 0 }'

  5. Confirm that the lock has been removed.

    aws s3api get-object-retention --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileE1 --version-id f59bbbb8a093dde1ed2cceb029a92fa2 { "Retention": {} }

  6. Set a Compliance mode object lock with a retention period of 90 days.

    aws s3api put-object-retention --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileE1 --bypass-governance-retention --version-id f59bbbb8a093dde1ed2cceb029a92fa2 --retention '{ "Mode": "Compliance", "RetainUntilDate": "2022-03-01T00:00:00+00:00" }'

E. Managing the legal-hold settings of existing versions of an object

The typical workflow in this case consists of the following steps:

  1. List the versions of an object and choose the version for which you want to apply the legal hold (in these examples we will use the 2nd most recent version.

    aws s3api list-object-versions --endpoint-url=http://locking.example.com:9091 --bucket=b2 --prefix fileE1 | jq '.Versions[].VersionId' "bf427bb54de0520a2b2c5d18e552587e" "a05ab3dac37bebf45dc269c60df77417" "771c0aa2c1d8e944fa75ac8cbf780c34" "f59bbbb8a093dde1ed2cceb029a92fa2"

  2. Enable legal hold on that version using the put-object-legal-hold API call.

    aws s3api put-object-legal-hold --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileE1 --version-id a05ab3dac37bebf45dc269c60df77417 --legal-hold Status=ON

  3. Check the version’s legal hold status using the get-object-legal-hold.

    aws s3api get-object-legal-hold --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileE1 --version-id a05ab3dac37bebf45dc269c60df77417 { "LegalHold": { "Status": "ON" } }

  4. Remove the legal hold lock.

    aws s3api put-object-legal-hold --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileE1 --version-id a05ab3dac37bebf45dc269c60df77417 --legal-hold Status=OFF

  5. Confirm that the legal hold lock has been removed.

    aws s3api get-object-legal-hold --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileE1 --version-id a05ab3dac37bebf45dc269c60df77417 { "LegalHold": { "Status": "OFF" } }

Related articles

S3 Object Locking

Using awscli v2 with Swarm S3

 

Looking for labels? They can now be found in the details panel on the floating action bar.

Related content

© DataCore Software Corporation. · https://www.datacore.com · All rights reserved.