Page Comparison

...

You can make regular GET/HEAD requests (ie. without ?objectlock query arg) on buckets and domains with original logic. If you have the required Get{Domain|Bucket}ObjectLocking permission, the response will also contain the objectlocking metadata headers, including retention limit if present, together with all other metadata.

Managing Retention on an Existing Object

Enabling/disabling retention on an object requires that the user has PutObjectRetention permission. The user must have GetObjectRetention permission to query the current retention status. The client must explicitly specify the versionId of the object version to lock. 

The Gateway then creates a new variant of that version on which it stores the extra Object Locking headers. This variant is protected by the retention period. For the client, there is no distinction between the variant and the original object version; the following headers are added or changed:

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>

Introducing or extending a retention period is always possible, but there are restrictions to shortening/removing a retention period on an object that is already under the retention:

• In compliance mode, this is not permitted

• In governance mode, it requires that the user has a special permission BypassGovernanceRetention. 

An S3 request must explicitly include x-amz-bypass-governance-retention:true as a request header with any request that requires overriding governance mode. Using S3, one enables/inspects a 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, one enables/inspects a retention period on an object using the following calls: 

...

Call Type

...

Purpose

...

PUT /<bucket>/<object>?version=<uuid>&objectlock=governance:<untildate>

...

To put a governance lock onto an object and specify both lock mode and duration.

...

PUT /<bucket>/<object>?version=<uuid>&objectlock=compliance 

...

To put a compliance lock onto an object and inherit the default duration from the bucket.

...

PUT /<bucket>/<object>?version=<uuid>&objectlock

...

To inherit the default object lock mode and duration on the bucket.

...

DELETE /<bucket>/<object>?version=<uuid>&objectlock=<mode>

...

To remove an object lock from an object, assuming the user has the proper permissions.

 Use GET /<bucket>/<object>?version=<uuid>&objectlock to query the current object lock status, and 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 called on an object that is not under retention, none of the headers are present and the response body says:  

Object is not locked 

Both S3 and SCSP allow retrieving Object Lock information using the regular object HEAD and GET requests. Assuming that the user has 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 PutObjectLegalHold permission for the user. To query the current legal hold status, the user needs GetObjectLegalHold permission.

x-object-lock-meta-legal-hold: ON              (absent means OFF) 
x-object-lock-meta-original-lifepoints: <original lifepoints>  
lifepoint: [] deletable=no

Using S3, the user can enable/inspect 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, the user can enable/inspect legal hold on an object using the following calls:

...

Call Type

...

Purpose

...

PUT /<bucket>/<object>?version=<uuid>&objectlock=legal-hold

...

To put a legal hold onto an object

...

DELETE /<bucket>/<object>?version=<uuid>&objectlock=legal-hold

To remove legal hold from an object.

...

Important

...

GET /<bucket>/<object>?version=<uuid>&objectlock

...

To query an object’s legal hold status.

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 it is called on an object that is neither under the legal hold nor retention, the header is not present, and the response body says:  

Object is not locked 

Both S3 and SCSP allow retrieving legal hold information using regular object HEAD and GET requests. Assuming the user has 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 fall under both retention mode and legal hold at the same time. In the SCSP protocol, querying and deleting such combined locks are handled via a uniform GET and DELETE API (as opposed to S3 which has separate APIs for querying/deleting retention and legal hold). 

...

Max Retention Config 

S3 allows defining a “max-retention-duration" limit in the policy. The Gateway has the new configuration option to offer a similar capability to S3. Using a single new config flag to approximate this functionality:

[object_locking] 
retentionMaxYears=100 

The default limit value is 100 years if unspecified. It is assumed a year is 365 days when performing conversions between numbers of days and years. 

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

Managing Retention on an Existing Object

Enabling/disabling retention on an object requires that the user has PutObjectRetention permission. The user must have GetObjectRetention permission to query the current retention status. The client must explicitly specify the versionId of the object version to lock. 

The Gateway then creates a new variant of that version on which it stores the extra Object Locking headers. This variant is protected by the retention period. For the client, there is no distinction between the variant and the original object version; the following headers are added or changed:

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>

Introducing or extending a retention period is always possible, but there are restrictions to shortening/removing a retention period on an object that is already under the retention:

• In compliance mode, this is not permitted

