# Locking objects with Object Lock S3 Object Lock can help prevent Amazon S3 objects from being deleted or overwritten for a fixed amount of time or indefinitely. Object Lock uses a *write-once-read-many* (WORM) model to store objects. You can use Object Lock to help meet regulatory requirements that require WORM storage, or to add another layer of protection against object changes or deletion. **Note** S3 Object Lock has been assessed by Cohasset Associates for use in environments that are subject to SEC 17a-4, CFTC, and FINRA regulations. For more information about how Object Lock relates to these regulations, see the [Cohasset Associates Compliance Assessment](https://d1.awsstatic.com/r2018/b/S3-Object-Lock/Amazon-S3-Compliance-Assessment.pdf). Object Lock provides two ways to manage object retention: *retention periods* and *legal holds*. An object version can have a retention period, a legal hold, or both. + **Retention period** – A retention period specifies a fixed period of time during which an object version remains locked. You can set a unique retention period for individual objects. Additionally, you can set a default retention period on an S3 bucket. You may also restrict the minimum and maximum allowable retention periods with the `s3:object-lock-remaining-retention-days` condition key in the bucket policy. This condition key helps you establish the allowable retention period. For more information, see [Setting limits on retention periods with a bucket policy](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock-managing.html#object-lock-managing-retention-limits). + **Legal hold** – A legal hold provides the same protection as a retention period, but it has no expiration date. Instead, a legal hold remains in place until you explicitly remove it. Legal holds are independent from retention periods and are placed on individual object versions. Object Lock works only in buckets that have S3 Versioning enabled. When you lock an object version, Amazon S3 stores the lock information in the metadata for that object version. Placing a retention period or a legal hold on an object protects only the version that's specified in the request. Retention periods and legal holds don't prevent new versions of the object from being created, or delete markers to be added on top of the object. For information about S3 Versioning, see [Retaining multiple versions of objects with S3 Versioning](Versioning.md). If you put an object into a bucket that already contains an existing protected object with the same object key name, Amazon S3 creates a new version of that object. The existing protected version of the object remains locked according to its retention configuration. ## How S3 Object Lock works **Topics** + [ ### Retention periods ](#object-lock-retention-periods) + [ ### Retention modes ](#object-lock-retention-modes) + [ ### Legal holds ](#object-lock-legal-holds) + [ ### How deletes work with S3 Object Lock ](#object-lock-how-deletes-work) + [ ### Best practices for using S3 Object Lock ](#object-lock-best-practices) + [ ### Required permissions ](#object-lock-permissions) ### Retention periods A *retention period* protects an object version for a fixed amount of time. When you place a retention period on an object version, Amazon S3 stores a timestamp in the object version's metadata to indicate when the retention period expires. After the retention period expires, the object version can be overwritten or deleted. You can place a retention period explicitly on an individual object version or on a bucket's properties so that it applies to all objects in the bucket automatically. When you apply a retention period to an object version explicitly, you specify a *Retain Until Date* for the object version. Amazon S3 stores this date in the object version's metadata. You can also set a retention period in a bucket's properties. When you set a retention period on a bucket, you specify a duration, in either days or years, for how long to protect every object version placed in the bucket. When you place an object in the bucket, Amazon S3 calculates a *Retain Until Date* for the object version by adding the specified duration to the object version's creation timestamp. The object version is then protected exactly as though you explicitly placed an individual lock with that retention period on the object version. **Note** When you `PUT` an object version that has an explicit individual retention mode and period in a bucket, the object version's individual Object Lock settings override any bucket property retention settings. Like all other Object Lock settings, retention periods apply to individual object versions. Different versions of a single object can have different retention modes and periods. For example, suppose that you have an object that is 15 days into a 30-day retention period, and you `PUT` an object into Amazon S3 with the same name and a 60-day retention period. In this case, your `PUT` request succeeds, and Amazon S3 creates a new version of the object with a 60-day retention period. The older version maintains its original retention period and becomes deletable in 15 days. After you've applied a retention setting to an object version, you can extend the retention period. To do this, submit a new Object Lock request for the object version with a *Retain Until Date* that is later than the one currently configured for the object version. Amazon S3 replaces the existing retention period with the new, longer period. Any user with permissions to place an object retention period can extend a retention period for an object version. To set a retention period, you must have the `s3:PutObjectRetention` permission. When you set a retention period on an object or S3 bucket, you must select one of two retention modes: *compliance* or *governance*. ### Retention modes S3 Object Lock provides two retention modes that apply different levels of protection to your objects: + Compliance mode + Governance mode In *compliance* mode, a protected object version can't be overwritten or deleted by any user, including the root user in your AWS account. When an object is locked in compliance mode, its retention mode can't be changed, and its retention period can't be shortened. Compliance mode helps ensure that an object version can't be overwritten or deleted for the duration of the retention period. **Note** The only way to delete an object under the compliance mode before its retention date expires is to delete the associated AWS account. In *governance* mode, users can't overwrite or delete an object version or alter its lock settings unless they have special permissions. With governance mode, you protect objects against being deleted by most users, but you can still grant some users permission to alter the retention settings or delete the objects if necessary. You can also use governance mode to test retention-period settings before creating a compliance-mode retention period. To override or remove governance-mode retention settings, you must have the `s3:BypassGovernanceRetention` permission and must explicitly include `x-amz-bypass-governance-retention:true` as a request header with any request that requires overriding governance mode. **Note** By default, the Amazon S3 console includes the `x-amz-bypass-governance-retention:true` header. If you try to delete objects protected by *governance* mode and have the `s3:BypassGovernanceRetention` permission, the operation will succeed. ### Legal holds With Object Lock, you can also place a *legal hold* on an object version. Like a retention period, a legal hold prevents an object version from being overwritten or deleted. However, a legal hold doesn't have an associated fixed amount of time and remains in effect until removed. Legal holds can be freely placed and removed by any user who has the `s3:PutObjectLegalHold` permission. Legal holds are independent from retention periods. Placing a legal hold on an object version doesn't affect the retention mode or retention period for that object version. For example, suppose that you place a legal hold on an object version and that object version is also protected by a retention period. If the retention period expires, the object doesn't lose its WORM protection. Rather, the legal hold continues to protect the object until an authorized user explicitly removes the legal hold. Similarly, if you remove a legal hold while an object version has a retention period in effect, the object version remains protected until the retention period expires. ### How deletes work with S3 Object Lock If your bucket has S3 Object Lock enabled and the object is protected by a retention period or legal hold and you try to delete an object, Amazon S3 returns one of the following responses, depending on how you tried to delete the object: + **Permanent `DELETE` request** – If you issued a permanent `DELETE` request (a request that specifies a version ID), Amazon S3 returns an Access Denied (`403 Forbidden`) error when you try to delete the object. For more information about troubleshooting Access Denied errors with Object Lock, see [S3 Object Lock settings](troubleshoot-403-errors.md#troubleshoot-403-object-lock). + **Simple `DELETE` request** – If you issued a simple `DELETE` request (a request that doesn't specify a version ID), Amazon S3 returns a `200 OK` response and inserts a [delete marker](DeleteMarker.md) in the bucket, and that marker becomes the current version of the object with a new ID. For more information about managing delete markers with Object Lock, see [Managing delete markers with Object Lock](object-lock-managing.md#object-lock-managing-delete-markers). ### Best practices for using S3 Object Lock Consider using *Governance mode* if you want to protect objects from being deleted by most users during a pre-defined retention period, but at the same time want some users with special permissions to have the flexibility to alter the retention settings or delete the objects. Consider using *Compliance mode* if you never want any user, including the root user in your AWS account, to be able to delete the objects during a pre-defined retention period. You can use this mode in case you have a requirement to store compliant data. You can use *Legal Hold* when you are not sure for how long you want your objects to stay immutable. This could be because you have an upcoming external audit of your data and want to keep objects immutable till the audit is complete. Alternately, you may have an ongoing project utilizing a dataset that you want to keep immutable until the project is complete. ### Required permissions Object Lock operations require specific permissions. Depending on the exact operation that you're attempting, you might need any of the following permissions: + `s3:BypassGovernanceRetention` + `s3:GetBucketObjectLockConfiguration` + `s3:GetObjectLegalHold` + `s3:GetObjectRetention` + `s3:PutBucketObjectLockConfiguration` + `s3:PutObjectLegalHold` + `s3:PutObjectRetention` For a complete list of Amazon S3 permissions with descriptions, see [ Actions, resources, and condition keys for Amazon S3](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazons3.html) in the *Service Authorization Reference*. For more information about the permissions to S3 API operations by S3 resource types, see [Required permissions for Amazon S3 API operations](using-with-s3-policy-actions.md). For information about using conditions with permissions, see [Bucket policy examples using condition keys](amazon-s3-policy-keys.md). # Object Lock considerations Amazon S3 Object Lock can help prevent objects from being deleted or overwritten for a fixed amount of time or indefinitely. You can use the Amazon S3 console, AWS Command Line Interface (AWS CLI), AWS SDKs, or Amazon S3 REST API to view or set Object Lock information. For general information about S3 Object Lock capabilities, see [Locking objects with Object Lock](object-lock.md). **Important** After you enable Object Lock on a bucket, you can't disable Object Lock or suspend versioning for that bucket. S3 buckets with Object Lock can't be used as destination buckets for server access logs. For more information, see [Logging requests with server access logging](ServerLogs.md). **Topics** + [ ## Permissions for viewing lock information ](#object-lock-managing-view) + [ ## Bypassing governance mode ](#object-lock-managing-bypass) + [ ## Using Object Lock with S3 Replication ](#object-lock-managing-replication) + [ ## Using Object Lock with encryption ](#object-lock-managing-encryption) + [ ## Using Object Lock with Amazon S3 Inventory ](#object-lock-inv-report) + [ ## Managing S3 Lifecycle policies with Object Lock ](#object-lock-managing-lifecycle) + [ ## Managing delete markers with Object Lock ](#object-lock-managing-delete-markers) + [ ## Using S3 Storage Lens with Object Lock ](#object-lock-storage-lens) + [ ## Uploading objects to an Object Lock enabled bucket ](#object-lock-put-object) + [ ## Configuring events and notifications ](#object-lock-managing-events) + [ ## Setting limits on retention periods with a bucket policy ](#object-lock-managing-retention-limits) ## Permissions for viewing lock information You can programmatically view the Object Lock status of an Amazon S3 object version by using the [https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html) or [https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) operations. Both operations return the retention mode, retain until date, and legal hold status for the specified object version. Additionally, you can view the Object Lock status for multiple objects in your S3 bucket using S3 Inventory. To view an object version's retention mode and retention period, you must have the `s3:GetObjectRetention` permission. To view an object version's legal hold status, you must have the `s3:GetObjectLegalHold` permission. To view a bucket's default retention configuration, you must have the `s3:GetBucketObjectLockConfiguration` permission. If you make a request for an Object Lock configuration on a bucket that doesn't have S3 Object Lock enabled, Amazon S3 returns an error. ## Bypassing governance mode If you have the `s3:BypassGovernanceRetention` permission, you can perform operations on object versions that are locked in governance mode as if they were unprotected. These operations include deleting an object version, shortening the retention period, or removing the Object Lock retention period by placing a new `PutObjectRetention` request with empty parameters. To bypass governance mode, you must explicitly indicate in your request that you want to bypass this mode. To do this, include the `x-amz-bypass-governance-retention:true` header with your `PutObjectRetention` API operation request, or use the equivalent parameter with requests made through the AWS CLI or AWS SDKs. The S3 console automatically applies this header for requests made through the S3 console if you have the `s3:BypassGovernanceRetention` permission. **Note** Bypassing governance mode doesn't affect an object version's legal hold status. If an object version has a legal hold enabled, the legal hold remains and prevents requests to overwrite or delete the object version. ## Using Object Lock with S3 Replication You can use Object Lock with S3 Replication to enable automatic, asynchronous copying of locked objects and their retention metadata, across S3 buckets. This means that for replicated objects, Amazon S3 takes the object lock configuration of the source bucket. In other words, if the source bucket has Object Lock enabled, the destination buckets must also have Object Lock enabled. If an object is directly uploaded to the destination bucket (outside of S3 Replication), it takes the Object Lock set on the destination bucket. When you use replication, objects in a *source bucket* are replicated to one or more *destination buckets*. To set up replication on a bucket with Object Lock enabled, you can use the S3 console, AWS CLI, Amazon S3 REST API, or AWS SDKs. **Note** To use Object Lock with replication, you must grant two additional permissions on the source S3 bucket in the AWS Identity and Access Management (IAM) role that you use to set up replication. The two additional permissions are `s3:GetObjectRetention` and `s3:GetObjectLegalHold`. If the role has an `s3:Get*` permission statement, that statement satisfies the requirement. For more information, see [Setting up permissions for live replication](setting-repl-config-perm-overview.md). For general information about S3 Replication, see [Replicating objects within and across Regions](replication.md). For examples of setting up S3 Replication, see [Examples for configuring live replication](replication-example-walkthroughs.md). ## Using Object Lock with encryption Amazon S3 encrypts all new objects by default. You can use Object Lock with your encrypted objects. For more information, see [Protecting data with encryption](UsingEncryption.md). While Object Lock can help prevent Amazon S3 objects from being deleted or overwritten, it does not protect against losing access to the encryption keys or encryption keys being deleted. For example, if you encrypt your objects with AWS KMS server-side encryption and your AWS KMS key is deleted your objects may become unreadable. ## Using Object Lock with Amazon S3 Inventory You can configure Amazon S3 Inventory to create lists of the objects in an S3 bucket on a defined schedule. You can configure Amazon S3 Inventory to include the following Object Lock metadata for your objects: + The retain until date + The retention mode + The legal hold status For more information, see [Cataloging and analyzing your data with S3 Inventory](storage-inventory.md). ## Managing S3 Lifecycle policies with Object Lock Object lifecycle management configurations continue to function normally on protected objects, including placing delete markers. However, a locked version of an object cannot be deleted by a S3 Lifecycle expiration policy. Object Lock is maintained regardless of which storage class the object resides in and throughout S3 Lifecycle transitions between storage classes. For more information about managing object lifecycles, see [Managing the lifecycle of objects](object-lifecycle-mgmt.md). ## Managing delete markers with Object Lock Although you can't delete a protected object version, you can still create a delete marker for that object. Placing a delete marker on an object doesn't delete the object or its object versions. However, it makes Amazon S3 behave in most ways as though the object has been deleted. For more information, see [Working with delete markers](DeleteMarker.md). **Note** Delete markers are not WORM-protected, regardless of any retention period or legal hold in place on the underlying object. ## Using S3 Storage Lens with Object Lock To see metrics for Object Lock-enabled storage bytes and object count, you can use Amazon S3 Storage Lens. S3 Storage Lens is a cloud-storage analytics feature that you can use to gain organization-wide visibility into object-storage usage and activity. For more information, see [Using S3 Storage Lens to protect your data](storage-lens-data-protection.md). For a complete list of metrics, see [Amazon S3 Storage Lens metrics glossary](storage_lens_metrics_glossary.md). ## Uploading objects to an Object Lock enabled bucket The `Content-MD5` or `x-amz-sdk-checksum-algorithm` header is required for any request to upload an object with a retention period configured using Object Lock. Theses headers are a way to verify the integrity of your object during upload. When uploading an object with the Amazon S3 console, S3 automatically adds the `Content-MD5` header. You can optionally specify an additional checksum function and checksum value through the console as the `x-amz-sdk-checksum-algorithm` header. If you use the [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) API you must specify the `Content-MD5` header, the `x-amz-sdk-checksum-algorithm` header, or both to configure the Object Lock retention period. For more information, see [Checking object integrity in Amazon S3](checking-object-integrity.md). ## Configuring events and notifications You can use Amazon S3 Event Notifications to track access and changes to your Object Lock configurations and data by using AWS CloudTrail. For information about CloudTrail, see [What is AWS CloudTrail?](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html) in the *AWS CloudTrail User Guide*. You can also use Amazon CloudWatch to generate alerts based on this data. For information about CloudWatch, see the [What is Amazon CloudWatch?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) in the *Amazon CloudWatch User Guide*. ## Setting limits on retention periods with a bucket policy You can set minimum and maximum allowable retention periods for a bucket by using a bucket policy. The maximum retention period is 100 years. The following example shows a bucket policy that uses the `s3:object-lock-remaining-retention-days` condition key to set a maximum retention period of 10 days. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Id": "SetRetentionLimits", "Statement": [ { "Sid": "SetRetentionPeriod", "Effect": "Deny", "Principal": "*", "Action": [ "s3:PutObjectRetention" ], "Resource": "arn:aws:s3:::amzn-s3-demo-bucket1/*", "Condition": { "NumericGreaterThan": { "s3:object-lock-remaining-retention-days": "10" } } } ] } ``` ------ **Note** If your bucket is the destination bucket for a replication configuration, you can set up minimum and maximum allowable retention periods for object replicas that are created by using replication. To do so, you must allow the `s3:ReplicateObject` action in your bucket policy. For more information about replication permissions, see [Setting up permissions for live replication](setting-repl-config-perm-overview.md). For more information about bucket policies, see the following topics: + [ Actions, resources, and condition keys for Amazon S3](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazons3.html) in the *Service Authorization Reference* For more information about the permissions to S3 API operations by S3 resource types, see [Required permissions for Amazon S3 API operations](using-with-s3-policy-actions.md). + [Object operations](security_iam_service-with-iam.md#using-with-s3-actions-related-to-objects) + [Bucket policy examples using condition keys](amazon-s3-policy-keys.md) # Configuring S3 Object Lock With Amazon S3 Object Lock, you can store objects in Amazon S3 general purpose buckets by using a *write-once-read-many* (WORM) model. You can use S3 Object Lock to prevent an object from being deleted or overwritten for a fixed amount of time or indefinitely. For general information about Object Lock capabilities, see [Locking objects with Object Lock](object-lock.md). Before you lock any objects, you must enable S3 Versioning and Object Lock on a general purpose bucket. Afterward, you can set a retention period, a legal hold, or both. To work with Object Lock, you must have certain permissions. For a list of the permissions related to various Object Lock operations, see [Required permissions](object-lock.md#object-lock-permissions). **Important** After you enable Object Lock on a bucket, you can't disable Object Lock or suspend versioning for that bucket. S3 buckets with Object Lock can't be used as destination buckets for server access logs. For more information, see [Logging requests with server access logging](ServerLogs.md). **Topics** + [ ## Enable Object Lock when creating a new S3 general purpose bucket ](#object-lock-configure-new-bucket) + [ ## Enable Object Lock on an existing S3 bucket ](#object-lock-configure-existing-bucket) + [ ## Set or modify a legal hold on an S3 object ](#object-lock-configure-set-legal-hold) + [ ## Set or modify a retention period on an S3 object ](#object-lock-configure-set-retention-period-object) + [ ## Set or modify a default retention period on an S3 bucket ](#object-lock-configure-set-retention-period-bucket) ## Enable Object Lock when creating a new S3 general purpose bucket You can enable Object Lock when creating a new S3 general purpose bucket by using the Amazon S3 console, AWS Command Line Interface (AWS CLI), AWS SDKs, or Amazon S3 REST API. ### Using the S3 console 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the left navigation pane, choose **General purpose buckets**. 1. Choose **Create bucket**. The **Create bucket** page opens. 1. For **Bucket name**, enter a name for your bucket. **Note** After you create a bucket, you can't change its name. For more information about naming buckets, see [General purpose bucket naming rules](bucketnamingrules.md). 1. For **Region**, choose the AWS Region where you want the bucket to reside. 1. Under **Object Ownership**, choose to disable or enable access control lists (ACLs) and control ownership of objects uploaded in your bucket. 1. Under **Block Public Access settings for this bucket**, choose the Block Public Access settings that you want to apply to the bucket. 1. Under **Bucket Versioning**, choose **Enabled**. Object Lock works only with versioned buckets. 1. (Optional) Under **Tags**, you can choose to add tags to your bucket. Tags are key-value pairs that are used to categorize storage and allocate costs. 1. Under **Advanced settings**, find **Object Lock** and choose **Enable**. You must acknowledge that enabling Object Lock will permanently allow objects in this bucket to be locked. 1. Choose **Create bucket**. ### Using the AWS CLI The following `create-bucket` example creates a new S3 bucket named `amzn-s3-demo-bucket1` with Object Lock enabled: ``` aws s3api create-bucket --bucket amzn-s3-demo-bucket1 --object-lock-enabled-for-bucket ``` For more information and examples, see [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/create-bucket.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/create-bucket.html) in the *AWS CLI Command Reference*. **Note** You can run AWS CLI commands from the console by using AWS CloudShell. AWS CloudShell is a browser-based, pre-authenticated shell that you can launch directly from the AWS Management Console. For more information, see [What is CloudShell?](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html) in the *AWS CloudShell User Guide*. ### Using the REST API You can use the REST API to create a new S3 bucket with Object Lock enabled. For more information, see [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html) in the *Amazon Simple Storage Service API Reference*. ### Using the AWS SDKs For examples of how to enable Object Lock when creating a new S3 bucket with the AWS SDKs, see [Code examples](https://docs.aws.amazon.com/AmazonS3/latest/API/s3_example_s3_LCreateBucket_section.html) in the *Amazon S3 API Reference*. For examples of how to get the current Object Lock configuration with the AWS SDKs, see [Code examples](https://docs.aws.amazon.com/AmazonS3/latest/API/s3_example_s3_GetObjectLockConfiguration_section.html) in the *Amazon S3 API Reference*. For an interactive scenario demonstrating different Object Lock features using the AWS SDKs, see [Code examples](https://docs.aws.amazon.com/AmazonS3/latest/API/s3_example_s3_Scenario_ObjectLock_section.html) in the *Amazon S3 API Reference*. For general information about using different AWS SDKs, see [Developing with Amazon S3 using the AWS SDKs](https://docs.aws.amazon.com/AmazonS3/latest/API/sdk-general-information-section.html) in the *Amazon S3 API Reference*. ## Enable Object Lock on an existing S3 bucket You can enable Object Lock for an existing S3 bucket by using the Amazon S3 console, the AWS CLI, AWS SDKs, or Amazon S3 REST API. ### Using the S3 console **Note** Object Lock works only with versioned buckets. 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the left navigation pane, choose **Buckets**. 1. In the **Buckets** list, choose the name of the bucket that you want to enable Object Lock on. 1. Choose the **Properties** tab. 1. Under **Properties**, scroll down to the **Object Lock** section, and choose **Edit**. 1. Under **Object Lock**, choose **Enable**. You must acknowledge that enabling Object Lock will permanently allow objects in this bucket to be locked. 1. Choose **Save changes**. ### Using the AWS CLI The following `put-object-lock-configuration` example command sets a 50-day Object Lock retention period on a bucket named `amzn-s3-demo-bucket1`: ``` aws s3api put-object-lock-configuration --bucket amzn-s3-demo-bucket1 --object-lock-configuration='{ "ObjectLockEnabled": "Enabled", "Rule": { "DefaultRetention": { "Mode": "COMPLIANCE", "Days": 50 }}}' ``` For more information and examples, see [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/put-object-lock-configuration.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/put-object-lock-configuration.html) in the *AWS CLI Command Reference*. **Note** You can run AWS CLI commands from the console by using AWS CloudShell. AWS CloudShell is a browser-based, pre-authenticated shell that you can launch directly from the AWS Management Console. For more information, see [What is CloudShell?](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html) in the *AWS CloudShell User Guide*. ### Using the REST API You can use the Amazon S3 REST API to enable Object Lock on an existing S3 bucket. For more information, see [https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectLockConfiguration.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectLockConfiguration.html) in the *Amazon Simple Storage Service API Reference*. ### Using the AWS SDKs For examples of how to enable Object Lock for an existing S3 bucket with the AWS SDKs, see [Code examples](https://docs.aws.amazon.com/AmazonS3/latest/API/s3_example_s3_PutObjectLockConfiguration_section.html) in the *Amazon S3 API Reference*. For examples of how to get the current Object Lock configuration with the AWS SDKs, see [Code examples](https://docs.aws.amazon.com/AmazonS3/latest/API/s3_example_s3_GetObjectLockConfiguration_section.html) in the *Amazon S3 API Reference*. For an interactive scenario demonstrating different Object Lock features using the AWS SDKs, see [Code examples](https://docs.aws.amazon.com/AmazonS3/latest/API/s3_example_s3_Scenario_ObjectLock_section.html) in the *Amazon S3 API Reference*. For general information about using different AWS SDKs, see [Developing with Amazon S3 using the AWS SDKs](https://docs.aws.amazon.com/AmazonS3/latest/API/sdk-general-information-section.html) in the *Amazon S3 API Reference*. ## Set or modify a legal hold on an S3 object You can set or remove a legal hold on an S3 object by using the Amazon S3 console, AWS CLI, AWS SDKs, or Amazon S3 REST API. **Important** If you want to set a legal hold on an object, the object's bucket must already have Object Lock enabled. When you `PUT` an object version that has an explicit individual retention mode and period in a bucket, the object version's individual Object Lock settings override any bucket property retention settings. For more information, see [Legal holds](object-lock.md#object-lock-legal-holds). ### Using the S3 console 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the left navigation pane, choose **Buckets**. 1. In the **Buckets** list, choose the name of the bucket that contains the object that you want to set or modify a legal hold on. 1. In the **Objects** list, select the object that you want to set or modify a legal hold on. 1. On the **Object properties** page, find the **Object Lock legal hold** section, and choose **Edit**. 1. Choose **Enable** to set a legal hold or **Disable** to remove a legal hold. 1. Choose **Save changes**. ### Using the AWS CLI The following `put-object-legal-hold` example sets a legal hold on the object *`my-image.fs`* in the bucket named `amzn-s3-demo-bucket1`: ``` aws s3api put-object-legal-hold --bucket amzn-s3-demo-bucket1 --key my-image.fs --legal-hold="Status=ON" ``` The following `put-object-legal-hold` example removes a legal hold on the object *`my-image.fs`* in the bucket named `amzn-s3-demo-bucket1`: ``` aws s3api put-object-legal-hold --bucket amzn-s3-demo-bucket1 --key my-image.fs --legal-hold="Status=OFF" ``` For more information and examples, see [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/put-object-legal-hold.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/put-object-legal-hold.html) in the *AWS CLI Command Reference*. **Note** You can run AWS CLI commands from the console by using AWS CloudShell. AWS CloudShell is a browser-based, pre-authenticated shell that you can launch directly from the AWS Management Console. For more information, see [What is CloudShell?](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html) in the *AWS CloudShell User Guide*. ### Using the REST API You can use the REST API to set or modify a legal hold on an object. For more information, see [https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectLegalHold.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectLegalHold.html) in the *Amazon Simple Storage Service API Reference*. ### Using the AWS SDKs For examples of how to set a legal hold on an object with the AWS SDKs, see [Code examples](https://docs.aws.amazon.com/AmazonS3/latest/API/s3_example_s3_PutObjectLegalHold_section.html) in the *Amazon S3 API Reference*. For examples of how to get the current legal hold status with the AWS SDKs, see [Code examples](https://docs.aws.amazon.com/AmazonS3/latest/API/s3_example_s3_GetObjectLegalHoldConfiguration_section.html) in the *Amazon S3 API Reference*. For an interactive scenario demonstrating different Object Lock features using the AWS SDKs, see [Code examples](https://docs.aws.amazon.com/AmazonS3/latest/API/s3_example_s3_Scenario_ObjectLock_section.html) in the *Amazon S3 API Reference*. For general information about using different AWS SDKs, see [Developing with Amazon S3 using the AWS SDKs](https://docs.aws.amazon.com/AmazonS3/latest/API/sdk-general-information-section.html) in the *Amazon S3 API Reference*. ## Set or modify a retention period on an S3 object You can set or modify a retention period on an S3 object by using the Amazon S3 console, AWS CLI, AWS SDKs, or Amazon S3 REST API. **Important** If you want to set a retention period on an object, the object's bucket must already have Object Lock enabled. When you `PUT` an object version that has an explicit individual retention mode and period in a bucket, the object version's individual Object Lock settings override any bucket property retention settings. The only way to delete an object under the compliance mode before its retention date expires is to delete the associated AWS account. For more information, see [Retention periods](object-lock.md#object-lock-retention-periods). ### Using the S3 console 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the left navigation pane, choose **Buckets**. 1. In the **Buckets** list, choose the name of the bucket that contains the object that you want to set or modify a retention period on. 1. In the **Objects** list, select the object that you want to set or modify a retention period on. 1. On the **Object properties** page, find the **Object Lock retention** section, and choose **Edit**. 1. Under **Retention**, choose **Enable** to set a retention period or **Disable** to remove a retention period. 1. If you chose **Enable**, under **Retention mode**, choose either **Governance mode** or **Compliance mode**. For more information, see [Retention modes](object-lock.md#object-lock-retention-modes). 1. Under **Retain until date**, choose the date that you want to have the retention period end on. During this period, your object is WORM-protected and can't be overwritten or deleted. For more information, see [Retention periods](object-lock.md#object-lock-retention-periods). 1. Choose **Save changes**. ### Using the AWS CLI The following `put-object-retention` example sets a retention period on the object *`my-image.fs`* in the bucket named `amzn-s3-demo-bucket1` until January 1, 2025: ``` aws s3api put-object-retention --bucket amzn-s3-demo-bucket1 --key my-image.fs --retention='{ "Mode": "GOVERNANCE", "RetainUntilDate": "2025-01-01T00:00:00" }' ``` For more information and examples, see [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/put-object-retention.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/put-object-retention.html) in the *AWS CLI Command Reference*. **Note** You can run AWS CLI commands from the console by using AWS CloudShell. AWS CloudShell is a browser-based, pre-authenticated shell that you can launch directly from the AWS Management Console. For more information, see [What is CloudShell?](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html) in the *AWS CloudShell User Guide*. ### Using the REST API You can use the REST API to set a retention period on an object. For more information, see [https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectRetention.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectRetention.html) in the *Amazon Simple Storage Service API Reference*. ### Using the AWS SDKs For examples of how to set a retention period on an object with the AWS SDKs, see [Code examples](https://docs.aws.amazon.com/AmazonS3/latest/API/s3_example_s3_PutObjectRetention_section.html) in the *Amazon S3 API Reference*. For examples of how to get the retention period on an object with the AWS SDKs, see [Code examples](https://docs.aws.amazon.com/AmazonS3/latest/API/s3_example_s3_GetObjectLockConfiguration_section.html) in the *Amazon S3 API Reference*. For an interactive scenario demonstrating different Object Lock features using the AWS SDKs, see [Code examples](https://docs.aws.amazon.com/AmazonS3/latest/API/s3_example_s3_GetObjectLockConfiguration_section.html) in the *Amazon S3 API Reference*. For general information about using different AWS SDKs, see [Developing with Amazon S3 using the AWS SDKs](https://docs.aws.amazon.com/AmazonS3/latest/API/sdk-general-information-section.html) in the *Amazon S3 API Reference*. ## Set or modify a default retention period on an S3 bucket You can set or modify a default retention period on an S3 bucket by using the Amazon S3 console, AWS CLI, AWS SDKs, or Amazon S3 REST API. You specify a duration, in either days or years, for how long to protect every object version placed in the bucket. **Important** If you want to set a default retention period on a bucket, the bucket must already have Object Lock enabled. When you `PUT` an object version that has an explicit individual retention mode and period in a bucket, the object version's individual Object Lock settings override any bucket property retention settings. The only way to delete an object under the compliance mode before its retention date expires is to delete the associated AWS account. For more information, see [Retention periods](object-lock.md#object-lock-retention-periods). ### Using the S3 console 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the left navigation pane, choose **Buckets**. 1. In the **Buckets** list, choose the name of the bucket that you want to set or modify a default retention period on. 1. Choose the **Properties** tab. 1. Under **Properties**, scroll down to the **Object Lock** section, and choose **Edit**. 1. Under **Default retention**, choose **Enable** to set a default retention or **Disable** to remove a default retention. 1. If you chose **Enable**, under **Retention mode**, choose either **Governance mode** or **Compliance mode**. For more information, see [Retention modes](object-lock.md#object-lock-retention-modes). 1. Under **Default retention period**, choose the number of days or years that you want the retention period to last for. Objects placed in this bucket will be locked for this number of days or years. For more information, see [Retention periods](object-lock.md#object-lock-retention-periods). 1. Choose **Save changes**. ### Using the AWS CLI The following `put-object-lock-configuration` example command sets a 50-day Object Lock retention period on the bucket named `amzn-s3-demo-bucket1` by using compliance mode: ``` aws s3api put-object-lock-configuration --bucket amzn-s3-demo-bucket1 --object-lock-configuration='{ "ObjectLockEnabled": "Enabled", "Rule": { "DefaultRetention": { "Mode": "COMPLIANCE", "Days": 50 }}}' ``` The following `put-object-lock-configuration` example removes the default retention configuration on a bucket: ``` aws s3api put-object-lock-configuration --bucket amzn-s3-demo-bucket1 --object-lock-configuration='{ "ObjectLockEnabled": "Enabled"}' ``` For more information and examples, see [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/put-object-lock-configuration.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/put-object-lock-configuration.html) in the *AWS CLI Command Reference*. **Note** You can run AWS CLI commands from the console by using AWS CloudShell. AWS CloudShell is a browser-based, pre-authenticated shell that you can launch directly from the AWS Management Console. For more information, see [What is CloudShell?](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html) in the *AWS CloudShell User Guide*. ### Using the REST API You can use the REST API to set a default retention period on an existing S3 bucket. For more information, see [https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectLockConfiguration.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectLockConfiguration.html) in the *Amazon Simple Storage Service API Reference*. ### Using the AWS SDKs For examples of how to set a default retention period on an existing S3 bucket with the AWS SDKs, see [Code examples](https://docs.aws.amazon.com/AmazonS3/latest/API/s3_example_s3_PutObjectLockConfiguration_section.html) in the *Amazon S3 API Reference*. For an interactive scenario demonstrating different Object Lock features using the AWS SDKs, see [Code examples](https://docs.aws.amazon.com/AmazonS3/latest/API/s3_example_s3_Scenario_ObjectLock_section.html) in the *Amazon S3 API Reference*. For general information about using different AWS SDKs, see [Developing with Amazon S3 using the AWS SDKs](https://docs.aws.amazon.com/AmazonS3/latest/API/sdk-general-information-section.html) in the *Amazon S3 API Reference*.