Updated on 2024-03-26 GMT+08:00

Client-Side Encryption (SDK for Python)

Initializing CryptoCipher

The OBS SDK for Python offers two types of CryptoCipher. Choose the one right for you.

CtrRSACipherGenerator needs an RSA public or private key to encrypt the randomly generated data key.

Method

CtrRSACipherGenerator(master_crypto_key_path, master_key_info=None, need_sha256=False)

API Parameters

Table 1 CtrRSACipherGenerator

Parameter

Type

Mandatory (Yes/No)

Description

master_crypto_key_path

str

Yes

Explanation:

Path where the RSA key file is stored

Default value:

None

master_key_info

str

No

Explanation:

Key information, which is stored in the custom metadata of objects to help you distinguish different data keys. You need to maintain the mapping between master_key_info and crypto_key.

Default value:

None

need_sha256

bool

No

Explanation:

Whether to verify the SHA-256 value of the encrypted data and to add SHA-256 values calculated before and after the encryption to the custom metadata

NOTE:

To reduce memory overheads, the SDK uses streaming computing, which means that a file needs to be read and encrypted twice in a common upload and three times in a resumable upload.

Value range:

True: The SHA-256 value of the encrypted data is verified. The SDK automatically calculates SHA-256 before and after the object is encrypted and saves the two values to the custom metadata of the object. In addition, the SDK adds the SHA-256 value of the encrypted object to the request header when sending a request to the server. After receiving the request, the server calculates the SHA-256 value of the object and checks the consistency between the calculated and the received values. If they are inconsistent, an error message is returned.

False: The SHA-256 value of the encrypted data is not verified.

Default value:

False

CTRCipherGenerator requires only a data key. This key is used to encrypt all objects.

Method

CTRCipherGenerator(crypto_key, master_key_info=None, crypto_iv=None, need_sha256=False)

API Parameters

Table 2 CTRCipherGenerator

Parameter

Type

Mandatory (Yes/No)

Description

crypto_key

str or bytes

Yes

Explanation:

Data key used for encrypting data

Restrictions:

  • Length: 32 bytes
  • If a character string is passed, it is converted to bytes.

Default value:

None

master_key_info

str

No

Explanation:

Key information, which is stored in the custom metadata of objects to help you distinguish different data keys. You need to maintain the mapping between master_key_info and crypto_key.

Default value:

None

crypto_iv

str or bytes

No

Explanation:

Initial value used for encrypting data

Restrictions:

  • Length: 16 bytes
  • If crypto_iv is specified, all objects are encrypted using the specified initial value. If crypto_iv is not specified, the SDK randomly generates an initial value for each object.

Default value:

None

need_sha256

bool

No

Explanation:

Whether to verify the SHA-256 value of the encrypted data and to add SHA-256 values calculated before and after the encryption to the custom metadata

NOTE:

To reduce memory overheads, the SDK uses streaming computing, which means that a file needs to be read and encrypted twice during a common upload, but in a resumable upload, a file needs to be read and encrypted three times.

Value range:

True: The SHA-256 value of the encrypted data is verified. The SDK automatically calculates SHA-256 before and after the object is encrypted and saves the two values to the custom metadata of the object. In addition, the SDK adds the SHA-256 value of the encrypted object to the request header when sending a request to the server. After receiving the request, the server calculates the SHA-256 value of the object and checks the consistency between the calculated and the received values. If they are inconsistent, an error message is returned.

False: The SHA-256 value of the encrypted data is not verified.

Default value:

False

Initializing CryptoClient

Initializing CryptoClient is inherited from initializing an ObsClient. For details, see Initializing an Instance of ObsClient (SDK for Python).

Method

CryptoClient(access_key_id,secret_access_key,server,cipher_generator=your-cipher_generator, *args, **kwargs)

API Parameters

Table 3 List of request parameters

Parameter

Description

Recommended Value

access_key_id

Explanation:

Access key ID (AK)

Default value:

