Page Comparison

...

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 that have 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. After the period expires, the lock The lock goes away automatically after the period expires.

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

...

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

There is more than one way to set a retention period on an object version:

...

A bucket default retention period specifies a duration (in days or years) for which every object version placed in the bucket should be is locked. When placing an object in the bucket, 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 has been set . To do thiswith the following steps:

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

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

...

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. When an object is locked in compliance mode, its The retention mode cannot be changed, and its 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.

...

Prerequisites

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

Whenever an object gets locked until a certain date, it gets a deletable=no lifepoint protecting it from deletion until that the date.

...

Gateway refuses to enable object locking when versioning is not enabled. Once object locking is 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

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

Object locking uses the following headers:

...

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

...

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

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

• The x-object-lock-meta-retain-until-date header applies only to retention periods and specifies the end date of the retention period. The x-object-lock-meta-legal-hold header only 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. This means Swarm no longer considers these lifepoints.
  Gateway only manipulates delete/deletable type lifepoints, all other lifepoints are unaffected and continue functioning normally.
  As long as an object lock is in effect, it takes precedence over any user-defined delete/deletable lifepoints, blocking delete. When The user-defined lifepoints take effect again when an object lock expires (or gets removed), the user-defined lifepoints take effect again.

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

...

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 we go over 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 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 that the time.

How to Enable Object Locking

Object locking can only be is set using API calls. It is not yet available in the user interface.

Enabling Object Locking on a Bucket

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

S3 normally only allows enabling object locking on new buckets that do not yet carry without any objects. Gateway does not impose this restriction.

The user must have the PutBucketObjectLocking permission to enable/disable object locking on a bucket. To query current object locking status, the 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 that is unrelated if a bucket in one domain has object locking (and therefore versioning) enabled.

...

Enabling Object Locking using SCSP

To enable Enable object locking on a bucket:

...

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.

To allow writing unlocked objects into a bucket with object locking enabled, remove Remove the lock defaults and write new objects without any of the object locking headers to allow writing unlocked objects into a bucket with object locking enabled.

To remove Remove the lock defaults:

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

How to Check Object Locking Status

• To query 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

...

Creating a New Object with a Retention Period

To 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 client adds the following headers in the S3 PutObject / SCSP POST requestin effect:

x-object-lock-meta-mode: <GOVERNANCE|COMPLIANCE>
x-object-lock-meta-retain-until-date: <date>
This takes precedence over the default bucket retention mode and duration, if present.

...

Creating a New Object with a Legal Hold

To 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, the client adds the following header in the S3 PutObject / SCSP POST request:

x-object-lock-legal-hold: ON

To use these headers, the The user needs to have the PutObjectRetention and, respectively, PutObjectLegalHold permission to use these headers, or the request fails with a 403 Forbidden error.

...

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

To query current retention status, the The user must have the GetObjectRetention permission to query current retention status.

The client must explicitly specify the versionId of the object version to lock.

Gateway then applies the extra object locking headers to that the version, thus applying object locking protection for the length of the retention period.

...

x-object-lock-meta-mode: <GOVERNANCE|COMPLIANCE>
x-object-lock-meta-retain-until-date: <date>
x-object-lock-meta-original-lifepoints: <original lifepoints>
lifepoint: [<date>] deletable=no, <later lifepoints>

When changing the retention period, Gateway must also recompute the lock lifepoint when changing the retention period, starting from the preserved set of original lifepoints and only appending those with later end dates to the lock lifepoint. This is the main purpose of preserving the original lifepoints.

...

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

• To set Set a governance lock onto an object, specifying both lock mode and duration (this overrides any defaults configured on the bucket):
  PUT /<bucket>/<object>?version=<uuid>&objectlock=governance:<untildate>

• To set Set a compliance lock onto an object and inherit the default duration from the bucket:
  PUT /<bucket>/<object>?version=<uuid>&objectlock=compliance

• To completely Completely inherit the default object lock mode and duration on the bucket:
  PUT /<bucket>/<object>?version=<uuid>&objectlock

• To remove Remove a (governance) object lock from an object:
  DELETE /<bucket>/<object>?version=<uuid>&objectlock=<mode>
  The mode is always "governance". A compliance mode object lock cannot be removed. The BypassGovernanceRetention permission is required to carry out this action and the request must carry the x-object-lock-meta-bypass-governance:true header.

• To query Query current object lock status:
  GET /<bucket>/<object>?version=<uuid>&objectlock
  The response carries the following headers:
  x-object-lock-meta-mode: <GOVERNANCE|COMPLIANCE>
x-object-lock-meta-retain-until: <date>
  And the response body says:
  Object is locked in <mode> mode until <date>
  When None of the headers are present when called on an object not under retention, none of the headers are present and the response body says:
  Object is not locked

...

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

• To set Set a legal hold onto an object:
  PUT /<bucket>/<object>?version=<uuid>&objectlock=legal-hold

• To remove Remove a legal hold from an object:
  DELETE /<bucket>/<object>?version=<uuid>&objectlock=legal-hold
  This reinstates any original lifepoints by moving them from the x-object-lock-meta-original-lifepoints header back into in to the proper lifepoint headers.

• To query Query an object's legal hold status:
  GET /<bucket>/<object>?version=<uuid>&objectlock
  The response carries the following headers:
  x-object-lock-meta-legal-hold: on
  And the response body says:
  Object is locked in legal hold
  When The header is not present when called on an object not under legal hold nor retention, the header is not present and the response body says:
  Object is not locked

...

In the SCSP protocol, querying and deleting such combined locks is handled via a uniform GET and DELETE API (as opposed to S3 which has separate APIs for querying/deleting retention and legal hold).

• To queryQuery:
  GET /<bucket>/<object>?version=<uuid>&objectlock[=<locktype>]
  When Response headers for both retention and the legal hold display when querying the object lock status without specifying the lock type, response headers for both retention and the legal hold displaywithout 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". In this case only the The corresponding permission is required.

• To deleteDelete:
  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". When the The locktype is of "retention", this can only be done 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 that this logic – it rejects any DELETE requests for indelible objects with an HTTP 403 Forbidden error.

When Gateway Gateway checks if the object is locked when it gets a HTTP 403 Forbidden error from Swarm, it checks if the object is locked. 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:

...

[object_locking]
retentionMaxYears=100
The default limit value is 100 years (input type int) if unspecified.

• When doing A year is assumed to be 365 days when performing conversions between numbers of days and years, it is assumed a year is 365 days.

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

...