Object locking prevents object versions from being deleted or overwritten – for a fixed amount of time or indefinitely. Use an object lock to help meet regulatory requirements requiring WORM storage, or to add another layer of protection against object changes and deletion.

...

Object locking does not prevent the creation of new versions of an object while the object is locked – it makes it impossible to delete or otherwise change the version(s) of the object with locking enabled.

...

• Retention – Specifies a fixed period of time ("retention period") during which the object remains locked. During this period, the object is WORM-protected and cannot be overwritten or deleted. The lock goes away automatically after the period expires.

• Legal hold – An object stays locked indefinitely when a legal hold is applied. A legal hold does not expire; it must be explicitly removed.

Retention

Retention Periods

A retention period is used to set the fixed amount of time the object needs to remain locked. The object version cannot be changed or deleted until the time expires.

...

A bucket default retention period specifies a duration (in days or years) for which every object version placed in the bucket is locked. Gateway calculates a retention period for the object version by adding the specified duration to the object version's creation timestamp when placing an object in the bucket.

How to Extend a Retention Period

A retention period can always be extended after it is set with the following steps:

1. Submit a new lock request for the object version with a retention period longer than the current one.

2. Gateway replaces the existing retention period with the new, longer period.

Any user with permissions to set an object retention period can also extend a retention period.

Retention Modes

A retention mode must always be specified when locking an object or setting a bucket default retention period. 

...

• In governance mode, grant some users the permission to shorten or remove a retention period or delete object versions under retention if necessary.

• In compliance mode, a locked object version cannot be overwritten or deleted by any user, even the admin user. The retention mode cannot be changed, and the retention period cannot be shortened when an object is locked in compliance mode.

In a deviation from S3, Gateway always uses the maximum of either the bucket default retention duration, or the duration specified in a per-object request.

Legal Hold

A legal hold prevents an object version from being overwritten or deleted until the legal hold is removed.

Legal holds do not have an associated retention period and are independent from retention periods and retention modes. As long as the bucket containing the object has object locking enabled adding and removing legal holds are available. It does not matter if the specified object version has a retention period set or not.

Prerequisites

Swarm Storage 12.0 or above must be running to use this feature because it relies on the Swarm lifepoints feature to prevent deletion of locked objects until a certain date has passed. Object locking is fully implemented starting with Gateway 7.6.

When an object is locked until a certain date, it obtains a deletable=no lifepoint protecting it from deletion until the date.

Versioning needs to be enabled for object locking to work.

Gateway refuses to enable object locking when versioning is not enabled. Gateway refuses to disable versioning once object locking is enabled. In both cases an error message is displayed.

Metadata Headers

...

Related to Object Locking

Object versions in Swarm are immutable and the metadata cannot be changed unlike Amazon S3.

...

The above headers are listed using the SCSP names. The corresponding S3 names start with x-amz-*. The SCSP headers are effectively stored with the objects. The S3 names are mapped onto the SCSP counterparts and back on-the-fly.

Assumptions and Limitations

• Internal to Gateway, all header values are treated as case-insensitive.

• Dates are in the rfc1123 format, e.g. "Wed, 12 Dec 2016 15:59:02 GMT". For S3 these are translated in to the ISO8601 format.

• The x-object-lock-meta-retain-until-date header applies to retention periods and specifies the end date of the retention period. The x-object-lock-meta-legal-hold header applies to legal hold. Both a retention period and a legal hold can both be set on the same object version.

• The x-object-lock-meta-original-lifepoints header stores the complete set of user defined delete/deletable lifepoint headers found on the object at the time the retention period/legal hold was applied. The original delete/deletable lifepoint headers are removed. Swarm no longer considers these lifepoints.
  Gateway manipulates delete/deletable type lifepoints, all other lifepoints are unaffected and continue functioning normally.
  An object lock in effect takes precedence over any user-defined delete/deletable lifepoints, blocking delete. The user-defined lifepoints take effect again when an object lock expires or is removed.

• Object locking works for tenanted objects. Object locking cannot be set on untenanted and unnamed objects in a cluster.

Lifepoint Headers

Gateway now adds a single deletable=no lifepoint header (the lock lifepoint), to go along with the object lock. This lock lifepoint is what actually protects the object against deletion in Swarm, both through user requests and through built-in functionalities like HP or bucket policies.

The lock lifepoint is computed as follows;

1. The lock lifepoint end date matches the end date of the retention period if the object is locked with a retention period. For legal hold, the lock lifepoint has no end date.

