"Do you want client-side encryption for your software but don’t know where to start? In this hands-on workshop, we cover the basics of client-side encryption, perform encrypt and decrypt operations using AWS Key Management Service (KMS) and the AWS Encryption SDK, and discuss security and performance considerations when implementing client-side encryption in your software. This workshop covers the basic challenges of this domain; a best practice for protecting data end-to-end with client-side encryption; KMS-style services and their uses, including AWS KMS; the open-source, open-format AWS Encryption SDK; and considerations for advanced integrations, such as performance tradeoffs and high-availability strategies.

1. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Using the AWS Encryption SDK for
multiple master key encryption
Jamie Angell
Sr. Manager, Software
Development
AWS Cryptography
Amazon Web Services
S D D 4 0 2
Ryan Emery
Senior Software Engineer
AWS Cryptography
Amazon Web Services
Liz Roth
Senior Software Engineer
Amazon Web Services

2. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Agenda
Quick primer on encryption
Quick primer on AWS Key Management Service (AWS KMS)
Intro to the AWS Encryption SDK
Adding encryption to an application
Implementing data key caching in your application

3. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.

4. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Basic definitions
Plaintext CiphertextData Key
Encryption
Algorithm

5. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Encryption
Encryption Algorithm
Plaintext
Ciphertext
Data Key

6. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Decryption
Plaintext
Ciphertext
Data Key
Decryption Algorithm

7. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Don’t roll your own crypto

8. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Keys
Small
High value
Easily exfiltrated
Require additional protection

9. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.

10. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
AWS Key Management Service
Traditional web service with web APIs
integrated with other Amazon Web
Services (AWS) services
Backed by hardware security modules
(HSMs)
Non-exportable keys called customer
master keys (CMKs)
KMS
KMSFleet HSMs
CMKARNs

11. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
AWS KMS
KMS
GenerateDataKey
Data
Key
Encrypted
Data Key
HSMs
CMK

12. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
KMS access control
KMSGenerateDataKey
CMK
Access Denied
GenerateDataKey
CloudTrail Log
CloudTrail Log AWSCloudTrail
Key Policies
Granting Access
Key Policies
Preventing Access

13. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Encrypting with AWS KMS
Encrypt API
{
"KeyId": "string",
"EncryptionContext":
{ "string" : "string" },
"Plaintext": blob
}
Result
{
"KeyId": "string"
"CiphertextBlob": blob,
}
If the ciphertext blob or the encryption context is changed,
requests to decrypt the data will fail

14. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Decrypting with AWS KMS
Decrypt API
{
"EncryptionContext":
{ "string" : "string" },
"CiphertextBlob": blob
}
Result
{
"KeyId": "string"
"Plaintext": blob,
}
If the ciphertext blob or the encryption context is changed,
requests to decrypt the data will fail

15. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Non-secret, plaintext additional information
Should be relevant to the data
Included in CloudTrail logs in plaintext
Can be used as conditions in IAM policies, key
policies, and grants
Examples:
Document type, security classification,
customer ID, date stamps, order IDs, etc.
Balance plaintext disclosure with audit/access
control detail
{
"awsRegion": "us-east-2",
"eventName": "Decrypt",
"eventSource": "kms.amazonaws.com",
"eventTime": "2017-09-15T19:35:54Z",
"requestParameters": {
"encryptionContext": {
"TenantID": ”123AID",
"OrderDate": "2018-09-01",
"OrderID": "123-4567890-011",
"Type": "Invoice"
}
},
// ...
}
Encryption context
Encryption
Context

16. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Encryption context – Why it matters
good.txt bad.txt
good.txt
bad.txt
bad.txt
good.txt
Decryption succeeds ☺
Decryption succeeds 

17. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Encryption context – Why it matters
good.txt bad.txt
good.txt
bad.txt
bad.txt
good.txt
good.txt
NAME=“GOOD.TXT”
bad.txt
NAME=“BAD.TXT”
bad.txt
good.txt
NAME=“BAD.TXT”
good.txt
bad.txt
NAME=“GOOD.TXT”
Decryption succeeds ☺
Decryption succeeds 
Decryption succeeds ☺
Decryption fails ☺

18. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
AWS KMS direct-encrypt considerations
Plaintext message is limited to 4,096 bytes
Plaintext is sent to AWS KMS (over TLS) before being encrypted by the AWS
KMS HSMs
You must call AWS KMS for every encrypt and
decrypt operation

19. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Envelope Encryption With KMS
Have KMS generate a limited-scope data key
Encrypt the data key using AWS KMS or an HSM
Encrypt the plaintext using the data key
Store or transmit the encrypted data key
and the ciphertext

20. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Encrypted
data key
Encrypted
data
Plaintext data
Encrypted message
Key encryption key
(CMK)
Data key Encryption
algorithm
Encryption
algorithm
Envelope encryption

21. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Benefits of envelope encryption
Scales with the number of messages you encrypt
Can encrypt very large messages
Efficiently encrypts a message that can be decrypted by multiple recipients
Data key can be cached and used across multiple messages
Reduces calls to AWS KMS
Reduces latency

22. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Complexities of envelope encryption
Several moving parts to build
Carefully select algorithms in use
Make sure you get everything right
Don’t reuse IVs
Generate keys correctly
Keep track of encryption context
Design a data format to store required parameters

23. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.

24. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
The AWS Encryption SDK
• Framework and data format for client-side encryption
• Library that gives you authenticated envelope encryption
• Backed by AWS KMS or external key sources
• Implementations available for Java, Python, and C
• Specification is available if you want to implement in a different
language
• Supports data-key caching
• Open source under Apache 2.0 license
• Built on language-specific crypto primitives

25. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Data format
• Bundles all the information needed to perform the decryption except the
backing key
• Includes the plaintext encryption context
• Includes information that validates integrity of
the ciphertext and encryption context
AWSEncryptionSDK
messageformat

26. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Why is this useful?
Makes it easy to use AWS KMS
It does the hard stuff, so you can focus on your application
Available as an open-source library
Available in Java, Python, C, and CLI—all interoperable
Documented message format

27. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Master keys and master key providers
Master keys
Control access to data
Correspond to AWS KMS CMKs
Master key providers
Decide which master keys to use
In general
Use AWS KMS
You can integrate with other key material sources

28. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Support for data-key caching
Security/performance trade-off
Missing key use detail in audit logs
Need identical encryption contexts and keys
Greater potential impact if a key is
ever compromised

29. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Encrypting with the AWS Encryption SDK
AWSKMS
Encrypted data
Customermaster key(CMK)
AWSEncryptionSDK
Encrypteddatakey
GenerateDataKey
EncryptioncontextPlaintextdata
Encryptedmessage
Datakey
CMK ARN
Encryption
algorithm
AWSEncryptionSDK
messageformat

30. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Encrypting with multiple master keys
CMKus-east-1
AWSEncryptionSDKGenerateDataKey
Datakey
CMKeu-west-1
Encrypteddatakeyeu-west-1
Encrypteddatakeyus-
east-1
Encrypt
EncryptioncontextPlaintext data
Encrypted data
Encryptedmessage
Encryption
algorithm
AWSEncryptionSDK
messageformat
CMKARN eu-west-1 CMKARN us-east-1
KMS us-east-1
KMS eu-west -1

31. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Decrypting in us-east-1
AWSEncryptionSDK
Datakey
Encryptioncontext
Plaintext data
Encrypted data
Encryptedmessage
Datakey
Decrypt
Decryptionalgorithm
AWSEncryptionSDK
messageformat
CMKus-east-1
Encrypteddatakeyus-east-1
CMKARN us-east-1
KMS us-east-1

32. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Decrypting in eu-west-1
Datakey
Encryptioncontext
Plaintext data
Encrypted data
Encryptedmessage
Datakey
Decrypt
Decryptionalgorithm
AWSEncryptionSDK
messageformat
CMKARN eu-west-1
CMKeu-west-1
Encrypteddatakeyeu-west-1
AWSEncryptionSDK
KMS eu-west -1

33. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
public static void main(String[] args) {
KmsMasterKeyProvider mkp = new KmsMasterKeyProvider("alias/myExampleKey");
byte[] myData = "Hello World!".getBytes(StandardCharsets.UTF_8);
Map<String, String> encryptionContext = new Map<String, String>;
encryptionContext.put("data_type", "example");
encryptionContext.put("classification", "public");
byte[] ciphertext = new AwsCrypto()
.encryptData(mkp, myData, encryptionContext).getResult();
byte[] plaintext = new AwsCrypto()
.decryptData(mkp, ciphertext).getResult();
System.out.println(new String(myData, StandardCharsets.UTF_8));
}
The AWS Encryption SDK (Java)

34. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
def encrypt_this():
plaintext = "Hello World!"
mkp = KMSMasterKeyProvider(
key_ids=["alias/myExampleKey"]
)
encryption_context = {
"data_type": "example",
"classification": "public",
}
ciphertext, encryptor_header = aws_encryption_sdk.encrypt(
source=plaintext,
key_provider=mkp,
encryption_context=encryption_context,
)
decrypted_plaintext, decryptor_header = aws_encryption_sdk.decrypt(
source=ciphertext,
key_provider=mkp,
)
print(decrypted_plaintext.decode("utf-8"))
The AWS Encryption SDK (Python)

35. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
echo "Hello World!" > plaintext
aws-encryption-cli
--encrypt
--master-keys
provider=aws-kms
key=alias/myExampleKey
--encryption-context
"data_type=example"
"classification=public"
--metadata-output -
--input plaintext
--output ciphertext
aws-encryption-cli
--decrypt
--metadata-output -
--input ciphertext
--output decrypted-plaintext
cat decrypted-plaintext
The AWS Encryption SDK (CLI)

36. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.

37. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Set up the demo application
Activity
busy-engineers-guide.reinvent-workshop.com
Environment setup

38. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.

39. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Explore and add Base64 encoding to your application
Activity
busy-engineers-guide.reinvent-workshop.com
Exercise 1: Explore

40. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.

41. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Encrypt directly with AWS KMS
Activity
busy-engineers-guide.reinvent-workshop.com
Exercise 2: Introducing KMS

42. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.

43. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Using the AWS Encryption SDK
Activity
busy-engineers-guide.reinvent-workshop.com
Exercise 3: The AWS Encryption SDK

44. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.

45. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Add data key caching to your application
Activity
busy-engineers-guide.reinvent-workshop.com
Exercise 4: Data Key Caching

46. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.

47. © 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Add data key caching to your application
Activity
busy-engineers-guide.reinvent-workshop.com
Exercise 5: Using Multiple CMKs

48. Thank you!
© 2019,Amazon Web Services, Inc. or its affiliates. All rights reserved.
Thank you!
Jamie Angell
Sr. Manager, Software
Development
AWS Cryptography
Amazon Web Services
Ryan Emery
Senior Software Engineer
AWS Cryptography
Amazon Web Services
Liz Roth
Senior Software Engineer
Amazon Web Services