Upload an object to an IBM Immutable Storage protected bucket

Edit online

This enhancement of the PUT operation adds three new request headers: two for specifying the retention period in different ways, and one for adding a single legal hold to the new object. New errors are defined for illegal values for the new headers. If an object is under retention, it cannot be overwritten or deleted.

Objects in protected buckets that are no longer under retention (retention period has expired and the object does not have any legal holds), when overwritten, will again come under retention. The new retention period can be provided as part of the object overwrite request or the default retention time of the bucket will be given to the object.

The storage account user making a PUT Object with Retention Header request must have WRITE_ACP permissions for this object. For more information, see Create an ACL for an object.

AWS Signature V4 is required for this operation, as well as a hash or checksum for an integrity check by using either Content-md5, a x-amz-checksum- header, or the actual SHA-256 value in the x-amz-content-sha256 header. It is recommended that protection headers are included in the signature.

Requests

Edit online

Syntax

PUT /BucketName/ObjectName HTTP/1.1
Host: myBucket.mydsNet.corp.com
Date: Wed, 8Feb 201717:50:00GMT
Authorization: {authorization-string}
Content-Type: text/plain
Retention-Period: 220752000
Retention-Legal-Hold-Id: SomeLegalHold2012

Note: The syntax only shows the new request headers.

Request headers

Table 1. Protection request headers
Name	Type	Description
Content-MD5	String	The base64-encoded 128-bit MD5 digest of the message (without the headers) according to RFC 1864.
Retention-Period	Non-negative integer (in seconds) or `-1` or `-2`	Retention period to store on the object in seconds. The object can be neither overwritten nor deleted until the amount of time specified in the retention period has elapsed. If both `Retention-Period` and `Retention-Expiration-Date` are specified, a 400 error is returned. If neither is specified, the bucket's DefaultRetention period will be used. A retention period of `-1` indicates indefinite retention for the object. A retention period of `-1` can only be specified at the initial object creation. An object with a retention period of `-1` cannot be overwritten or deleted. The indefinite retention period for an object can be changed to a finite value at any time with the retention extension operation. Once an object has been given a positive value for the retention period, that object cannot be given a retention period of `-1`. A retention period of `-2` indicates permanent retention for the object. In order to specify `-2`, permanent retention must be enabled on the bucket in which this object resides. Once an object is permanently retained, the object, and thus the bucket which contains the object, cannot be deleted. 0 is a legal value assuming the bucket's minimum retention period is also 0. Constraints Retention-Period must be greater than or equal to the bucket MinimumRetention and less than or equal to the bucket MaximumRetention
Retention-Expiration-Date	Date (ISO 8601 Format)	Date on which it is possible to delete or modify the object. You can only specify this or the `Retention-Period` header. If both are specified a 400 error will be returned. If neither is specified the bucket's DefaultRetention period will be used. This header should be used to calculate a retention period in seconds and then stored in that manner. Constraints The Retention-Expiration-Date must be greater than or equal to `(current time + bucket MinimumRetention)` and less than or equal to `(current time + bucket MaximumRetention)`
Retention-Legal-Hold-ID	String	A single legal hold to apply to the object. A legal hold is a `Y` character long string. The object cannot be overwritten or deleted until all legal holds associated with the object are removed.
`x-amz-tagging`	String	This header supports up to 10 object tags, UTF-8 encoded in the format of key=value pairs delimited by "&".
`x-amz-checksum-crc32`	String	This header is the Base64 encoded, 32-bit CRC32 checksum of the object.
`x-amz-checksum-crc32c`	String	This header is the Base64 encoded, 32-bit CRC32C checksum of the object.
`x-amz-checksum-crc64nvme`	String	This header is the Base64 encoded, 64-bit CRC64NVME checksum of the object. The CRC64NVME checksum is always a full object checksum.
`x-amz-checksum-sha1`	String	This header is the Base64 encoded, 160-bit SHA1 digest of the object.
`x-amz-checksum-sha256`	String	This header is the Base64 encoded, 256-bit SHA256 digest of the object.
`x-amz-trailer`	String Possible value x-amz-checksum-crc32	Indicates which checksum value header will be found in the trailer of the payload in order to verify object upload integrity.

Content-MD5 or x-amz-checksum- HTTP header or AWS Signature Version 4 signed payload is required for upload requests with Object Lock parameters.

Specific headers for SSE-C

Common SSE-C headers are available for buckets using Server Side Encryption with Customer-Provided Keys (SSE-C) enabled.

Attention: SSE-C headers can be used to write or write objects from a protected bucket. However, it should be noted that SSE-C keys cannot be rotated for objects in a protected bucket.

Other headers

Upload an object with tagging by adding the x-amz-tagging header to an object upload request. For more information, see: Other headers.