|
1 | 1 | # AWS Encryption SDK for Java |
2 | 2 |
|
3 | | -The AWS Encryption SDK is a client-side encryption library designed to make it easy for everyone to encrypt and decrypt data using industry standards and best practices. It enables you to focus on the core functionality of your application, rather than on how to best encrypt and decrypt your data. |
| 3 | +The AWS Encryption SDK enables secure client-side encryption. It uses cryptography best practices to protect your data and the encryption keys used to protect that data. Each data object is protected with a unique data encryption key (DEK), and the DEK is protected with a key encryption key (KEK) called a *master key*. The encrypted DEK is combined with the encrypted data into a single [encrypted message](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/message-format.html), so you don't need to keep track of the DEKs for your data. The SDK supports master keys in [AWS Key Management Service](https://aws.amazon.com/kms/) (KMS), and it also provides APIs to define and use other master key providers. The SDK provides methods for encrypting and decrypting strings, byte arrays, and byte streams. For details, see the [example code][examples] and the [Javadoc](https://aws.github.io/aws-encryption-sdk-java/javadoc/). |
4 | 4 |
|
5 | | -For details about the design, architecture and usage of the SDK, see the [official documentation](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/), [example code][examples] and the [Javadoc](https://aws.github.io/aws-encryption-sdk-java/javadoc/). |
| 5 | +For more details about the design and architecture of the SDK, see the [official documentation](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/). |
6 | 6 |
|
7 | 7 | [Security issue notifications](./CONTRIBUTING.md#security-issue-notifications) |
8 | 8 |
|
@@ -60,9 +60,75 @@ You can get the latest release from Maven: |
60 | 60 | </dependency> |
61 | 61 | ``` |
62 | 62 |
|
63 | | -### Sample Code |
| 63 | +### Get Started |
| 64 | + |
| 65 | +The following code sample demonstrates how to get started: |
| 66 | + |
| 67 | +1. Instantiate the SDK. |
| 68 | +2. Define the master key provider. |
| 69 | +3. Encrypt and decrypt data. |
| 70 | + |
| 71 | +```java |
| 72 | +// This sample code encrypts and then decrypts a string using a KMS CMK. |
| 73 | +// You provide the KMS key ARN and plaintext string as arguments. |
| 74 | +package com.amazonaws.crypto.examples; |
| 75 | + |
| 76 | +import java.util.Collections; |
| 77 | +import java.util.Map; |
| 78 | + |
| 79 | +import com.amazonaws.encryptionsdk.AwsCrypto; |
| 80 | +import com.amazonaws.encryptionsdk.CryptoResult; |
| 81 | +import com.amazonaws.encryptionsdk.kms.KmsMasterKey; |
| 82 | +import com.amazonaws.encryptionsdk.kms.KmsMasterKeyProvider; |
| 83 | + |
| 84 | +public class StringExample { |
| 85 | + private static String keyArn; |
| 86 | + private static String data; |
| 87 | + |
| 88 | + public static void main(final String[] args) { |
| 89 | + keyArn = args[0]; |
| 90 | + data = args[1]; |
| 91 | + |
| 92 | + // Instantiate the SDK |
| 93 | + final AwsCrypto crypto = new AwsCrypto(); |
| 94 | + |
| 95 | + // Set up the master key provider |
| 96 | + final KmsMasterKeyProvider prov = new KmsMasterKeyProvider(keyArn); |
| 97 | + |
| 98 | + // Encrypt the data |
| 99 | + // |
| 100 | + // NOTE: Encrypted data should have associated encryption context |
| 101 | + // to protect integrity. For this example, just use a placeholder |
| 102 | + // value. For more information about encryption context, see |
| 103 | + // https://amzn.to/1nSbe9X (blogs.aws.amazon.com) |
| 104 | + final Map<String, String> context = Collections.singletonMap("Example", "String"); |
| 105 | + |
| 106 | + final String ciphertext = crypto.encryptString(prov, data, context).getResult(); |
| 107 | + System.out.println("Ciphertext: " + ciphertext); |
| 108 | + |
| 109 | + // Decrypt the data |
| 110 | + final CryptoResult<String, KmsMasterKey> decryptResult = crypto.decryptString(prov, ciphertext); |
| 111 | + // Check the encryption context (and ideally the master key) to |
| 112 | + // ensure this is the expected ciphertext |
| 113 | + if (!decryptResult.getMasterKeyIds().get(0).equals(keyArn)) { |
| 114 | + throw new IllegalStateException("Wrong key id!"); |
| 115 | + } |
| 116 | + |
| 117 | + // The SDK may add information to the encryption context, so check to |
| 118 | + // ensure all of the values are present |
| 119 | + for (final Map.Entry<String, String> e : context.entrySet()) { |
| 120 | + if (!e.getValue().equals(decryptResult.getEncryptionContext().get(e.getKey()))) { |
| 121 | + throw new IllegalStateException("Wrong Encryption Context!"); |
| 122 | + } |
| 123 | + } |
| 124 | + |
| 125 | + // The data is correct, so output it. |
| 126 | + System.out.println("Decrypted: " + decryptResult.getResult()); |
| 127 | + } |
| 128 | +} |
| 129 | +``` |
64 | 130 |
|
65 | | -You can find sample code in the [examples directory][examples]. |
| 131 | +You can find more examples in the [examples directory][examples]. |
66 | 132 |
|
67 | 133 | ## Public API |
68 | 134 |
|
|
0 commit comments