• In governance mode, it requires that the user has a special permission BypassGovernanceRetention. 

An S3 request must explicitly include x-amz-bypass-governance-retention:true as a request header with any request that requires overriding governance mode. Using S3, one enables/inspects a 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, one enables/inspects a retention period on an object using the following calls: 

 Use GET /<bucket>/<object>?version=<uuid>&objectlock to query the current object lock status, and 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 called on an object that is not under retention, none of the headers are present and the response body says:  

Object is not locked 

Both S3 and SCSP allow retrieving Object Lock information using the regular object HEAD and GET requests. Assuming that the user has 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 PutObjectLegalHold permission for the user. To query the current legal hold status, the user needs GetObjectLegalHold permission.

x-object-lock-meta-legal-hold: ON              (absent means OFF) 
x-object-lock-meta-original-lifepoints: <original lifepoints>  
lifepoint: [] deletable=no

Using S3, the user can enable/inspect 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, the user can enable/inspect legal hold on an object using the following calls:

...

...

The user needs both GetObjectRetention and GetObjectLegalHold permissions for this request. 

One can also query lock status for one specific lock type, being either legal hold or retention. The corresponding permission is required. 

...

...

Enforcing the Object Lock

It is worth repeating that Amazon S3’s definition of Object Locking locks object versions, and not objects. It is perfectly possible to overwrite an object that is locked, and now, the overwritten version continues to exist and is protected from changes or deletion.

Moreover, object versions are immutable in Swarm; any object version is protected from modification by design. The exception to this is deletion, which the lock lifepoints now protect against:

• The users' attempts to delete

• Any automated delete attempts by Swarm. 

Swarm rejects any delete requests for indelible objects with a 403 error. An S3 client can delete the delete marker, making the previous version visible again in the Portal. An upcoming Portal release allows visibility of delete markers and version history in a bucket listing.

For SCSP, this is an update to gateway.cfg to pick the desired behavior which is either ‘fail deletes the locked objects with a 403 error’ or ‘mimic the S3 behavior’. 

[object_locking] 
scspDeleteUsesS3Logic=true

New Policy Actions

The following new policy actions related to Object Locking are introduced:

...

Policy Actions

...

Definition

...

PutBucketObjectLocking

...

To enable/disable object locking on a bucket

...

GetBucketObjectLocking

...

To query bucket object locking status

...

PutObjectRetention

...

To put or extend object retention

...

GetObjectRetention

...

To query an object retention

...

BypassGovernanceRetention

...

To shorten/remove retention in the governance mode

...

PutObjectLegalHold

...

To put/remove a legal hold

...

GetObjectLegalHold

...

To query a legal hold

Interactions with Other Functionalities

Content UI

The Content Portal also supports Object Locking.

• There are different icons based on each Object Locking state and default of the bucket in the bucket listing view.

• The object versions are locked at the bucket level.

• Both retention and legal hold can be applied on a single object version if necessary.

Recursive Deletes

To avoid the conflict of recursive deletes attempting to remove a locked object, Gateway first checks if there are any objects under retention or legal hold and refuses the recursive delete if so. The request fails with an HTTP 412 error if the recursive delete cannot be performed due to the Object Locking.

...

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 it is called on an object that is neither under the legal hold nor retention, the header is not present, and the response body says:  

Object is not locked 

Both S3 and SCSP allow retrieving legal hold information using regular object HEAD and GET requests. Assuming the user has 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 fall under both retention mode and legal hold at the same time. In the SCSP protocol, querying and deleting such combined locks are handled via a uniform GET and DELETE API (as opposed to S3 which has separate APIs for querying/deleting retention and legal hold). 

For query, use GET /<bucket>/<object>?version=<uuid>&objectlock[=<locktype>]

When querying the object lock status without specifying the lock type, response headers for both retention and the legal hold display, and the response body contains both status texts, separated by a newline.

One can also query lock status for one specific lock type, being either legal hold or retention. The corresponding permission is required. 

To delete, use DELETE /<bucket>/<object>?version=<uuid>&objectlock=<locktype>. Using SCSP one can remove either the retention or legal hold using DELETE and can specify the appropriate query argument objectlock=<locktype>, where locktype is legal hold or retention.

Enforcing the Object Lock

