Updated on 2024-06-18 GMT+08:00

Client-Side Encryption APIs (SDK for Java)

Initializing CryptoCipher

OBS SDK for Java provides two cipher suites for you to choose from.

CtrRSACipherGenerator is inherited from CTRCipherGenerator but only requires you to provide an RSA public or private key to encrypt or decrypt the randomly generated data key.

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

Table 1 CtrRSACipherGenerator parameters

Parameter

Type

Mandatory (Yes/No)

Description

privateKey

PrivateKey

Yes when decrypting objects (for example, getObject)

Explanation:

RSA private key.

Default value:

None

publicKey

PublicKey

Yes for encryption (for example, putObject)

Explanation:

RSA public key.

Default value:

None

masterKeyInfo

String

No

Explanation:

Key information, which is stored in the user-defined metadata of objects to help you identify keys. You need to maintain the mappings between keys and masterKeyInfo on your own.

Default value:

None

secureRandom

SecureRandom

Yes

Explanation:

Secure random number generator, which is used to randomly generate cryptoKeyBytes and cryptoIvBytes.

Default value:

None

needSha256

boolean

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 user-defined 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:

If need_sha256 is set to true, the SDK automatically calculates SHA-256 before and after the object is encrypted and saves the two values to the user-defined 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

Table 2 CTRCipherGenerator parameters

Parameter

Type

Mandatory (Yes/No)

Description

masterKeyInfo

String

No

Explanation:

Key information, which is stored in the user-defined metadata of objects to help you identify cryptoKeyBytes. You need to maintain the mappings between cryptoKeyBytes and masterKeyInfo on your own.

Default value:

None

cryptoKeyBytes

byte[]

Yes

Explanation:

Data key used for encrypting data.

Restrictions:

The value must be 32 bytes long.

Default value:

None

cryptoIvBytes

byte[]

No

Explanation:

Initial value used for encrypting data.

Restrictions:

  • The value must be 16 bytes long.
  • If this parameter is specified, all objects are encrypted using the specified initial value. If this parameter is not specified, the SDK randomly generates an initial value for each object.

Default value:

None

secureRandom

SecureRandom

Yes

Explanation:

Secure random number generator, for use when either cryptoKeyBytes or cryptoIvBytes is missing.

Default value:

None

needSha256

boolean

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 user-defined 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:

If need_sha256 is set to true, the SDK automatically calculates SHA-256 before and after the object is encrypted and saves the two values to the user-defined 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 CryptoObsClient

CryptoObsClient is inherited from ObsClient. For its configuration details, see Creating and Configuring an OBS Client (SDK for Java).

Method

CryptoObsClient(String accessKey, String secretKey, String endPoint, CTRCipherGenerator ctrCipherGenerator)

Table 3 Parameters for initializing CryptoObsClient

Parameter

Description

Recommended Value

accessKey

Explanation:

Access key ID (AK).

Default value:

An empty string, indicating an anonymous user.

N/A

secretKey

Explanation:

Secret access key (SK).

Default value:

An empty string, indicating an anonymous user.

N/A

endPoint

Explanation:

OBS server address. 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

ctrCipherGenerator

Explanation:

Cipher suite used by the client.

Value range:

Default value:

None

N/A

APIs That Support Client-Side Encryption

Table 4 APIs that support client-side encryption

Method

Description

putObject

Uploads an object.

getObject

Downloads an object.

Code Examples

CtrRSACipherGenerator:
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
import com.obs.services.ObsConfiguration;
import com.obs.services.crypto.CTRCipherGenerator;
import com.obs.services.crypto.CryptoObsClient;
import com.obs.services.crypto.CtrRSACipherGenerator;
import com.obs.services.exception.ObsException;
import com.obs.services.model.GetObjectRequest;
import com.obs.services.model.ObsObject;
import com.obs.services.model.PutObjectResult;

import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.security.NoSuchAlgorithmException;
import java.security.PrivateKey;
import java.security.PublicKey;
import java.security.spec.InvalidKeySpecException;