An empty string, indicating an anonymous user

N/A

secret_access_key

Explanation:

Secret access key (SK)

Default value:

An empty string, indicating an anonymous user

N/A

server

Explanation:

Server address for accessing OBS. It consists of a protocol type, domain name, and port number, for example, https://your-endpoint:443. For security purposes, you are advised to use HTTPS.

Default value:

None

N/A

cipher_generator

Explanation:

Cipher generator used by a client

Value range:

Default value:

None

N/A

Initiating an Encrypted Multipart Upload

Initiating an encrypted multipart upload is inherited from the ObsClient API for initiating a multipart upload. For details, see Initiating a Multipart Upload (SDK for Python).

Method

CryptoClient.initiateEncryptedMultipartUpload(bucketName, objectKey, crypto_cipher, *args, **kwargs)

API Parameters

Table 4 List of request parameters

Parameter

Type

Mandatory (Yes/No)

Description

bucketName

str

Yes

Explanation:

Bucket name

Restrictions:

  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain periods (.) and hyphens (-) adjacent to each other, for example, my-.bucket or my.-bucket.
  • If you repeatedly create buckets of the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.

Default value:

None

objectKey

str

Yes

Explanation:

Object name. An object is uniquely identified by an object name in a bucket. An object name is a complete path that does not contain the bucket name.

For example, if the address for accessing the object is examplebucket.obs.eu-west-101.myhuaweicloud.eu/folder/test.txt, the object name is folder/test.txt.

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

NOTE:

The object URL is in the following format: https://Bucket name.Domain name/Folder directory level/Object name. If this object is stored in the root directory of the bucket, its URL does not contain the folder directory level.

crypto_cipher

OBSCipher

Yes

Explanation:

OBS cipher generated by calling cipher_generator.new(). Configure this parameter into the metadata during task initiation.

Value range:

A value generated by calling cipher_generator.new(). cipher_generator is the cipher_generator parameter set for CryptoClient initialization.

Example: cipher = ctr_client.cipher_generator.new(""). ctr_client is the encryption client.

Default value:

None

Uploading an Encrypted Part

Uploading encrypted parts is inherited from the ObsClient API for uploading parts. For details, see Uploading a Part (SDK for Python).

Method

CryptoClient.initiateEncryptedMultipartUpload(bucketName, objectKey, partNumber, uploadId, crypto_cipher, *args, **kwargs)

API Parameters

Table 5 List of request parameters

Parameter

Type

Mandatory (Yes/No)

Description

bucketName

str

Yes

Explanation:

Bucket name

Restrictions:

  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain periods (.) and hyphens (-) adjacent to each other, for example, my-.bucket or my.-bucket.
  • If you repeatedly create buckets of the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.

Default value:

None

objectKey

str

Yes

Explanation:

Object name. An object is uniquely identified by an object name in a bucket. An object name is a complete path that does not contain the bucket name.

For example, if the address for accessing the object is examplebucket.obs.eu-west-101.myhuaweicloud.eu/folder/test.txt, the object name is folder/test.txt.

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

NOTE:

The object URL is in the following format: https://Bucket name.Domain name/Folder directory level/Object name. If this object is stored in the root directory of the bucket, its URL does not contain the folder directory level.

partNumber

int

Yes

Explanation:

Part number

Value range:

[1,10000]

Default value:

None

uploadId

str

Yes

Explanation:

Multipart upload ID, which can be returned by initiating a multipart upload, for example, 000001648453845DBB78F2340DD460D8

Restrictions:

The value must contain 32 characters.

Default value:

None

crypto_cipher

OBSCipher

Yes

Explanation:

OBS cipher generated by calling cipher_generator.new()

Value range:

A value generated by calling cipher_generator.new(). cipher_generator is the cipher_generator parameter set for CryptoClient initialization.

Example: cipher = ctr_client.cipher_generator.new(""). ctr_client is the encryption client.

Default value:

None

Helpful Links