Add support for object locking with legal hold. (#8634)

docs/retention/README.md

@@ -5,6 +5,9 @@ MinIO server allows selectively specify WORM for specific objects or configuring
 Object locking requires locking to be enabled on a bucket at the time of bucket creation. In addition, a default retention period and retention mode can be configured on a bucket to be
 applied to objects created in that bucket.
 
+Independently of retention, an object can also be under legal hold. This effectively disallows
+all deletes and overwrites of an object under legal hold until the hold is lifted.
+
 ## Get Started
 
 ### 1. Prerequisites
@@ -29,10 +32,22 @@ aws s3api put-object --bucket testbucket --key lockme --object-lock-mode GOVERNA
 See https://docs.aws.amazon.com/AmazonS3/latest/dev/object-lock-overview.html for AWS S3 spec on
 object locking and permissions required for object retention and governance bypass overrides.
 
+### Set legal hold on an object
+
+PutObject API allows setting legal hold using `x-amz-object-lock-legal-hold` header.
+
+```sh
+aws s3api put-object --bucket testbucket --key legalhold --object-lock-legal-hold-status ON --body /etc/issue
+```
+
+See https://docs.aws.amazon.com/AmazonS3/latest/dev/object-lock-overview.html for AWS S3 spec on
+object locking and permissions required for specifying legal hold.
+
 ### 3. Note
 
 - When global WORM is enabled by `MINIO_WORM` environment variable or `worm` field in configuration file supersedes bucket level WORM and `PUT object lock configuration` REST API is disabled.
 - In global WORM mode objects can never be overwritten
+- If an object is under legal hold, it cannot be overwritten unless the legal hold is explicitly removed.
 - In `Compliance` mode, objects cannot be overwritten or deleted by anyone until retention period
 is expired. If user has requisite governance bypass permissions, an object's retention date can
 be extended in `Compliance` mode.