Updated wording and copyright notice

Author: WesleyRosenblum

src/examples/README.md

@@ -21,7 +21,31 @@ you need to describe how you want the library to protect your data keys.
 You can do this using
 [keyrings](#keyrings) or [cryptographic materials managers](#cryptographic-materials-managers),
 or using [master key providers](#master-key-providers).
-These examples will show you how.
+These examples will show you how yo use the configuration tools that we include for you 
+as well as how to create some of your own. We start with AWS KMS examples, then show 
+how to use other wrapping keys.
+
+* Using AWS Key Management Service (AWS KMS)
+    * How to use a single AWS KMS CMK
+        * [with keyrings](./java/com/amazonaws/crypto/examples/keyring/awskms/SingleCmk.java)
+    * How to use multiple AWS KMS CMKs in different regions
+        * [with keyrings](./java/com/amazonaws/crypto/examples/keyring/awskms/MultipleRegions.java)
+    * How to decrypt when you don't know the CMK
+        * [with keyrings](./java/com/amazonaws/crypto/examples/keyring/awskms/DiscoveryDecrypt.java)
+    * How to decrypt within a region
+        * [with keyrings](./java/com/amazonaws/crypto/examples/keyring/awskms/DiscoveryDecryptInRegionOnly.java)
+    * How to decrypt with a preferred region but failover to others
+        * [with keyrings](./java/com/amazonaws/crypto/examples/keyring/awskms/DiscoveryDecryptWithPreferredRegions.java)
+* Using raw wrapping keys
+    * How to use a raw AES wrapping key
+        * [with keyrings](./java/com/amazonaws/crypto/examples/keyring/rawaes/RawAes.java)
+    * How to use a raw RSA wrapping key
+        * [with keyrings](./java/com/amazonaws/crypto/examples/keyring/rawrsa/RawRsa.java)
+    * How to encrypt with a raw RSA public key wrapping key without access to the private key
+        * [with keyrings](./java/com/amazonaws/crypto/examples/keyring/rawrsa/PublicPrivateKeySeparate.java)
+* Combining wrapping keys
+    * How to combine AWS KMS with an offline escrow key
+        * [with keyrings](./java/com/amazonaws/crypto/examples/keyring/multi/AwsKmsWithEscrow.java)
 
 ### Keyrings
 

src/examples/java/com/amazonaws/crypto/examples/FileStreamingDefaults.java

@@ -1,15 +1,5 @@
-/*
- * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
- *
- * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except
- * in compliance with the License. A copy of the License is located at
- *
- * http://aws.amazon.com/apache2.0
- *
- * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations under the License.
- */
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
 
 package com.amazonaws.crypto.examples;
 
@@ -53,7 +43,7 @@ public class FileStreamingDefaults {
      * @param sourcePlaintextFile Plaintext file to encrypt
      */
     public static void run(final AwsKmsCmkId awsKmsCmk, final File sourcePlaintextFile) throws IOException {
-        // Instantiate the SDK
+        // Instantiate the AWS Encryption SDK
         final AwsCrypto awsEncryptionSdk = new AwsCrypto();
 
         // We assume that you can also write to the directory containing the plaintext file,
@@ -63,7 +53,7 @@ public static void run(final AwsKmsCmkId awsKmsCmk, final File sourcePlaintextFi
         encryptedFile.deleteOnExit();
         decryptedFile.deleteOnExit();
 
-        // Prepare your encryption context
+        // Prepare your encryption context.
         // https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context
         final Map<String, String> encryptionContext = new HashMap<>();
         encryptionContext.put("encryption", "context");
@@ -84,7 +74,7 @@ public static void run(final AwsKmsCmkId awsKmsCmk, final File sourcePlaintextFi
                         .encryptionContext(encryptionContext)
                         .inputStream(new FileInputStream(sourcePlaintextFile)).build())) {
 
-            // Copy the encrypted data into the encrypted file.
+            // Encrypt the data and write the ciphertext to the encrypted file.
             try (FileOutputStream out = new FileOutputStream(encryptedFile)) {
                 IOUtils.copy(encryptingStream, out);
             }
@@ -111,7 +101,8 @@ public static void run(final AwsKmsCmkId awsKmsCmk, final File sourcePlaintextFi
                 assert v.equals(decryptResult.getEncryptionContext().get(k));
             });
 
-            // Copy the plaintext data to a file
+            // Now that we are more confident that we will decrypt the right message,
+            // we can start decrypting.
             try (FileOutputStream out = new FileOutputStream(decryptedFile)) {
                 IOUtils.copy(decryptingStream, out);
             }

src/examples/java/com/amazonaws/crypto/examples/InMemoryStreamingDefaults.java

@@ -1,15 +1,5 @@
-/*
- * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
- *
- * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except
- * in compliance with the License. A copy of the License is located at
- *
- * http://aws.amazon.com/apache2.0
- *
- * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations under the License.
- */
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
 
 package com.amazonaws.crypto.examples;
 
@@ -50,10 +40,10 @@ public class InMemoryStreamingDefaults {
      * @param sourcePlaintext Plaintext to encrypt
      */
     public static void run(final AwsKmsCmkId awsKmsCmk, final byte[] sourcePlaintext) throws IOException {
-        // Instantiate the SDK
+        // Instantiate the AWS Encryption SDK
         final AwsCrypto awsEncryptionSdk = new AwsCrypto();
 
-        // Prepare your encryption context
+        // Prepare your encryption context.
         // https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context
         final Map<String, String> encryptionContext = new HashMap<>();
         encryptionContext.put("encryption", "context");

src/examples/java/com/amazonaws/crypto/examples/OneStepDefaults.java

@@ -1,15 +1,5 @@
-/*
- * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
- *
- * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except
- * in compliance with the License. A copy of the License is located at
- *
- * http://aws.amazon.com/apache2.0
- *
- * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations under the License.
- */
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
 
 package com.amazonaws.crypto.examples;
 
@@ -42,10 +32,10 @@ public class OneStepDefaults {
      * @param sourcePlaintext Plaintext to encrypt
      */
     public static void run(final AwsKmsCmkId awsKmsCmk, final byte[] sourcePlaintext) {
-        // Instantiate the SDK
+        // Instantiate the AWS Encryption SDK
         final AwsCrypto awsEncryptionSdk = new AwsCrypto();
 
-        // Prepare your encryption context
+        // Prepare your encryption context.
         // https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context
         final Map<String, String> encryptionContext = new HashMap<>();
         encryptionContext.put("encryption", "context");

src/examples/java/com/amazonaws/crypto/examples/OneStepUnsigned.java

@@ -1,15 +1,5 @@
-/*
- * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
- *
- * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except
- * in compliance with the License. A copy of the License is located at
- *
- * http://aws.amazon.com/apache2.0
- *
- * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations under the License.
- */
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
 
 package com.amazonaws.crypto.examples;
 
@@ -55,11 +45,11 @@ public class OneStepUnsigned {
      * @param sourcePlaintext Plaintext to encrypt
      */
     public static void run(final AwsKmsCmkId awsKmsCmk, final byte[] sourcePlaintext) {
-        // Instantiate the SDK and specify the algorithm suite that we want to use.
+        // Instantiate the AWS Encryption SDK and specify the algorithm suite that we want to use.
         final AwsCrypto awsEncryptionSdk = new AwsCrypto();
         awsEncryptionSdk.setEncryptionAlgorithm(CryptoAlgorithm.ALG_AES_256_GCM_IV12_TAG16_HKDF_SHA256);
 
-        // Prepare your encryption context
+        // Prepare your encryption context.
         // https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context
         final Map<String, String> encryptionContext = new HashMap<>();
         encryptionContext.put("encryption", "context");

src/examples/java/com/amazonaws/crypto/examples/keyring/awskms/CustomClientSupplier.java

@@ -1,15 +1,5 @@
-/*
- * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
- *
- * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except
- * in compliance with the License. A copy of the License is located at
- *
- * http://aws.amazon.com/apache2.0
- *
- * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations under the License.
- */
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
 
 package com.amazonaws.crypto.examples.keyring.awskms;
 
@@ -95,10 +85,10 @@ public AWSKMS getClient(String regionId) {
      * @param sourcePlaintext Plaintext to encrypt
      */
     public static void run(final AwsKmsCmkId awsKmsCmk, final byte[] sourcePlaintext) {
-        // Instantiate the SDK
+        // Instantiate the AWS Encryption SDK
         final AwsCrypto awsEncryptionSdk = new AwsCrypto();
 
-        // Prepare your encryption context
+        // Prepare your encryption context.
         // https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context
         final Map<String, String> encryptionContext = new HashMap<>();
         encryptionContext.put("encryption", "context");

src/examples/java/com/amazonaws/crypto/examples/keyring/awskms/CustomKmsClientConfig.java

@@ -1,15 +1,5 @@
-/*
- * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
- *
- * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except
- * in compliance with the License. A copy of the License is located at
- *
- * http://aws.amazon.com/apache2.0
- *
- * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations under the License.
- */
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
 
 package com.amazonaws.crypto.examples.keyring.awskms;
 
@@ -58,10 +48,10 @@ public class CustomKmsClientConfig {
      * @param sourcePlaintext Plaintext to encrypt
      */
     public static void run(final AwsKmsCmkId awsKmsCmk, final byte[] sourcePlaintext) {
-        // Instantiate the SDK
+        // Instantiate the AWS Encryption SDK
         final AwsCrypto awsEncryptionSdk = new AwsCrypto();
 
-        // Prepare your encryption context
+        // Prepare your encryption context.
         // https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context
         final Map<String, String> encryptionContext = new HashMap<>();
         encryptionContext.put("encryption", "context");

src/examples/java/com/amazonaws/crypto/examples/keyring/awskms/DiscoveryDecrypt.java

@@ -1,15 +1,5 @@
-/*
- * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
- *
- * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except
- * in compliance with the License. A copy of the License is located at
- *
- * http://aws.amazon.com/apache2.0
- *
- * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations under the License.
- */
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
 
 package com.amazonaws.crypto.examples.keyring.awskms;
 
@@ -58,10 +48,10 @@ public class DiscoveryDecrypt {
      * @param sourcePlaintext Plaintext to encrypt
      */
     public static void run(final AwsKmsCmkId awsKmsCmk, final byte[] sourcePlaintext) {
-        // Instantiate the SDK
+        // Instantiate the AWS Encryption SDK
         final AwsCrypto awsEncryptionSdk = new AwsCrypto();
 
-        // Prepare your encryption context
+        // Prepare your encryption context.
         // https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context
         final Map<String, String> encryptionContext = new HashMap<>();
         encryptionContext.put("encryption", "context");

src/examples/java/com/amazonaws/crypto/examples/keyring/awskms/DiscoveryDecryptInRegionOnly.java

@@ -1,15 +1,5 @@
-/*
- * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
- *
- * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except
- * in compliance with the License. A copy of the License is located at
- *
- * http://aws.amazon.com/apache2.0
- *
- * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations under the License.
- */
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
 
 package com.amazonaws.crypto.examples.keyring.awskms;
 
@@ -65,10 +55,10 @@ public class DiscoveryDecryptInRegionOnly {
      * @param sourcePlaintext Plaintext to encrypt
      */
     public static void run(final AwsKmsCmkId awsKmsCmk, final byte[] sourcePlaintext) {
-        // Instantiate the SDK
+        // Instantiate the AWS Encryption SDK
         final AwsCrypto awsEncryptionSdk = new AwsCrypto();
 
-        // Prepare your encryption context
+        // Prepare your encryption context.
         // https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context
         final Map<String, String> encryptionContext = new HashMap<>();
         encryptionContext.put("encryption", "context");

src/examples/java/com/amazonaws/crypto/examples/keyring/awskms/DiscoveryDecryptWithPreferredRegions.java

@@ -1,15 +1,5 @@
-/*
- * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
- *
- * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except
- * in compliance with the License. A copy of the License is located at
- *
- * http://aws.amazon.com/apache2.0
- *
- * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations under the License.
- */
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
 
 package com.amazonaws.crypto.examples.keyring.awskms;
 
@@ -71,10 +61,10 @@ public class DiscoveryDecryptWithPreferredRegions {
      * @param sourcePlaintext Plaintext to encrypt
      */
     public static void run(final AwsKmsCmkId awsKmsCmk, final byte[] sourcePlaintext) {
-        // Instantiate the SDK
+        // Instantiate the AWS Encryption SDK
         final AwsCrypto awsEncryptionSdk = new AwsCrypto();
 
-        // Prepare your encryption context
+        // Prepare your encryption context.
         // https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context
         final Map<String, String> encryptionContext = new HashMap<>();
         encryptionContext.put("encryption", "context");

src/examples/java/com/amazonaws/crypto/examples/keyring/awskms/MultipleRegions.java

@@ -1,15 +1,5 @@
-/*
- * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
- *
- * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except
- * in compliance with the License. A copy of the License is located at
- *
- * http://aws.amazon.com/apache2.0
- *
- * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations under the License.
- */
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
 
 package com.amazonaws.crypto.examples.keyring.awskms;
 
@@ -54,10 +44,10 @@ public class MultipleRegions {
      * @param sourcePlaintext      Plaintext to encrypt
      */
     public static void run(final AwsKmsCmkId awsKmsGeneratorCmk, final List<AwsKmsCmkId> awsKmsAdditionalCmks, byte[] sourcePlaintext) {
-        // Instantiate the SDK
+        // Instantiate the AWS Encryption SDK
         final AwsCrypto awsEncryptionSdk = new AwsCrypto();
 
-        // Prepare your encryption context
+        // Prepare your encryption context.
         // https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context
         final Map<String, String> encryptionContext = new HashMap<>();
         encryptionContext.put("encryption", "context");

src/examples/java/com/amazonaws/crypto/examples/keyring/awskms/SingleCmk.java

@@ -1,15 +1,5 @@
-/*
- * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
- *
- * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except
- * in compliance with the License. A copy of the License is located at
- *
- * http://aws.amazon.com/apache2.0
- *
- * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations under the License.
- */
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
 
 package com.amazonaws.crypto.examples.keyring.awskms;
 
@@ -51,10 +41,10 @@ public class SingleCmk {
      * @param sourcePlaintext Plaintext to encrypt
      */
     public static void run(final AwsKmsCmkId awsKmsCmk, final byte[] sourcePlaintext) {
-        // Instantiate the SDK
+        // Instantiate the AWS Encryption SDK
         final AwsCrypto awsEncryptionSdk = new AwsCrypto();
 
-        // Prepare your encryption context
+        // Prepare your encryption context.
         // https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context
         final Map<String, String> encryptionContext = new HashMap<>();
         encryptionContext.put("encryption", "context");