It is worth repeating that Amazon S3’s definition of Object Locking locks object versions, and not objects. It is perfectly possible to overwrite an object that is locked, and now, the overwritten version continues to exist and is protected from changes or deletion.

Moreover, object versions are immutable in Swarm; any object version is protected from modification by design. The exception to this is deletion, which the lock lifepoints now protect against:

• The users' attempts to delete

• Any automated delete attempts by Swarm. 

Swarm rejects any delete requests for indelible objects with a 403 error. An S3 client can delete the delete marker, making the previous version visible again in the Portal. An upcoming Portal release allows visibility of delete markers and version history in a bucket listing.

For SCSP, this is an update to gateway.cfg to pick the desired behavior which is either ‘fail deletes the locked objects with a 403 error’ or ‘mimic the S3 behavior’. 

[object_locking] 
allowRecursiveDeleteBypassscspDeleteUsesS3Logic=true

A warning is logged if this setting is present. The header into the recursive delete request is X-Object-Lock-Meta-Bypass-Recursive-Delete-Check: true. When encountering this header, the Gateway skips the aforementioned checks and allows the recursive delete to proceed. 

Lifepoints

The original set of user-defined lifepoints is preserved in a separate header and can be reinstated when the object lock is removed. This applies to deletable/delete lifepoints, all other types of lifepoints are left as is. 

The Gateway adds a deletable=no lock lifepoint to protect locked objects from inadvertent deletion. In the case of the retention period, the lock lifepoint has the same end date as the retention period. The lock lifepoint includes the subset of user-defined lifepoints with a later end date than the retention period. This allows those lifepoints to automatically resume taking effect as soon as the retention period expires. 

In the case of the legal hold, the lock lifepoint has no end date, and no user-defined lifepoints are included in it.

Append

SCSP APPEND creates a new version when versioning is enabled. Any lock either retention or legal hold, which is applied to the object version, is applied to the new version created by the APPEND operation.

Max Retention Config 

S3 allows defining a “max-retention-duration" limit in the policy. The Gateway has the new configuration option to offer a similar capability to S3. Using a single new config flag to approximate this functionality:

[object_locking] 
retentionMaxYears=100 

The default limit value is 100 years if unspecified. It is assumed a year is 365 days when performing conversions between numbers of days and years. 

...

New Policy Actions

The following new policy actions related to Object Locking are introduced:

Interactions with Other Functionalities

Content UI

The Content Portal also supports Object Locking.

• There are different icons based on each Object Locking state and default of the bucket in the bucket listing view.

• The object versions are locked at the bucket level.

• Both retention and legal hold can be applied on a single object version if necessary.

Recursive Deletes

To avoid the conflict of recursive deletes attempting to remove a locked object, Gateway first checks if there are any objects under retention or legal hold and refuses the recursive delete if so. The request fails with an HTTP 412 error if the recursive delete cannot be performed due to the Object Locking.

While the recursive delete of a domain or bucket does not immediately result in deletion of locked object versions, instead this makes it less practical to find and access. Significantly, it defeats the built-in safety checks that prevent versioning from getting disabled, which results in the deletion of the locked object versions. For that reason, the Gateway requires an additional config setting in the gateway.cfg;

[object_locking] 
allowRecursiveDeleteBypass=true

A warning is logged if this setting is present. The header into the recursive delete request is X-Object-Lock-Meta-Bypass-Recursive-Delete-Check: true. When encountering this header, the Gateway skips the aforementioned checks and allows the recursive delete to proceed. 

Lifepoints

The original set of user-defined lifepoints is preserved in a separate header and can be reinstated when the object lock is removed. This applies to deletable/delete lifepoints, all other types of lifepoints are left as is. 

The Gateway adds a deletable=no lock lifepoint to protect locked objects from inadvertent deletion. In the case of the retention period, the lock lifepoint has the same end date as the retention period. The lock lifepoint includes the subset of user-defined lifepoints with a later end date than the retention period. This allows those lifepoints to automatically resume taking effect as soon as the retention period expires. 

In the case of the legal hold, the lock lifepoint has no end date, and no user-defined lifepoints are included in it.

Append

SCSP APPEND creates a new version when versioning is enabled. Any lock either retention or legal hold, which is applied to the object version, is applied to the new version created by the APPEND operation.

Audit Logging

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

...