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.
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 |
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:
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)
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
Method |
Description |
---|---|
putObject |
Uploads an object. |
getObject |
Downloads an object. |
Code Examples
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(); } } } |
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.