Encryption & Decryption
Encryption & Decryption¶
The Amazon Yojaka product deals with a lot of sensitive customer-related data such as package shipping labels, customer invoices, customer addresses etc. It is imperative that all this be stored and transmitted in an encrypted format between different services. This page documents the encryption/decryption mechanisms that Amazon Yojaka supports.
AWS Key Management Service¶
Amazon Yojaka uses the AWS Key Management Service for management of keys that will be used for encryption/decryption of sensitive data. As part of the Registration process, an Amazon Yojaka seller would have received the ARN of an AWS KMS customer master key (CMK) that will be used to encrypt/decrypt all sensitive data pertaining to that seller. The seller must share that ARN with you, the connector developer.
The Amazon Yojaka team will ensure that the AWS IAM role provided to you during on-boarding has the appropriate permissions to encrypt/decrypt data using the customer master key assigned to the sellers who work with your connector.
Any sensitive data that you receive in an API response will encrypted so that it can only be decrypted using the AWS KMS customer master key assigned to the appropriate seller.
Tip
The AWS KMS customer master key will be owned by the Amazon Yojaka product and will be managed by Amazon. Your connector’s AWS IAM role will only have permissions to encrypt/decrypt data exchanged with Amazon Yojaka using that customer master key.
Sensitive Data¶
The following is a list of sensitive data that is provided to your connector by Amazon Yojaka. You will need to use the AWS KMS service to decrypt this data using the customer master key of the appropriate seller.
Invoices
Shipping labels
Gift messages
Product serial numbers
Note
Any API in which the response contains a field which indicates that it is encrypted data or contains encryption info will need to be decrypted by the connector before it can be used.
Example Data¶
Below is an example, in the JSON format, of how encrypted data is returned in an API response by the Amazon Yojaka APIs.
{
"value": "AYaDeDDLFxcUHj... <Base64 encoded string>",
"encryptionInfo": {
"context": "shipLabel",
"type": "AWS_KMS"
}
}
Encryption Information¶
AWS Encryption SDK¶
Use the AWS Encryption SDK library to simplify your code that needs to encrypt/decrypt sensitive data. This SDK works seamlessly with the AWS Key Management Service and is available in multiple programming languages.
Tip
Using the Encryption & Decryption utility class available in the Java SDK further simplifies the process of encryption and decryption while working with the Amazon Yojaka APIs.
Sample Code¶
Below is some sample code on how you can use the AWS Encryption SDK to decrypt data received as a response from an Amazon Yojaka API.
Java¶
import com.amazonaws.auth.AWSStaticCredentialsProvider;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.encryptionsdk.AwsCrypto;
import com.amazonaws.encryptionsdk.CryptoResult;
import com.amazonaws.encryptionsdk.kms.KmsMasterKey;
import com.amazonaws.encryptionsdk.kms.KmsMasterKeyProvider;
import java.util.Base64;
import java.util.Map;
...
private AwsCrypto awsCrypto = new AwsCrypto();
public byte[] decryptYojakaEncryptedData(String value, String encryptionInfoContext) {
KmsMasterKeyProvider kmsMasterKeyProvider =
KmsMasterKeyProvider.builder()
// Use the credentials of the AWS IAM user that you created during the Onboarding step
.withCredentials(new AWSStaticCredentialsProvider(
new BasicAWSCredentials("AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY")))
// The ARN of the KMS key to use will be provided to you by the seller once they complete
// registration with the Amazon Yojaka team
.withKeysForEncryption("arn:aws:kms:eu-west-1:123456789012:key/ABCD1234")
.build();
CryptoResult<byte[], KmsMasterKey> decryptedDataEnvelope =
awsCrypto.decryptData(kmsMasterKeyProvider, Base64.getDecoder().decode(value));
// Verify that the encryption context in the result contains the encryption context
// provided in the API response. The SDK can add values to the encryption context.
// And hence, do not do an exact match.
// The encryption context should contain 2 keys named "client" and "dataType".
// The value for the key "client" will always be the string "yojaka"
// The value for the key "dataType" will be the value you received in the API response
// as the context field in the "encryptionInfo"
Map<String, String> encryptionContextMap = decryptedDataEnvelope.getEncryptionContext();
if (!encryptionContextMap.containsKey("client")
|| !encryptionContextMap.get("client").equals("yojaka")) {
throw new IllegalStateException();
}
if (!encryptionContextMap.containsKey("dataType")
|| !encryptionContextMap.get("dataType").equals(encryptionInfoContext)) {
throw new IllegalStateException();
}
return decryptedDataEnvelope.getResult();
}
...
On this page