public class CtrRSACipherGeneratorDemo001 {
    public static void main(String[] args) {
        // Obtain an AK/SK pair using environment variables or import the AK/SK pair in other ways. Using hard coding may result in leakage.
        // Obtain an AK/SK pair on the management console.
        String ak = System.getenv("ACCESS_KEY_ID");
        String sk = System.getenv("SECRET_ACCESS_KEY_ID");
        // (Optional) If you are using a temporary AK/SK pair and a security token to access OBS, you are advised not to use hard coding, which may result in information leakage.
        // Obtain an AK/SK pair and a security token using environment variables or import them in other ways.
        // String securityToken = System.getenv("SECURITY_TOKEN");
        // Enter the endpoint corresponding to the bucket. EU-Dublin is used here as an example. Replace it with the one currently in use.
        String endPoint = "https://obs.eu-west-101.myhuaweicloud.eu"; 
        // Obtain an endpoint using environment variables or import it in other ways.
        //String endPoint = System.getenv("ENDPOINT");
        CtrRSACipherGenerator ctrRSACipherGenerator = null;
        try {
            String examplePrivateKeyPath = "yourRSAPrivateKeyPath";
            String examplePublicKeyPath = "yourRSAPublicKeyPath";
            ObsConfiguration config = new ObsConfiguration();
            PrivateKey privateKeyObj = CtrRSACipherGenerator.importPKCS8PrivateKey(examplePrivateKeyPath);
            PublicKey publicKeyObj = CtrRSACipherGenerator.importPublicKey(examplePublicKeyPath);
            ctrRSACipherGenerator =
                    new CtrRSACipherGenerator(
                            "example_master_key_info", true, config.getSecureRandom(), privateKeyObj, publicKeyObj);

        } catch (IllegalArgumentException | IOException | NoSuchAlgorithmException | InvalidKeySpecException e) {
            e.printStackTrace();
        }
        assert ctrRSACipherGenerator != null;
        // Create an ObsClient instance.
        try (CryptoObsClient cryptoObsClient = new CryptoObsClient(ak, sk, securityToken, endPoint, ctrRSACipherGenerator)) {
            String exampleBucketName = "example-bucket";
            String exampleObjectKey = "exampleObjectKey";
            String examplePlainTextFilePath = "examplePlainTextFilePath";
            String exampleDecryptedFilePath = "exampleDecryptedFilePath";
            PutObjectResult putObjectResult =
                    cryptoObsClient.putObject(exampleBucketName, exampleObjectKey, new File(examplePlainTextFilePath));
            System.out.println("HTTP Code: " + putObjectResult.getStatusCode());
            System.out.println("Etag: " + putObjectResult.getEtag());
            // The object is successfully encrypted on the client and then uploaded.
            System.out.println("CtrRSACipherGeneratorDemo001 putObject successfully");

            GetObjectRequest getObjectRequest = new GetObjectRequest(exampleBucketName, exampleObjectKey);
            ObsObject obsObject = cryptoObsClient.getObject(getObjectRequest);
            InputStream input = obsObject.getObjectContent();
            byte[] b = new byte[1024];
            FileOutputStream fileOutputStream = new FileOutputStream(exampleDecryptedFilePath);
            int len;
            while ((len = input.read(b)) != -1) {
                fileOutputStream.write(b, 0, len);
            }
            fileOutputStream.close();
            input.close();

            System.out.println("HTTP Code: " + obsObject.getMetadata().getStatusCode());
            // The object is successfully decrypted on the client and then downloaded.
            System.out.println("CtrRSACipherGeneratorDemo001 getObject successfully");

            // Check whether the file remains the same before encryption and after decryption.
            byte[] plainTextFileSha256 = CTRCipherGenerator.getFileSha256Bytes(examplePlainTextFilePath);
            byte[] decryptedFileSha256 = CTRCipherGenerator.getFileSha256Bytes(exampleDecryptedFilePath);
            String plainTextFileSha256Base64Encoded = CTRCipherGenerator.getBase64Info(plainTextFileSha256);
            String decryptedFileSha256Base64Encoded = CTRCipherGenerator.getBase64Info(decryptedFileSha256);
            System.out.println("plainTextFileSha256 base64 encoded: " + plainTextFileSha256Base64Encoded);
            System.out.println("decryptedFileSha256 base64 encoded: " + decryptedFileSha256Base64Encoded);
            System.out.println(
                    "plainTextFileSha256 equals decryptedFileSha256 ? "
                            + decryptedFileSha256Base64Encoded.equals(plainTextFileSha256Base64Encoded));
            System.out.println("CtrRSACipherGeneratorDemo001 successfully");
        } catch (ObsException e) {
            System.out.println("CtrRSACipherGeneratorDemo001 failed");
            // Request failed. Print the HTTP status code.
            System.out.println("HTTP Code: " + e.getResponseCode());
            // Request failed. Print the server-side error code.
            System.out.println("Error Code:" + e.getErrorCode());
            // Request failed. Print the error details.
            System.out.println("Error Message: " + e.getErrorMessage());
            // Request failed. Print the request ID.
            System.out.println("Request ID:" + e.getErrorRequestId());
            System.out.println("Host ID:" + e.getErrorHostId());
        } catch (Exception e) {
            System.out.println("CtrRSACipherGeneratorDemo001 putObject failed");
            // Print other error details.
            e.printStackTrace();
        }
    }
}

CTRCipherGenerator:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
import com.obs.services.crypto.CTRCipherGenerator;
import com.obs.services.crypto.CryptoObsClient;
import com.obs.services.exception.ObsException;
import com.obs.services.model.GetObjectRequest;
import com.obs.services.model.ObsObject;
import com.obs.services.model.PutObjectResult;

import java.io.File;
import java.io.FileOutputStream;
import java.io.InputStream;
import java.security.NoSuchAlgorithmException;
import java.security.SecureRandom;