2. Next review the list of original lifepoints, and append those whose end date is later than the one from the lock lifepoint. In case of legal hold, there is no end date so none of the original lifepoints get appended.

The purpose of storing the set of original lifepoints is to allow later modifications/removal of the object lock to recompute/reinstate the original lifepoints as they are before the object lock.

The purpose of appending the "later lifepoints" to the lock lifepoint is to allow Swarm to act on them as it normally does once the lock lifepoint has expired naturally, without any intervention from Gateway. For legal hold there must always be a Gateway intervention to remove the lock, so the original lifepoints get reinstated at the time.

How to Enable Object Locking

Object locking is set using API calls. It is not available in the user interface.

Enabling Object Locking on a Bucket

Object locking must be enabled on the bucket before locking any objects.

...

The user must have the PutBucketObjectLocking permission to enable/disable object locking on a bucket. A user must have the GetBucketObjectLocking permission to query current object locking status.

Object Locking and Versioning Inheritance Rules

Versioning can be disabled for another bucket or domain in the cluster unrelated if a bucket in one domain has object locking (and therefore versioning) enabled.

...

It does not matter if versioning was enabled on the bucket itself, or whether it was inherited from cluster or domain level. Gateway refuses to disable versioning at the domain or bucket level if object locking is in effect anywhere within it.

Errors When Attempting to Enable Object Locking

The request to enable object locking can fail with the following errors:

...

Enabling object locking on a bucket comes down to storing the x-object-lock-meta-status and optionally x-object-lock-meta-default headers on the bucket context object. This immediately caches the bucket’s object locking configuration in memory so it is readily available during object requests.

Enabling Object Locking using S3

Enable or inspect the object locking configuration on a bucket using the following calls;

• https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectLockConfiguration.html

• https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObjectLockConfiguration.html

Enabling Object Locking using SCSP

Enable object locking on a bucket:

...

The defaults can be modified or removed at any time via additional PUT commands. This does not affect the object locking status of the bucket – once it is enabled, it stays enabled.

Object Locking Cannot be Disabled After it is Enabled

...

.

...

PUT /<bucket>?objectlock=
(use an empty query argument)
The "=" is optional.

How to Check Object Locking Status

• Query the object locking status of a bucket:
  GET /<bucket>?objectlock
  This returns the following response headers:
  x-object-lock-meta-status: ENABLED
x-object-lock-meta-default: <GOVERNANCE|COMPLIANCE>[:<duration>]
  And the response body says:
  Object locking is enabled on bucket <bucket> with default mode <mode> [ and default duration <duration> ]
  No response headers are present and the response body displays as below if the bucket does not have object locking enabled:
  Object locking disabled

REST API Changes

Object locking introduces the following new REST calls:

...

• PUT can now take object locking headers to create locks as a side effect

• POST can now take object locking headers to create locks as a side effect

• COPY can now take object locking headers to create locks as a side effect

• GET can return object locking headers if the user has the appropriate permissions

• HEAD can return object locking headers if the user has the appropriate permissions

For S3, see the Amazon documentation website https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html.

How to Lock an Object at Creation Time

Creating a New Object with a Retention Period

The client adds the following headers in the S3 PutObject / SCSP POST request to create a new object or object version with an immediate retention period in effect:

...

The request fails with a 400 Bad Request error because both are needed for a successful retention lock if either mode or retain-until-date is then still missing.

Creating a New Object with a Legal Hold

The client adds the following header in the S3 PutObject / SCSP POST request to create a new object or object version with an immediate legal hold in effect:

...

x-object-lock-meta-original-lifepoints: <original lifepoints>

Writing an Object as a Normal Unlocked Object in a Bucket with Object Locking Enabled

Objects are written as a normal unlocked object, despite being written to a bucket with object locking enabled if both headers are omitted from the request, and there are no defaults at the bucket level.

Managing Retention on an Existing Object

Enabling and disabling retention on an object requires the user have the PutObjectRetention permission.

...

Using S3, enable or inspect the retention period on an object using the following calls;

• https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectRetention.html

• https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObjectRetention.html

Using SCSP, enable or inspect the retention period on an object using the following calls:

...

Both S3 and SCSP also allow retrieving object lock information using regular object HEAD and GET requests.
Assuming the user has the GetObjectRetention permission, the information is returned in the form of the above response headers. The response body is not affected.

