# Object Lock & Retention

Object Lock provides write-once-read-many (WORM) protection for objects by preventing deletion or modification for a configured retention period. Aurora supports S3-compatible Object Lock semantics, including Governance and Compliance modes, per-object retention, default bucket retention, and legal holds.

## Prerequisites

- **Bucket versioning**: must be enabled.
- **Object Lock at creation**: buckets must be created with Object Lock enabled; you cannot enable it later for an existing bucket that did not have it.

## Concepts

- **Governance mode**: Prevents users without special permissions from removing or shortening retention.
  - **Who can change retention/lifecycle**: principals with explicit governance-bypass permission (for example, `s3:BypassGovernanceRetention`) can shorten or remove per-object retention and update protected versions.
  - **What it takes to delete**: privileged principals can permanently delete protected versions only when sending the governance bypass header; others must wait until retention expires.
  - **Bucket default retention changes**: require administrative permission to update the bucket’s object lock configuration; changing defaults does not reduce retention already applied to existing versions.
- **Compliance mode**: Absolutely prevents removing or shortening retention until the retention period expires (strongest protection; cannot be bypassed by administrators).
  - **Who can change retention/lifecycle**: no principal can remove or shorten per-object retention before expiry; bucket default retention may be changed, but it affects only future uploads.
  - **What it takes to delete**: permanent deletion of protected versions is blocked until retention expires and no legal hold is present; creating a delete marker does not remove protected versions.
- **Retention period**: Duration during which an object version is immutable. Defined by days or years, or by a specific retained‑until date.
- **Default retention**: Bucket‑level default applied automatically to new objects if no per‑object retention is provided.
- **Legal hold**: Independent, on/off flag that prevents deletion regardless of retention settings. Must be cleared before deletion.

> **Note**
>
> In Governance mode, bypass requires the special header `x-amz-bypass-governance-retention:true` and appropriate permission. Avoid granting this permission to routine keys.

## Enabling Object Lock

Create a bucket in the Dashboard UI with Versioning and Object Lock enabled:

1. **Buckets → Create Bucket**.
2. **Bucket name**: enter a name.
3. **Versioning**: enable.
4. **Object Lock**: enable (if presented) or ensure the bucket is created with Object Lock enabled by your administrator.
5. **Create** the bucket.

After the bucket exists and versioning is enabled, you can configure default retention via bucket UI.

## Recommended Access Key Permissions

For the most secure setups, grant only the permissions required by the workflow. Avoid Delete permissions and never grant governance bypass.

- **Backup writer** (upload with retention):
  - **Access**: Write (upload objects)
  - **Lock**: PutObjectRetention (set per-object retention) and/or rely on bucket default retention
  - **List (optional)**: enumerate keys for verification

- **Auditor/restore** (read-only with version awareness):
  - **Access**: Read, List
  - **Versioning**: GetBucketVersioning, ListBucketVersions, GetObjectVersion

> **Tip**
>
> Configure keys per bucket to ensure strict data scoping.

## Practical Examples

> Available S3 endpoint: `a-s3.aur.lu` (France, Albi).

### Ransomware-protected backups (180 days)

Goal: Ensure backups cannot be deleted or altered for 180 days.

1. **Create a bucket** in the Dashboard UI with Versioning and Object Lock enabled. Enable encryption.

2. **Default retention**: in the UI set COMPLIANCE for 180 days (strongest protection)

3. **Upload backups** (inherits default 180-day retention):

```bash
aws --profile aurora --endpoint-url https://a-s3.aur.lu s3 cp ./backup.tar s3://backups-immutable/2025-01-01/backup.tar
```

4. **Use multiple keys** with least privilege:
   - **Backup Writer key** (for upload only): Write, Optional List. Cannot read or delete, cannot shorten retention.
   - **Restore Reader key**: Read, List, Versioning: GetBucketVersioning, ListBucketVersions, GetObjectVersion. Cannot delete.

   Rationale: Separating duties limits blast radius if a key is compromised and supports clean audit trails.

### Compliance archives (7 years)

Goal: Retain records for 7 years without the ability to shorten or remove retention.

1. **Create a bucket** in the Dashboard UI with Versioning and Object Lock enabled. Enable encryption.

2. **Default retention**: in the UI set COMPLIANCE for 7 years

3. **Upload records** (inherit default retention):

```bash
aws --profile aurora --endpoint-url https://a-s3.aur.lu s3 cp ./record.json s3://records-archives/2025/01/record.json
```

4. **Legal hold (optional)**: place a legal hold on specific versions during investigation:

```bash
# Upload and capture version ID (versioning must be enabled)
aws --profile aurora --endpoint-url https://a-s3.aur.lu s3api put-object \
  --bucket records-archives \
  --key invoices/2025/01/invoice-123.json \
  --body invoice-123.json \
  --object-lock-mode COMPLIANCE \
  --object-lock-retain-until-date 2032-01-01T00:00:00Z

# Look up the version ID if needed
aws --profile aurora --endpoint-url https://a-s3.aur.lu s3api list-object-versions \
  --bucket records-archives \
  --prefix invoices/2025/01/invoice-123.json

# Apply legal hold to a specific version (replace VERSION_ID)
aws --profile aurora --endpoint-url https://a-s3.aur.lu s3api put-object-legal-hold \
  --bucket records-archives \
  --key invoices/2025/01/invoice-123.json \
  --legal-hold Status=ON \
  --version-id VERSION_ID
```

5. **Use multiple keys** with least privilege:
   - **Ingest Writer key**: Write only (rely on bucket default). Cannot read or delete.
   - **Compliance Officer key**: PutObjectRetention, GetObjectRetention, GetObjectLegalHold (no Write/Delete). Can view and apply retention/holds.
   - **Reviewer key**: Read, List, GetBucketVersioning, ListBucketVersions, GetObjectVersion (no Delete). Can verify objects and versions.

   Why multiple keys: Separates ingestion, compliance control, and read access for accountability and reduced blast radius.

### Immutable logs (30 days, Governance mode)

Goal: Ensure logs are tamper-evident and immutable for 30 days, with the option for emergency admin overrides (Governance mode).

1. **Create a bucket** in the Dashboard UI with Versioning and Object Lock enabled. Enable encrypiton for private data.

2. **Default retention**: set GOVERNANCE for 30 days in the UI

3. **Upload logs** (inherit default retention):

```bash
aws --profile aurora --endpoint-url https://a-s3.aur.lu s3 cp ./app.log s3://logs-immutable/2025-01-01/app.log
```

4. **Use multiple keys** with least privilege:
   - **Log Ingest key**: Write only. Cannot read/delete.
   - **Log Reader key**: Read, List. Cannot delete or change retention.
   - **Retention Adjuster** (optional): PutObjectRetention only for exceptions.

## Notes

- **Compliance mode**: retention cannot be shortened or removed.
- **Legal holds**: must be removed before deletion and are independent of retention.
- **Deletion permissions**: avoid granting Delete and DeleteObjectVersion on keys used for immutable workloads.