public class CTRCipherGeneratorDemo001 {
    public static void main(String[] args) {
        // Obtain an AK/SK pair using environment variables or import the AK/SK pair in other ways. Using hard coding may result in leakage.
        // Obtain an AK/SK pair on the management console.
        String ak = System.getenv("ACCESS_KEY_ID");
        String sk = System.getenv("SECRET_ACCESS_KEY_ID");
        // (Optional) If you are using a temporary AK/SK pair and a security token to access OBS, you are advised not to use hard coding, which may result in information leakage.
        // Obtain an AK/SK pair and a security token using environment variables or import them in other ways.
        // String securityToken = System.getenv("SECURITY_TOKEN");
        // Enter the endpoint corresponding to the bucket. EU-Dublin is used here as an example. Replace it with the one currently in use.
        String endPoint = "https://obs.eu-west-101.myhuaweicloud.eu"; 
        // Obtain an endpoint using environment variables or import it in other ways.
        //String endPoint = System.getenv("ENDPOINT");
          CTRCipherGenerator ctrCipherGenerator = null;
        try {
            SecureRandom secureRandom = SecureRandom.getInstanceStrong();
            // Note that in Linux, using SecureRandom.getInstanceStrong() may block the thread in case of insufficient system entropy. In this case, you are advised to either use entropy addition methods or set SecureRandom in another way.
            byte[] exampleMasterKey = new byte[CTRCipherGenerator.CRYPTO_KEY_BYTES_LEN];
            secureRandom.nextBytes(exampleMasterKey);
            // Replace exampleMasterKey with the one you actually use. Make sure the key is 32 bytes and keep it properly.
            ctrCipherGenerator =
                    new CTRCipherGenerator("example_master_key_info", exampleMasterKey, true, secureRandom);
        } catch (IllegalArgumentException | NoSuchAlgorithmException e) {
            e.printStackTrace();
        }
        assert ctrCipherGenerator != null;
        // Create an ObsClient instance.
        try (CryptoObsClient cryptoObsClient =
                new CryptoObsClient(ak, sk, securityToken, endPoint, ctrCipherGenerator)) {
            String exampleBucketName = "example-bucket";
            String exampleObjectKey = "exampleObjectKey";
            String examplePlainTextFilePath = "examplePlainTextFilePath";
            String exampleDecryptedFilePath = "exampleDecryptedFilePath";
            PutObjectResult putObjectResult =
                    cryptoObsClient.putObject(exampleBucketName, exampleObjectKey, new File(examplePlainTextFilePath));
            System.out.println("HTTP Code: " + putObjectResult.getStatusCode());
            System.out.println("Etag: " + putObjectResult.getEtag());
            // The object is successfully encrypted on the client and then uploaded.
            System.out.println("CTRCipherGeneratorDemo001 putObject successfully");

            GetObjectRequest getObjectRequest = new GetObjectRequest(exampleBucketName, exampleObjectKey);
            ObsObject obsObject = cryptoObsClient.getObject(getObjectRequest);
            InputStream input = obsObject.getObjectContent();
            byte[] b = new byte[1024];
            FileOutputStream fileOutputStream = new FileOutputStream(exampleDecryptedFilePath);
            int len;
            while ((len = input.read(b)) != -1) {
                fileOutputStream.write(b, 0, len);
            }
            fileOutputStream.close();
            input.close();

            System.out.println("HTTP Code: " + obsObject.getMetadata().getStatusCode());
            // The object is successfully decrypted on the client and then downloaded.
            System.out.println("CTRCipherGeneratorDemo001 getObject successfully");
            
            // Check whether the file remains the same before encryption and after decryption.
            byte[] plainTextFileSha256 = CTRCipherGenerator.getFileSha256Bytes(examplePlainTextFilePath);
            byte[] decryptedFileSha256 = CTRCipherGenerator.getFileSha256Bytes(exampleDecryptedFilePath);
            String plainTextFileSha256Base64Encoded = CTRCipherGenerator.getBase64Info(plainTextFileSha256);
            String decryptedFileSha256Base64Encoded = CTRCipherGenerator.getBase64Info(decryptedFileSha256);
            System.out.println("plainTextFileSha256 base64 encoded: " + plainTextFileSha256Base64Encoded);
            System.out.println("decryptedFileSha256 base64 encoded: " + decryptedFileSha256Base64Encoded);
            System.out.println(
                    "plainTextFileSha256 equals decryptedFileSha256 ? "
                            + decryptedFileSha256Base64Encoded.equals(plainTextFileSha256Base64Encoded));
            System.out.println("CTRCipherGeneratorDemo001 successfully");
        } catch (ObsException e) {
            System.out.println("CTRCipherGeneratorDemo001 failed");
            // Request failed. Print the HTTP status code.
            System.out.println("HTTP Code: " + e.getResponseCode());
            // Request failed. Print the server-side error code.
            System.out.println("Error Code:" + e.getErrorCode());
            // Request failed. Print the error details.
            System.out.println("Error Message: " + e.getErrorMessage());
            // Request failed. Print the request ID.
            System.out.println("Request ID:" + e.getErrorRequestId());
            System.out.println("Host ID:" + e.getErrorHostId());
        } catch (Exception e) {
            System.out.println("CTRCipherGeneratorDemo001 putObject failed");
            // Print other error details.
            e.printStackTrace();
        }
    }
}