Managing Legal Hold on an Existing Object

Enabling/disabling legal hold requires the user have the PutObjectLegalHold permission. The GetObjectLegalHold permission is required to check the current legal hold status.

...

Using S3, enable or inspect the legal hold using the following calls:

• https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectLegalHold.html

• https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObjectLegalHold.html

Using SCSP, enable or inspect the legal hold on an object using the following calls:

...

Both S3 and SCSP also allow retrieving legal hold information using regular object HEAD and GET requests. Assuming the user has the GetObjectLegalHold permission, the information is returned in the form of the above response headers. The response body is not affected.

Combined Retention and Legal Hold

An object can be both under one of the retention modes AND legal hold at the same time.

...

• Query:
  GET /<bucket>/<object>?version=<uuid>&objectlock[=<locktype>]
  Response headers for both retention and the legal hold display when querying the object lock status without specifying the lock type, and the response body contains both status texts, separated by a new line.
  The user needs both the GetObjectRetention and the GetObjectLegalHold permissions for this request.
  Query the lock status for one specific lock type, either "legal-hold" or "retention". The corresponding permission is required.

• Delete:
  DELETE /<bucket>/<object>?version=<uuid>&objectlock=<locktype>
  Using SCSP remove either the retention or legal hold using DELETE and specifying the appropriate query argument objectlock=<locktype>, locktype being "legal-hold" or "retention". The locktype of "retention" is used exclusively for locks in governance mode.

Differences Between S3 and Swarm's Implementation of Object Locking

In S3, a DELETE request results in a delete marker, shadowing the locked object version. Swarm's implementation deviates from this logic – it rejects any DELETE requests for indelible objects with an HTTP 403 Forbidden error.

Gateway checks if the object is locked when it receives an HTTP 403 Forbidden error from Swarm. Gateway simulates the S3 behavior creating a new (unlocked) object version, immediately followed by a DELETE, thus creating a delete marker.

For SCSP, use a configuration flag to pick the desired behavior:

• fail deletes of locked objects with a 403 Forbidden error, or

• mimic the S3 behavior (https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock-overview.html)

[object_locking]
scspDeleteUsesS3Logic=true

New Policy Actions Related to Object Locking

The following new policy actions related to object locking are introduced:

• PutBucketObjectLocking: to enable/disable object locking on a bucket

• GetBucketObjectLocking: to query bucket object locking status

• PutObjectRetention: to set or extend object retention

• GetObjectRetention: to query object retention

• BypassGovernanceRetention: to shorten/remove a retention in governance mode

• PutObjectLegalHold: to set/remove a legal hold

• GetObjectLegalHold: to query legal hold

Interactions with Existing Swarm Functionality

Recursive Deletes

Clients can request recursive deletes Recursive Deletes of entire domains/buckets using DELETE <uri>?recursive=yes requests. Swarm implements this by synchronously deleting the domain/bucket object, and asynchronously deleting the objects in it. This has potential for conflicting with object retention/legal hold. Gateway first checks if there are any objects under retention/legal hold and refuse the recursive delete if so.

The recursive delete request fails with a 412 Precondition Failed error if any buckets with object locks are found.

APPEND

SCSP APPEND does create a new version when versioning is enabled; it does not allow an object's metadata to be modified. The "retain-until" header value can not be changed on an APPEND. Gateway does not impose any restrictions on the use of APPEND in combination with object locking.

Max Retention Configuration

S3 allows defining a max-retention-duration limit in the policy. Gateway currently approximates this functionality using a new configuration flag:

...

• A year is assumed to be 365 days when performing conversions between numbers of days and years.

• In the SCSP/S3 APIs, any user-specified value exceeding the limit is capped to the limit.

Audit Logging

Object Locking operations are audit logged (Gateway Audit Logging). Since object locks can also be requested as part of the object PUT/POST/COPY requests, Gateway tag the request's audit log line with additional object lock information, rather than inserting new log lines.

...

• Enabling retention on a bucket and setting defaults if provided:
  <audit log line> [OBJLCK:ENABLE:<mode>:<duration>]

• Setting/removing retention on an object:
  <audit log line> [OBJLCK:RETENTION:<mode>:<retainUntil>]
<audit log line> [OBJLCK:RETENTION:NONE]

• Setting/removing legal hold on an object:
  <audit log line> [OBJLCK:LEGALHOLD:ON]
<audit log line> [OBJLCK:LEGALHOLD:OFF]

...