{"type":"doc","content":[{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"minLevel":{"value":"1"},"maxLevel":{"value":"2"},"outline":{"value":"false"},"type":{"value":"list"},"printable":{"value":"false"}},"macroMetadata":{"macroId":{"value":"e63948dc-69fb-421d-9e17-b1e69afd4456"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"ea5295b2-2be8-485c-8c9a-1eea6b849c59"}},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"Objects are not actually locked. Object locking is used to lock ","type":"text"},{"text":"individual object versions","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Important","type":"text"}]},{"type":"paragraph","content":[{"text":"Object locking does not prevent overwriting or deleting objects. Since the locked ","type":"text"},{"text":"versions","type":"text","marks":[{"type":"strong"}]},{"text":" remain present and protected, it is still possible to overwrite or even delete objects with locking enabled.","type":"text"}]},{"type":"paragraph","content":[{"text":"A new version is created when overwriting or modifying an object","type":"text"},{"text":". A delete request creates a delete marker. The object appears deleted, but Swarm preserves history including the locked version.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#172b4d"}}]}]}]},{"type":"paragraph","content":[{"text":"There are two types of object locking used simultaneously and independent of each other:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Retention ","type":"text","marks":[{"type":"strong"}]},{"text":"– 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.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Legal hold","type":"text","marks":[{"type":"strong"}]},{"text":" – An object stays locked indefinitely when a legal hold is applied. A legal hold does not expire; it must be explicitly removed.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Retention","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Retention Periods","type":"text"}]},{"type":"paragraph","content":[{"text":"A ","type":"text"},{"text":"retention period","type":"text","marks":[{"type":"strong"}]},{"text":" 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.","type":"text"}]},{"type":"paragraph","content":[{"text":"There is more than one way to set a retention period on an object version:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Newly created objects can inherit a ","type":"text"},{"text":"default retention period","type":"text","marks":[{"type":"strong"}]},{"text":" configured on the bucket level.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Explicitly setting a retention period when creating a new object overrides the default retention period configured for the bucket if present.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Explicitly set a retention period on an existing object version.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"A ","type":"text"},{"text":"bucket default retention period","type":"text","marks":[{"type":"strong"}]},{"text":" 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.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"How to Extend a Retention Period","type":"text"}]},{"type":"paragraph","content":[{"text":"A retention period can always be extended after it is set with the following steps:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Submit a new lock request for the object version with a retention period longer than the current one.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Gateway replaces the existing retention period with the new, longer period.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Any user with permissions to set an object retention period can also extend a retention period.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Retention Modes","type":"text"}]},{"type":"paragraph","content":[{"text":"A ","type":"text"},{"text":"retention mode","type":"text","marks":[{"type":"strong"}]},{"text":" must always be specified when locking an object or setting a bucket default retention period. ","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Info","type":"text"}]},{"type":"paragraph","content":[{"text":"Retention mode always applies to the individual objects carrying it, not to the bucket or cluster as a whole.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"There are two retention modes impacting actions with objects under retention:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In ","type":"text"},{"text":"governance mode","type":"text","marks":[{"type":"strong"}]},{"text":", grant some users the permission to shorten or remove a retention period ","type":"text"},{"text":"or delete object versions","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"ee6e848c-f937-499f-9016-8c6d9f6a4fd1"}}]},{"text":" under retention if necessary.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In ","type":"text"},{"text":"compliance mode","type":"text","marks":[{"type":"strong"}]},{"text":", 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.","type":"text"}]}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Info","type":"text"}]},{"type":"paragraph","content":[{"text":"Compliance mode is irreversible for the entire retention period once an object is locked.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Legal Hold","type":"text"}]},{"type":"paragraph","content":[{"text":"A legal hold prevents an object version from being overwritten or deleted until the legal hold is removed.","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Info","type":"text"}]},{"type":"paragraph","content":[{"text":"Setting a legal hold on an object version does not affect the retention mode or retention period for the object version.","type":"text"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Prerequisites","type":"text"}]},{"type":"paragraph","content":[{"text":"Swarm Storage 12.0 or above","type":"text","marks":[{"type":"strong"}]},{"text":" must be running to use this feature because it relies on the Swarm ","type":"text"},{"text":"lifepoints","type":"text","marks":[{"type":"strong"},{"type":"link","attrs":{"href":"#"}}]},{"text":" feature to prevent deletion of locked objects until a certain date has passed. ","type":"text"},{"text":"Object locking is fully implemented starting with Gateway 7.6","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"9041531c-8d40-4949-8bf1-4cf1c17e6d49"}}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"When an object is locked until a certain date, it obtains a ","type":"text"},{"text":"deletable=no","type":"text","marks":[{"type":"code"}]},{"text":" lifepoint protecting it from deletion until the date.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Important","type":"text"}]},{"type":"paragraph","content":[{"text":"Even though Gateway relies on lifepoints, it remains possible for applications to impose user defined lifepoints on objects together with object locks. Gateway verifies correct semantics in all cases without any additional behavior needed from the application side. In case of any conflicts between user defined lifepoints and object locks, the object lock always wins.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Versioning","type":"text","marks":[{"type":"strong"},{"type":"link","attrs":{"href":"#"}}]},{"text":" needs to be enabled for object locking to work.","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"9774c897-68a2-4729-af86-89dabc026e44"}},{"type":"textColor","attrs":{"color":"#172b4d"}}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Info","type":"text"}]},{"type":"paragraph","content":[{"text":"The ability to disable versioning at the cluster level via SNMP does not pass via Gateway so it cannot protect against disabling object locking in the cluster.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#172b4d"}}]},{"type":"hardBreak"},{"text":"Administrators are advised against disabling versioning at the cluster level to avoid the risk of auto-deleting locked object versions ","type":"text"},{"text":"after object locking is enabled in individual domains or buckets.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#172b4d"}}]}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Metadata Headers Related to Object Locking","type":"text"}]},{"type":"paragraph","content":[{"text":"Object versions in Swarm are immutable and the metadata cannot be changed unlike Amazon S3.","type":"text"}]},{"type":"paragraph","content":[{"text":"Object locking uses the following headers:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"on ","type":"text"},{"text":"buckets","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"},{"type":"hardBreak"},{"text":"x-object-lock-meta-status: ENABLED","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":"(empty means DISABLED)","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"efd70c9e-f283-4b2e-94a1-4902a1c1fc09"}},{"type":"em"}]},{"type":"hardBreak"},{"text":"x-object-lock-meta-default: [:<","type":"text","marks":[{"type":"code"}]},{"text":"duration","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"39d938a6-cd01-4024-902e-21308b31b8bf"}},{"type":"code"}]},{"text":">]","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":"Bucket default retention period duration is expressed as ","type":"text"},{"text":"y","type":"text","marks":[{"type":"strong"}]},{"text":" for number of years or ","type":"text"},{"text":"d ","type":"text","marks":[{"type":"code"}]},{"text":"for number of days.","type":"text"}]}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"on ","type":"text"},{"text":"objects","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"},{"type":"hardBreak"},{"text":"x-object-lock-meta-mode: ","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":"x-object-lock-meta-retain-until-date: ","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":"x-object-lock-meta-legal-hold: ON","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":"(empty means OFF)","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"5c8d76b9-213f-4ada-a2fd-1de0964651e6"}},{"type":"em"}]},{"type":"hardBreak"},{"text":"x-object-lock-meta-original-lifepoints:","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":"","type":"text","marks":[{"type":"em"}]},{"type":"hardBreak"},{"text":"lifepoint: [] deletable=no","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":"(for retention period)","type":"text","marks":[{"type":"em"}]},{"type":"hardBreak"},{"text":"lifepoint: [] deletable=no","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":"(for legal hold)","type":"text","marks":[{"type":"em"}]}]}]}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":"The above headers are listed using the SCSP names. The corresponding S3 names start with ","type":"text"},{"text":"x-amz-*","type":"text","marks":[{"type":"strong"}]},{"text":". The SCSP headers are effectively stored with the objects. The S3 names are mapped onto the SCSP counterparts and back on-the-fly.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Assumptions and Limitations","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Internal to Gateway, all header values are treated as case-insensitive.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Dates are in the ","type":"text"},{"text":"rfc1123","type":"text","marks":[{"type":"code"}]},{"text":" format, e.g. \"","type":"text"},{"text":"Wed, 12 Dec 2016 15:59:02 GMT","type":"text","marks":[{"type":"code"}]},{"text":"\". For S3 these are translated in to the ","type":"text"},{"text":"ISO8601","type":"text","marks":[{"type":"code"}]},{"text":" format.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"x-object-lock-meta-retain-until-date","type":"text","marks":[{"type":"code"}]},{"text":" header applies to retention periods and specifies the end date of the retention period. The ","type":"text"},{"text":"x-object-lock-meta-legal-hold","type":"text","marks":[{"type":"code"}]},{"text":" header applies to ","type":"text"},{"text":"legal hold","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"e9255cd9-d6f4-4249-988b-25c4f3a978b6"}}]},{"text":". B","type":"text"},{"text":"oth a retention period and a legal hold can both be set on the same object version.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#172b4d"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"x-object-lock-meta-original-lifepoints","type":"text","marks":[{"type":"code"}]},{"text":" 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 ","type":"text"},{"text":"no longer considers these lifepoints","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"be3939e6-47c3-490b-aff7-4e04a67b37f2"}}]},{"text":".","type":"text"},{"type":"hardBreak"},{"text":"Gateway manipulates delete/deletable type lifepoints, all other lifepoints are unaffected and continue functioning normally.","type":"text"},{"type":"hardBreak"},{"text":"An object lock in effect takes precedence over any user-defined delete/deletable lifepoints, blocking ","type":"text"},{"text":"delete","type":"text","marks":[{"type":"code"}]},{"text":". The user-defined lifepoints take effect again when an object lock expires or is removed.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Object locking works for tenanted objects. Object locking cannot be set on ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#172b4d"}}]},{"text":"untenanted and unnamed objects in a cluster","type":"text","marks":[{"type":"textColor","attrs":{"color":"#172b4d"}},{"type":"link","attrs":{"href":"https://perifery.atlassian.net/wiki/spaces/public/pages/2443818312"}}]},{"text":".","type":"text","marks":[{"type":"textColor","attrs":{"color":"#172b4d"}}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Lifepoint Headers","type":"text"}]},{"type":"paragraph","content":[{"text":"Gateway now adds a single ","type":"text"},{"text":"deletable=no","type":"text","marks":[{"type":"code"}]},{"text":" lifepoint header (the ","type":"text"},{"text":"lock lifepoint","type":"text","marks":[{"type":"strong"}]},{"text":"), 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.","type":"text"}]},{"type":"paragraph","content":[{"text":"The lock lifepoint is computed as follows;","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"How to Enable Object Locking","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"1976855f-8178-4836-892b-7b1d36f27e0c"}}]}]},{"type":"paragraph","content":[{"text":"Object locking is set using API calls. It is not available in the user interface.","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"1976855f-8178-4836-892b-7b1d36f27e0c"}},{"type":"textColor","attrs":{"color":"#172b4d"}}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Enabling Object Locking on a Bucket","type":"text"}]},{"type":"paragraph","content":[{"text":"Object locking must be enabled on the bucket before locking any objects.","type":"text"}]},{"type":"paragraph","content":[{"text":"S3 normally allows enabling object locking on new buckets without any objects. Gateway does not impose this restriction.","type":"text"}]},{"type":"paragraph","content":[{"text":"The user must have the ","type":"text"},{"text":"PutBucketObjectLocking","type":"text","marks":[{"type":"code"}]},{"text":" permission to enable/disable object locking on a bucket. A user must have the ","type":"text"},{"text":"GetBucketObjectLocking","type":"text","marks":[{"type":"code"}]},{"text":" permission to query the current object locking status. ","type":"text"}]},{"type":"paragraph","content":[{"text":"The command to enable policy versioning on a bucket is:","type":"text"}]},{"type":"codeBlock","content":[{"text":"curl -i --location-trusted -XPUT --post301--data-binary '' -H \"Policy-Versioning: enabled\"\n\"http:///?domain=&replicate=immediate\"","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://perifery.atlassian.net/wiki/spaces/public/pages/2931654659"}},{"text":" to enable policy versioning from the UI.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Object Locking and Versioning Inheritance Rules","type":"text"}]},{"type":"paragraph","content":[{"text":"Versioning:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Cannot be disabled at the bucket, domain, or cluster level if object locking (and versioning) is enabled at a bucket level.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Can be disabled for individual buckets if enabled at a domain level.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Can be disabled for individual domains and/or buckets if enabled at the cluster level.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"It does not matter if versioning was enabled on the bucket 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.","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"d1c53ab2-f4ee-4920-80b7-69ae7b826bfb"}}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Errors When Attempting to Enable Object Locking","type":"text"}]},{"type":"paragraph","content":[{"text":"The request to enable object locking can fail with the following errors:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"412 Precondition Failed","type":"text","marks":[{"type":"code"}]},{"text":" is displayed if the Swarm cluster does not ","type":"text"},{"text":"support all features","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"1cdc2a5b-0087-41bb-8e07-b19e693d5453"}}]},{"text":" ","type":"text"},{"text":"necessary to perform the operation.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#172b4d"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"412 Precondition Failed","type":"text","marks":[{"type":"code"}]},{"text":" is displayed if the bucket does not have versioning enabled.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"403 Forbidden","type":"text","marks":[{"type":"code"}]},{"text":" if the user does not have the ","type":"text"},{"text":"PutBucketObjectLocking","type":"text","marks":[{"type":"code"}]},{"text":" permission.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Enabling object locking on a bucket comes down to storing the ","type":"text"},{"text":"x-object-lock-meta-status","type":"text","marks":[{"type":"code"}]},{"text":" and optionally ","type":"text"},{"text":"x-object-lock-meta-default","type":"text","marks":[{"type":"code"}]},{"text":" headers on the bucket context object. This immediately caches the bucket’s object locking configuration ","type":"text"},{"text":"in memory","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"22627349-e6a9-460d-9710-188b5b33bb89"}}]},{"text":" so it is readily available during object requests.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Enabling Object Locking using S3","type":"text"}]},{"type":"paragraph","content":[{"text":"Enable or inspect the object locking configuration on a bucket using the following calls;","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"type":"inlineCard","attrs":{"url":"https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectLockConfiguration.html"}},{"text":" ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"type":"inlineCard","attrs":{"url":"https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObjectLockConfiguration.html"}},{"text":" ","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Enabling Object Locking using SCSP","type":"text"}]},{"type":"paragraph","content":[{"text":"Enable object locking on a bucket:","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":"PUT /?objectlock= [ : ]","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"defaultmode","type":"text","marks":[{"type":"code"}]},{"text":" can be either \"governance\" or \"compliance\"","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"defaultperiod","type":"text","marks":[{"type":"code"}]},{"text":" is optional; it is a number of years (y) or days (d), eg. ","type":"text"},{"text":"1y","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"20d","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"In this call omit either ","type":"text"},{"text":"defaultmode","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"defaultperiod","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"or both.","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"d36dddc3-15c0-4cb4-8806-efe5829103ef"}}]}]},{"type":"paragraph","content":[{"text":"The bucket allows object locking (it is enabled), but no locking happens by default ","type":"text"},{"text":"if both are omitted","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"d36dddc3-15c0-4cb4-8806-efe5829103ef"}}]},{"text":". Objects written to the bucket without any locking directives remain unlocked.","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"d36dddc3-15c0-4cb4-8806-efe5829103ef"}},{"type":"textColor","attrs":{"color":"#172b4d"}}]}]},{"type":"paragraph","content":[{"text":"The defaults can be modified or removed at any time via additional ","type":"text"},{"text":"PUT","type":"text","marks":[{"type":"code"}]},{"text":" commands. This does not affect the object locking status of the bucket – once it is enabled, it stays enabled.","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Caution","type":"text"}]},{"type":"paragraph","content":[{"text":"Object locking cannot be disabled once enabled on a bucket.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"It does not matter if versioning was enabled on the bucket itself, or whether it was inherited from cluster or domain level. Gateway ","type":"text"},{"text":"refuses to disable versioning at","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"9240850f-5d22-4ef1-8f54-dd128fd1b278"}}]},{"text":" the domain or bucket level if object locking is in effect anywhere within it.","type":"text"}]},{"type":"paragraph","content":[{"text":"Remove the lock defaults and write new objects without any object locking headers to allow writing unlocked objects into a bucket with object locking enabled.","type":"text"}]},{"type":"paragraph","content":[{"text":"Remove the lock defaults:","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":"PUT /?objectlock=","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"6c26a637-563f-4e87-912e-1c5a27af8e44"}},{"type":"code"}]},{"type":"hardBreak"},{"text":"(use an empty query argument)","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"4c64d52d-ad02-4fdd-b9fc-808dd01fccd4"}},{"type":"em"}]},{"type":"hardBreak"},{"text":"The \"=\" is optional.","type":"text","marks":[{"type":"em"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"How to Check Object Locking Status","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Query the object locking status of a bucket:","type":"text"},{"type":"hardBreak"},{"text":"GET /?objectlock","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":"This returns the following response headers:","type":"text"},{"type":"hardBreak"},{"text":"x-object-lock-meta-status: ENABLED","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":"x-object-lock-meta-default: [:]","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":"And the response body says:","type":"text"},{"type":"hardBreak"},{"text":"Object locking is enabled on bucket with default mode [ and default duration ]","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":"No response headers are present and the response body displays as below if the bucket does not have object locking enabled:","type":"text"},{"type":"hardBreak"},{"text":"Object locking disabled","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"REST API Changes","type":"text"}]},{"type":"paragraph","content":[{"text":"Object locking introduces the following new REST calls:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"PUT","type":"text","marks":[{"type":"code"}]},{"text":" with ","type":"text"},{"text":"?objectlock","type":"text","marks":[{"type":"code"}]},{"text":" query arguments","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GET","type":"text","marks":[{"type":"code"}]},{"text":" with ","type":"text"},{"text":"?objectlock","type":"text","marks":[{"type":"code"}]},{"text":" query arguments","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"DELETE","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"4b5ba5b8-b8f3-474c-a210-608944ad7eb2"}},{"type":"code"}]},{"text":" with ","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"4b5ba5b8-b8f3-474c-a210-608944ad7eb2"}}]},{"text":"?objectlock","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"4b5ba5b8-b8f3-474c-a210-608944ad7eb2"}},{"type":"code"}]},{"text":" query arguments (","type":"text"},{"text":"DELETE","type":"text","marks":[{"type":"code"}]},{"text":" is an object-only call)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Object locking also introduces changes to existing REST calls:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"PUT","type":"text","marks":[{"type":"code"}]},{"text":" can now take object locking headers to create locks as a side effect","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"POST","type":"text","marks":[{"type":"code"}]},{"text":" can now take object locking headers to create locks as a side effect","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"COPY","type":"text","marks":[{"type":"code"}]},{"text":" can now take object locking headers to create locks as a side effect","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GET","type":"text","marks":[{"type":"code"}]},{"text":" can return object locking headers if the user has the appropriate permissions","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"HEAD","type":"text","marks":[{"type":"code"}]},{"text":" can return object locking headers if the user has the appropriate permissions","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For S3, see ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html"}},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"How to Lock an Object at Creation Time","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Creating a New Object with a Retention Period","type":"text"}]},{"type":"paragraph","content":[{"text":"The client adds the following headers in the S3 ","type":"text"},{"text":"PutObject","type":"text","marks":[{"type":"code"}]},{"text":" / SCSP ","type":"text"},{"text":"POST","type":"text","marks":[{"type":"code"}]},{"text":" request to create ","type":"text"},{"text":"a new object","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"b40ee57b-9395-4b18-9119-8ced7db2d4a7"}}]},{"text":" or object version with an immediate retention period in effect:","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":"x-object-lock-meta-mode: ","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":"x-object-lock-meta-retain-until-date: ","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"type":"hardBreak"},{"text":"This takes precedence over the default bucket retention mode and duration, if present.","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"b0c3e054-ea0a-4cf7-84a4-35a96416a7ee"}}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Gateway looks for corresponding defaults at the bucket level if any one of these two headers is omitted from the request and if found, takes the corresponding values from there.","type":"text"}]},{"type":"paragraph","content":[{"text":"The request fails with a ","type":"text"},{"text":"400 Bad Request","type":"text","marks":[{"type":"code"}]},{"text":" error because both are needed for a successful retention lock if either mode or retain-until-date is then still missing.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Creating a New Object with a Legal Hold","type":"text"}]},{"type":"paragraph","content":[{"text":"The client adds the following header in the S3 ","type":"text"},{"text":"PutObject","type":"text","marks":[{"type":"code"}]},{"text":" / SCSP ","type":"text"},{"text":"POST","type":"text","marks":[{"type":"code"}]},{"text":" request to ","type":"text"},{"text":"create a new object","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"6a2fc888-2ab3-478c-907f-0f13e1f8dea9"}}]},{"text":" or object version with an immediate legal hold in effect:","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":"x-object-lock-legal-hold: ON","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"The user needs to have the ","type":"text"},{"text":"PutObjectRetention","type":"text","marks":[{"type":"code"}]},{"text":" and, respectively, ","type":"text"},{"text":"PutObjectLegalHold","type":"text","marks":[{"type":"code"}]},{"text":" permission to use these headers, or the request fails with a ","type":"text"},{"text":"403 Forbidden","type":"text","marks":[{"type":"code"}]},{"text":" error.","type":"text"}]},{"type":"paragraph","content":[{"text":"The request fails with a ","type":"text"},{"text":"412 Precondition Failed","type":"text","marks":[{"type":"code"}]},{"text":" error if the bucket does not have object locking enabled.","type":"text"}]},{"type":"paragraph","content":[{"text":"Gateway forwards these headers when creating the new object on Swarm, and also creates a lock lifepoint instructing Swarm to not delete the object before the retention period expires. For retention periods, the lock lifepoint also includes the subset of the original lifepoints with a later end date than the retention period.","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":"lifepoint: [] deletable=no, ","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"Or in case of legal hold;","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":"lifepoint: [] deletable=no","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"The original lifepoint headers are preserved in:","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":"x-object-lock-meta-original-lifepoints: ","type":"text","marks":[{"type":"code"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Writing an Object as a Normal Unlocked Object in a Bucket with Object Locking Enabled","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Managing Retention on an Existing Object","type":"text"}]},{"type":"paragraph","content":[{"text":"Enabling and disabling retention on an object requires the user have the ","type":"text"},{"text":"PutObjectRetention","type":"text","marks":[{"type":"code"}]},{"text":" permission.","type":"text"}]},{"type":"paragraph","content":[{"text":"The user must have the ","type":"text"},{"text":"GetObjectRetention","type":"text","marks":[{"type":"code"}]},{"text":" permission to query current retention status.","type":"text"}]},{"type":"paragraph","content":[{"text":"The client must explicitly specify the ","type":"text"},{"text":"versionId","type":"text","marks":[{"type":"code"}]},{"text":" of the object version to lock.","type":"text"}]},{"type":"paragraph","content":[{"text":"Gateway then applies the extra object locking headers to the version, thus applying object locking protection for the length of the retention period.","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"572a9b01-1834-4bf7-a10f-e3adda9a821b"}},{"type":"textColor","attrs":{"color":"#172b4d"}}]}]},{"type":"paragraph","content":[{"text":"The following headers are added or changed;","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":"x-object-lock-meta-mode: ","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":"x-object-lock-meta-retain-until-date","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"x-object-lock-meta-original-lifepoints: ","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":"lifepoint: [] deletable=no, ","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"Gateway must recompute the lock lifepoint when changing the retention period, starting from the preserved set of original lifepoints and appending those with later end dates to the lock lifepoint. This is the main purpose of preserving the original lifepoints.","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Introducing or extending a retention period is always possible, but there are restrictions to shortening or removing a retention period on an object already under retention:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In ","type":"text"},{"text":"compliance mode","type":"text","marks":[{"type":"strong"}]},{"text":" this is not permitted","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In ","type":"text"},{"text":"governance mode","type":"text","marks":[{"type":"strong"}]},{"text":", the user needs to have the special ","type":"text"},{"text":"BypassGovernanceRetention","type":"text","marks":[{"type":"code"}]},{"text":" permission.","type":"text"},{"type":"hardBreak"},{"text":"Also, ","type":"text"},{"text":"an S3 request","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"d57e1889-d497-4e35-b08c-1bf7fcb9812e"}}]},{"text":" must explicitly include ","type":"text"},{"text":"x-amz-bypass-governance-retention:true","type":"text","marks":[{"type":"code"}]},{"text":" as a request header with any request requiring overriding governance mode.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Using S3, enable or inspect the retention period on an object using the following calls;","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"type":"inlineCard","attrs":{"url":"https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectRetention.html"}}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"type":"inlineCard","attrs":{"url":"https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObjectRetention.html"}}]}]}]},{"type":"paragraph","content":[{"text":"Using SCSP, enable or inspect the retention period on an object using the following calls:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Set a governance lock onto an object, specifying both lock mode and duration (this overrides any defaults configured on the bucket):","type":"text"},{"type":"hardBreak"},{"text":"PUT //

Browser not supported