Configuring a Default WORM Policy for a Bucket

Function

OBS provides Write-Once-Read-Many (WORM) in compliance mode. After a WORM policy is configured for a bucket, if no protection policy or retention period is set for newly uploaded objects, the bucket-level WORM policy will be automatically applied to these objects. You can call this API to configure a default protection policy and retention period for a bucket. For more information about how to configure bucket-level WORM policies, see Configuring WORM to Protect Objects from Being Overwritten or Deleted.

With the bucket's default WORM policy, if you do not specify a WORM policy or a retention period when you upload an object to the bucket, the default policy will be automatically applied to the newly uploaded object. An object-level WORM policy requires configuring a specific date, which indicates an object will be protected until that date. For a default bucket-level WORM policy, a retention period is required, and the protection for an object starts when the object is uploaded to the bucket.

Constraints

• Before configuring object-level WORM, you must enable bucket-level WORM. If an object is protected by both bucket-level and object-level WORM, the object-level WORM policy takes precedence.
• The retention period of object-level WORM can only be extended but cannot be shortened.
• If you have deregistered your account or your account has been frozen, the WORM-protected objects will be permanently deleted.
• WORM does not protect parts generated during multipart uploads.
• When configuring bucket logging, do not store logs in a bucket with an active WORM retention policy. Because old files cannot be deleted, storage cost will continue to increase.
• If a bucket has WORM enabled, an append upload on this bucket will fail, with a 403 error returned.
• Only the compliance mode is supported.

• The WORM mode can only be COMPLIANCE.
• The retention period can be set to 1 to 36500 days or 1 to 100 years.
• You can modify or even delete the default WORM policy of a bucket. The change applies only to the objects uploaded after the change, but not to those uploaded before.
• During a multipart upload, the object parts uploaded are not protected before they are assembled. After object parts are assembled, the new object is protected by the default bucket-level WORM policy. You can also configure an object-level WORM policy for the new object.

Authorization

To call this API, you must be the bucket owner or have the permission to configure a default WORM policy for a bucket. You are advised to use IAM or bucket policies for authorization. For details about OBS authorization methods, see Differences Between OBS Permissions Control Methods.

• If you use IAM for authorization, you need to use either role/policy-based authorization or identity policy-based authorization and configure the required permissions:
  • If you use role/policy-based authorization (IAM v3 APIs in the old IAM version), you must have the obs:bucket:PutBucketObjectLockConfiguration permission. For details, see Creating a Custom IAM Policy.
  • If you use identity policy-based authorization (IAM v5 APIs in the new IAM version), you must have the obs:bucket:putBucketObjectLockConfiguration permission, as shown in the following table. For details, see Creating a Custom IAM Identity Policy.

    Action	Access Level	Resource Type (*: Required)	Condition Key	Alias	Dependencies
    obs:bucket:putBucketObjectLockConfiguration	Write	bucket *	g:EnterpriseProjectId g:ResourceTag/<tag-key>	-	-
    		-	obs:EpochTime obs:SourceIp obs:TlsVersion obs:CustomDomain

• If you use bucket policies for authorization, you must have the obs:bucket:PutBucketObjectLockConfiguration permission. For details, see Creating a Custom Bucket Policy.

URI

PUT /

Calling Method

For details, see Calling APIs. Before calling this API, calculate the API signature and add it to the request.

You can debug this API in API Explorer.

Request Syntax

PUT /?object-lock HTTP/1.1
Host: bucketname.obs.region.myhuaweicloud.com 
Date: date
Authorization: authorization
Content-Type: application/xml
Content-Length: length
<ObjectLockConfiguration xmlns="http://obs.region.myhuaweicloud.com/doc/2015-06-30/">
    
          <ObjectLockEnabled>Enabled</ObjectLockEnabled>
    <Rule>
       <!--In DefaultRetention, set either Days or Years to a non-zero value (ensuring that it is within the valid range), and leave the other at zero or omit it entirely. Do not set both Days and Years to non-zero values simultaneously.-->
       <DefaultRetention>
          <Days>integer</Days>
          <Mode>COMPLIANCE</Mode>
          <Years>integer</Years>
       </DefaultRetention>
    </Rule>
</ObjectLockConfiguration>

URI Parameters

This request contains no URI parameters.

Request Headers

This request uses common headers. For details, see Table 3.

Request Body

Response Syntax

HTTP/1.1 status_code
Date: date
Content-Length: length

Response Headers

This response uses common headers. For details, see Table 1.

Response Body

This response does not contain a response body.

Error Responses

Table 5 describes possible special errors in this request.

Refer to Error Code Overview for all other errors.

Sample Request 1

Configure the default bucket-level WORM policy with a retention period of 2 years.

PUT /?object-lock HTTP/1.1
Host: bucketname.obs.region.myhuaweicloud.com 
Date: Wed, 01 Jul 2015 02:25:05 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:75/Y4Ng1izvzc1nTGxpMXTE6ynw=
Content-Type: application/xml
Content-Length: 157
<ObjectLockConfiguration xmlns="http://obs.region.myhuaweicloud.com/doc/2015-06-30/">
    <ObjectLockEnabled>Enabled</ObjectLockEnabled>
    <Rule>
       <DefaultRetention>
          <Mode>COMPLIANCE</Mode>
          <Years>2</Years>
       </DefaultRetention>
    </Rule>
</ObjectLockConfiguration>

Sample Response 1

HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: BF260000016435CE298386946AE4C482
x-obs-id-2: 32AAAQAAEAABSAAgAAEAABAAAQAAEAABCT9W2tcvLmMJ+plfdopaD62S0npbaRUz
Date: Wed, 01 Jul 2015 02:25:06 GMT
Content-Length: 0

Sample Request 2

Delete the configuration of the default bucket-level WORM policy.

PUT /?object-lock HTTP/1.1
Host: bucketname.obs.region.myhuaweicloud.com 
Date: Wed, 01 Jul 2015 02:25:05 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:75/Y4Ng1izvzc1nTGxpMXTE6ynw=
Content-Type: application/xml
Content-Length: 157
<ObjectLockConfiguration xmlns="http://obs.region.myhuaweicloud.com/doc/2015-06-30/">
</ObjectLockConfiguration>

Sample Response 2

HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: BF260000016435CE298386946AE4C482
x-obs-id-2: 32AAAQAAEAABSAAgAAEAABAAAQAAEAABCT9W2tcvLmMJ+plfdopaD62S0npbaRUz
Date: Wed, 01 Jul 2015 02:25:06 GMT
Content-Length: 0

Helpful Links

• For more information about how to configure bucket-level WORM policies, see Configuring WORM to Protect Objects from Being Overwritten or Deleted.
• For details about the billing items involved in API operations, see Billing Items.