{"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":"992f4947-a081-4832-9c72-16b4c79a928c"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"036eb9bd-6478-4281-bdf1-def46e09e01f"}},{"type":"heading","attrs":{"level":1},"content":[{"text":"Overview","type":"text"}]},{"type":"bodiedExtension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"excerpt","parameters":{"macroParams":{"name":{"value":"Object Locking"}},"macroMetadata":{"macroId":{"value":"b8232ea926f6310d8a3b968c8767b317"},"schemaVersion":{"value":"1"},"title":"Excerpt"}},"localId":"7955506f-40d4-4c70-ae2b-549faa830eb6"},"content":[{"type":"paragraph","content":[{"text":"Object Locking prevents object versions from being deleted or overwritten for a fixed amount of time or indefinitely. It is applied to an object version to meet regulatory requirements that require WORM storage or to add another protection layer against object changes and deletion. ","type":"text"}]},{"type":"paragraph","content":[{"text":"There is a strong connection between Object Locking and Versioning. Object Locking does not lock objects, but individual ","type":"text"},{"text":"object versions","type":"text","marks":[{"type":"strong"}]},{"text":". Therefore, a user can create new object versions even though the object is locked, but it is impossible to delete or change any locked version of the object. ","type":"text"}]},{"type":"paragraph","content":[{"text":"There are two types of Object Locking:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Retention ","type":"text","marks":[{"type":"strong"}]},{"text":"-","type":"text"},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"Specifies a fixed period (“retention period”) during which the object version remains locked. During this retention period, the object is WORM-protected and cannot be overwritten or deleted. After the period expires, the lock goes away automatically from the object.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Legal hold","type":"text","marks":[{"type":"strong"}]},{"text":" - Keeps the object locked until the legal hold is explicitly removed. ","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"These two types of object locking are orthogonal, independent of each other, and can be used simultaneously.","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":"locks an object version for a fixed amount of time. Until that fixed amount of time has expired, one cannot delete or change the object version. ","type":"text"}]},{"type":"paragraph","content":[{"text":"There are three different ways 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.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Explicitly set a retention period when creating a new object. This overrides the default retention period configured on the bucket if present.","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"44a5ff09-a750-4915-a104-2e3d42a5709b"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Explicitly set a retention period on an existing object version. ","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"A bucket's default retention period specifies the duration in days or years, for which, every object version placed in the bucket is locked. While placing an object in the bucket, the Gateway calculates a retention period for the object version by adding the specified duration to the object version's creation timestamp.","type":"text"}]},{"type":"paragraph","content":[{"text":"An already set retention period can always be ","type":"text"},{"text":"extended","type":"text","marks":[{"type":"strong"}]},{"text":". Submit a new lock request for the object version with a retention period longer than the current period. The Gateway replaces the existing retention period with the new, longer period. Any user with permission to place an object retention period can extend a retention period. ","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"align-start","width":65.0},"content":[{"type":"media","attrs":{"width":2682,"id":"8cb3a8dc-52d9-4dbf-8d2c-fe00d2e7c8b0","collection":"contentId-2898919491","type":"file","height":970}}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Retention Modes","type":"text"}]},{"type":"paragraph","content":[{"text":"There are two ","type":"text"},{"text":"retention modes","type":"text","marks":[{"type":"em"}]},{"text":" that impact what can be done with objects under retention: ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In ","type":"text"},{"text":"governance ","type":"text","marks":[{"type":"strong"}]},{"text":"mode, some users can be granted permission to shorten or remove a retention period if necessary.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In ","type":"text"},{"text":"compliance ","type":"text","marks":[{"type":"strong"}]},{"text":"mode, any user including the admin user, cannot overwrite or delete a protected object version. When an object is locked in the compliance mode, the retention mode cannot be changed, and the retention period cannot be shortened. ","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The default retention mode and retention period can be set independently at the bucket level. The retention mode always applies to the individual objects carrying it, not to the bucket or cluster as a whole.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Legal Hold","type":"text"}]},{"type":"paragraph","content":[{"text":"A legal hold prevents an object version from being overwritten or deleted like a retention period. A legal hold does not have an associated retention period and remains in effect until removed. ","type":"text"}]},{"type":"paragraph","content":[{"text":"Legal holds are independent of retention periods and retention modes. As long as the bucket contains an object that has Object Locking enabled, the user can place and remove legal holds regardless of whether the specified object version has a retention period set or not. Placing a legal hold on an object version does not affect the retention mode or retention period for that object version.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"align-start","width":55.0},"content":[{"type":"media","attrs":{"width":1352,"id":"f622b4ee-163d-412d-885f-501c82d15734","collection":"contentId-2898919491","type":"file","height":788}}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Important","type":"text"}]},{"type":"paragraph","content":[{"text":"A legal hold cannot be applied as a default at the bucket level.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Design","type":"text"}]},{"type":"paragraph","content":[{"text":"The Object Locking feature is implemented fully in the Gateway using lifepoints, a Swarm feature, which is used to prevent deletion of locked objects until a certain date has passed. It is supported by both S3 and SCSP protocols.","type":"text"}]},{"type":"paragraph","content":[{"text":"Despite Gateway relying on lifepoints, it remains possible for applications to impose user-defined lifepoints on objects along with object locks. The Gateway verifies correct semantics in all cases without any additional behavior needed from the application side. In the case of any conflicts between user-defined lifepoints and object locks, the object lock always wins. ","type":"text"}]},{"type":"paragraph","content":[{"text":"Object Locking is compatible with the S3 protocol and always pertains to specific object versions. A prerequisite for applying it on a bucket is that versioning must be enabled on the bucket.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Metadata Headers","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"d5eb24eb-ec29-468c-82d1-45c5cfefe33d"}}]},{"text":" Related to Object Locking","type":"text"}]},{"type":"paragraph","content":[{"text":"Object Locking uses the following ","type":"text"},{"text":"headers","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"0bf5e99d-4365-4c30-adde-f093a778321e"}}]},{"text":".","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"On Buckets","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"x-object-lock-meta-status: ENABLED (absent means DISABLED)\nx-object-lock-meta-default: [:]","type":"text"}]},{"type":"paragraph","content":[{"text":" The duration of a bucket's default retention period is expressed as","type":"text"},{"text":" “y”","type":"text","marks":[{"type":"strong"}]},{"text":" or ","type":"text"},{"text":"“d”","type":"text","marks":[{"type":"strong"}]},{"text":" for the number of years/days. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"On Objects","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"x-object-lock-meta-mode: \nx-object-lock-meta-retain-until-date:\nx-object-lock-meta-legal-hold: ON (absent means OFF)\nx-object-lock-meta-original-lifepoints: \nlifepoint: [] deletable=no (for retention period)\nlifepoint: [] deletable=no (for legal hold)","type":"text"}]},{"type":"paragraph","content":[{"text":"The above headers are listed using the SCSP names and the corresponding S3 names start with ","type":"text"},{"text":"x-amz-*","type":"text","marks":[{"type":"code"}]},{"text":". The SCSP headers are effectively stored with objects. The S3 names are mapped onto the SCSP counterparts and back on the fly.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Internal to Gateway, all header values are treated case insensitive. Dates are in ","type":"text"},{"text":"rfc1123","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"format, e.g., “Wed, 12 Dec 2016 15:59:02 GMT”. For S3, these are translated in to ","type":"text"},{"text":"ISO8601","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"format. ","type":"text"}]},{"type":"bulletList","content":[{"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.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"x-object-lock-meta-legal-hold","type":"text","marks":[{"type":"code"}]},{"text":" header applies to the legal hold. ","type":"text"}]}]}]},{"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 when the retention period/legal hold is applied. The original delete/deletable lifepoint headers are removed.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Info","type":"text"}]},{"type":"paragraph","content":[{"text":"The term “lifepoint” implicitly means the delete/deletable lifepoints. All other types of lifepoints are not affected by object locks. ","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The lock lifepoint protects the object against deletion in Swarm, so be it through user requests or built-in functionalities like HP or bucket policies. The lock lifepoint is computed as follows:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If the object is locked with a retention period, then the lock lifepoint end date matches the end date of the retention period. For legal hold, the lock lifepoint has no end date. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Go over the list of original lifepoints and append those whose end date is later than the one from the lock lifepoint. In the case of the legal hold, there is no such 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 locking. ","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 gateway intervention. For legal hold, there must always be a gateway intervention to remove the lock, so the original lifepoints are reinstated at that time.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Enabling Object Locking on a Bucket","type":"text"}]},{"type":"paragraph","content":[{"text":"Before locking any objects, verify Object Locking is enabled on the bucket. S3 ","type":"text"},{"text":"allows","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"a2a0fd1d-1c6d-4ccb-a6c0-bc93a3839c0a"}}]},{"text":" enabling Object Locking on new buckets carrying no objects, but Gateway does not impose this restriction. The user must have ","type":"text"},{"text":"PutBucketObjectLocking","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"permission to enable/disable Object Locking on a bucket. The user must have ","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 request to enable Object Locking can fail with the following errors:","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":1800.0,"localId":"1238f743-b5bd-42dc-9802-d366385d323f"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[144.0]},"content":[{"type":"paragraph","content":[{"text":"Error Code","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[616.0]},"content":[{"type":"paragraph","content":[{"text":"Definition","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[144.0]},"content":[{"type":"paragraph","content":[{"text":"412","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[616.0]},"content":[{"type":"paragraph","content":[{"text":"When the bucket does not have versioning enabled. It does not matter if the versioning was enabled on the bucket itself, or whether it was inherited from a cluster or domain level.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[144.0]},"content":[{"type":"paragraph","content":[{"text":"403","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[616.0]},"content":[{"type":"paragraph","content":[{"text":"When the user does not have","type":"text"},{"text":" PutBucketObjectLocking","type":"text","marks":[{"type":"strong"}]},{"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. Using S3, one enables/inspects Object Locking config 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":"paragraph","content":[{"text":"Using SCSP, one enables Object Locking on a bucket as follows:","type":"text"}]},{"type":"paragraph","content":[{"text":"PUT /?objectlock= [ : ]","type":"text","marks":[{"type":"code"}]},{"text":" where;","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The default mode is either ","type":"text"},{"text":"governance","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" or ","type":"text"},{"text":"compliance","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":". ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The optional default period is a number of years (y) or days (d), e.g., 1y or 20d. ","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"In this call, the user can omit either default mode, default duration, or both. The defaults can be modified or removed at any time via additional ","type":"text"},{"text":"PUT","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" command.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Important","type":"text"}]},{"type":"paragraph","content":[{"text":"In a deviation from S3, the Gateway always uses the MAXIMUM of either the bucket default retention duration, or duration specified in a per-object request. ","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"GET /?objectlock","type":"text","marks":[{"type":"code"}]},{"text":" to query object locking status of a bucket. This returns the following response headers:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"x-object-lock-meta -status: ENABLED \nx-object-lock-meta-default: [:] ","type":"text"}]},{"type":"paragraph","content":[{"text":"And the response body says:","type":"text"}]},{"type":"paragraph","content":[{"text":"Object locking is enabled on bucket with default mode [ and default duration ]","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" ","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"No response headers are present if the bucket does not have object locking enabled and the response body says:","type":"text"}]},{"type":"paragraph","content":[{"text":"Object locking disabled","type":"text","marks":[{"type":"strong"},{"type":"em"}]}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Note","type":"text"}]},{"type":"paragraph","content":[{"text":"Object Locking cannot be disabled once enabled on a bucket. It is possible to remove the lock defaults and provide lock headers on writing new objects to force a lock to allow writing unlocked objects in a bucket with Object Locking enabled. ","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Locking an Object at Creation Time","type":"text"}]},{"type":"paragraph","content":[{"text":"The client adds the following headers in the S3 PutObject/SCSP POST request to create a new object with an immediate retention period in effect; ","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"x-object-lock-meta-mode: \nx-object-lock-meta-retain-until-date: ","type":"text"}]},{"type":"paragraph","content":[{"text":"This takes precedence over the default bucket retention mode and duration if present. ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The Gateway looks for corresponding defaults at the bucket level if any one of these two headers are omitted from the request. ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"It takes the corresponding values from there if found. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The request fails with an HTTP 400 error as both are needed for a successful retention lock if either mode or retain-until-date is still missing. ","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The object is written as a normal unlocked object, despite being written to a bucket that has Object Locking enabled if both headers are omitted from the request and there is no default set at the bucket level. The client can request an immediate legal hold by specifying the header: ","type":"text"}]}]}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"x-object-lock-meta-legal-hold: ON","type":"text"}]},{"type":"paragraph","content":[{"text":"Use of these headers requires that the user has ","type":"text"},{"text":"PutObjectRetention/PutObjectLegalHold ","type":"text","marks":[{"type":"code"}]},{"text":"permission; otherwise the request fails with an HTTP 403 error. The request fails with an HTTP 412 error","type":"text"},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"if the bucket does not have Object Locking enabled. ","type":"text"}]},{"type":"paragraph","content":[{"text":"The Gateway forwards these headers when creating a new object on Swarm, and also creates a lock lifepoint instructing Swarm to not delete the object before the retention period expires. ","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":1800.0,"localId":"a5b679ae-0173-4c7b-903a-ee6bcd1c3ed7"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[133.0]},"content":[{"type":"paragraph","content":[{"text":"Lock Mode","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[246.0]},"content":[{"type":"paragraph","content":[{"text":"Lock Lifepoint","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[381.0]},"content":[{"type":"paragraph","content":[{"text":"Remarks","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[133.0]},"content":[{"type":"paragraph","content":[{"text":"Retention Period","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[246.0]},"content":[{"type":"paragraph","content":[{"text":"lifepoint: [] deletable=no, ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[381.0]},"content":[{"type":"paragraph","content":[{"text":"Lock lifepoints includes the subset of the original lifepoints that had a later end date than the retention period.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[133.0]},"content":[{"type":"paragraph","content":[{"text":"Legal Hold","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[246.0]},"content":[{"type":"paragraph","content":[{"text":"lifepoint: [] deletable=no","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[381.0]},"content":[{"type":"paragraph"}]}]}]},{"type":"paragraph","content":[{"text":"Finally, the original lifepoint headers are preserved in ","type":"text"},{"text":"x-object-lock-meta-original-lifepoints: ","type":"text","marks":[{"type":"code"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Configuring Retention Limits","type":"text"}]},{"type":"paragraph","content":[{"text":"It is now possible to configure retention limits at root, domain, and bucket levels. The root config lives in ","type":"text"},{"text":"gateway.cfg","type":"text","marks":[{"type":"em"}]},{"text":" as item ","type":"text"},{"text":"[object_locking]retentionLimit = 100y (default)]","type":"text","marks":[{"type":"code"}]},{"text":". When specifying the value, supported units are y(ear), d(ay), h(our), m(minutes), and s(seconds). It allows specifying only one value/unit combination, hence, syntax such as 1y2d is ","type":"text"},{"text":"NOT","type":"text","marks":[{"type":"strong"}]},{"text":" supported. Typical config uses days or years. The smaller units are mainly intended for testing.","type":"text"}]},{"type":"paragraph","content":[{"text":"The older config ","type":"text"},{"text":"[object_locking]retentionMaxYears = 100","type":"text","marks":[{"type":"code"}]},{"text":" is still supported but deprecated in favor of the more flexible config.","type":"text"}]},{"type":"paragraph","content":[{"text":"The domain/bucket retention limits live as metadata header X-Object-Lock-Meta-Retention-Limit on the context objects.","type":"text"}]},{"type":"paragraph","content":[{"text":"When evaluating the retention duration for an object, it is always the smaller root/domain/bucket limit that applies.","type":"text"}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Note","type":"text"}]},{"type":"paragraph","content":[{"text":"Limits do not constrain the retention defaults that you can set on a bucket. They only constrain the actual retention applied to objects, possibly then capping the default.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Domain and bucket retention limits can be set on existing domain/bucket via the following SCSP requests, using the same value/unit syntax;","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"PUT ?domain=mydomain&objectlock&limit=1y\nPUT /mybucket?domain=mydomain&ojectlock&limit=100d","type":"text"}]},{"type":"paragraph","content":[{"text":"To delete a retention limit, use:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"DELETE ?domain=mydomain&objectlock&limit\nDELETE /mybucket?domain=mydomain&objectlock&limit","type":"text"}]},{"type":"paragraph","content":[{"text":"A GET or HEAD with the following query args returns a response carrying the objectlocking metadata including the new retention limit metadata header X-Object-Lock-Meta-Retention-Limit.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"GET ?domain=mydomain&objectlock\nHEAD /mybucket?domain=mydomain&objectlock","type":"text"}]},{"type":"paragraph","content":[{"text":"To set or delete a retention limit, you need new permission ","type":"text"},{"text":"PutDomainObjectLockingLimit","type":"text","marks":[{"type":"code"}]},{"text":" (for domain) and ","type":"text"},{"text":"PutBucketObjectLockingLimit ","type":"text","marks":[{"type":"code"}]},{"text":"(for bucket). A typical cloud service provider would reserve these permissions for itself.","type":"text"}]},{"type":"paragraph","content":[{"text":"Any changes to retention limits are written to the audit log, tagged with LIMIT:xxx where xxx is the limit being set, or NONE if the limit is being removed.","type":"text"}]},{"type":"paragraph","content":[{"text":"You need the ","type":"text"},{"text":"GetBucketObjectLocking","type":"text","marks":[{"type":"code"}]},{"text":" permission to query the current bucket retention limit (together with other metadata like bucket defaults). To query the current domain retention limit, you need the ","type":"text"},{"text":"GetDomainObjectLocking","type":"text","marks":[{"type":"code"}]},{"text":" permission, which is new. A domain carries no retention defaults, only an optional retention limit.","type":"text"}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"paragraph","content":[{"text":"There is no new permission specific to querying retention limits. With ","type":"text"},{"text":"Get{Domain|Bucket}ObjectLocking","type":"text","marks":[{"type":"em"}]},{"text":" permission, you can see all objectlocking-related metadata, including limits. ","type":"text"}]}]},{"type":"paragraph","content":[{"text":"You can make regular GET/HEAD requests (ie. without ?objectlock query arg) on buckets and domains with original logic. If you have the required ","type":"text"},{"text":"Get{Domain|Bucket}ObjectLocking","type":"text","marks":[{"type":"em"}]},{"text":" permission, the response will also contain the objectlocking metadata headers, including retention limit if present, together with all other metadata.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Max Retention Config ","type":"text"}]},{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"codeBlock","content":[{"text":"[object_locking] \nretentionLimit=100y ","type":"text"}]},{"type":"paragraph","content":[{"text":"Supported units are y(ear), d(ay), h(our), m(minutes), and s(seconds). The smaller units are intended for testing.","type":"text"}]},{"type":"paragraph","content":[{"text":"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. ","type":"text"}]},{"type":"paragraph","content":[{"text":"In the SCSP/S3 APIs, any user-specified value exceeding the limit is silently capped to the limit. ","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Managing Retention on an Existing Object","type":"text"}]},{"type":"paragraph","content":[{"text":"Enabling/disabling retention on an object requires that the user has ","type":"text"},{"text":"PutObjectRetention","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"permission. The user must have","type":"text"},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"GetObjectRetention","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"permission","type":"text"},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"to query the current retention status","type":"text"},{"text":".","type":"text","marks":[{"type":"strong"}]},{"text":" The client must explicitly specify the ","type":"text"},{"text":"versionId","type":"text","marks":[{"type":"em"}]},{"text":" of the object version to lock. ","type":"text"}]},{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"x-object-lock-meta-mode: \nx-object-lock-meta-retain-until-date: \nx-object-lock-meta-original-lifepoints: \nlifepoint: [] deletable=no, ","type":"text"}]},{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In compliance mode, this is not permitted","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In governance mode, it requires that the user has a special permission ","type":"text"},{"text":"BypassGovernanceRetention","type":"text","marks":[{"type":"code"}]},{"text":". ","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"paragraph","content":[{"text":"An ","type":"text"},{"text":"S3 request ","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"2e0b9f0e-fc33-4d46-834d-536582da552c"}}]},{"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 that requires overriding governance mode. Using S3, one enables/inspects a 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"}},{"text":" ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"type":"inlineCard","attrs":{"url":"https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObjectRetention.html"}},{"text":" ","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":" Using SCSP, one enables/inspects a retention period on an object using the following calls: ","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":1800.0,"localId":"f485b42b-ebcc-4065-8864-1457c64019f3"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[319.0]},"content":[{"type":"paragraph","content":[{"text":"Call Type","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[441.0]},"content":[{"type":"paragraph","content":[{"text":"Purpose","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[319.0]},"content":[{"type":"paragraph","content":[{"text":"PUT //

Browser not supported