Scrubbed code comments.

juneb · juneb · commit 77d7094f761c · 2017-08-09T16:50:07.000-07:00
diff --git a/src/examples/java/com/amazonaws/crypto/examples/EscrowedEncryptExample.java b/src/examples/java/com/amazonaws/crypto/examples/EscrowedEncryptExample.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * Copyright 2017 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
@@ -36,24 +36,29 @@
  * <p>
  * Arguments:
  * <ol>
- * <li>KMS KeyArn
+ * <li>Key ARN: To find the Amazon Resource Name of your KMS customer master key (CMK), 
+ *     see 'Viewing Keys' at http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html
  * <li>File Name
  * </ol>
  *
- * Some organizations want the ability to decrypt their data even if KMS is unavailable. This
- * program demonstrates one possible way of accomplishing this by generating an "Escrow" RSA
- * key-pair and using that in addition to the KMS key for encryption. The organization would keep
- * the RSA private key someplace secure (such as an offline HSM) and distribute the public key their
- * developers. This way all standard use would use KMS for decryption, however the organization
- * maintains the ability to decrypt all ciphertexts in a completely offline manner.
+ * AWS Key Management Service (KMS) is highly available. However, some organizations want to decrypt
+ * their data offline and independent of KMS. This sample demonstrates one way to do this.
+ * 
+ * This program generates an "escrowed" RSA key pair. It stores the private key in a secure offline 
+ * location, such as an offline HSM, and distributes the public key to their developers. It also 
+ * creates a KMS customer master key (CMK). The organization encrypts their data with both the 
+ * KMS CMK and the public key, so that either key alone could decrypt it. 
+ *
+ * The team usually uses the KMS CMK for decryption. However, the organization can, at any time
+ * use the private escrowed RSA key to decrypt the ciphertext independent of KMS. 
  */
 public class EscrowedEncryptExample {
     private static PublicKey publicEscrowKey;
     private static PrivateKey privateEscrowKey;
 
     public static void main(final String[] args) throws Exception {
-        // In the real world, the public key would be distributed by the organization.
-        // For this demo, we'll just generate a new random one each time.
+        // In practice, the organization would distribute the public key.
+        // For this demo, we generate a new random key for each operation.
         generateEscrowKeyPair();
 
         final String kmsArn = args[0];
@@ -66,23 +71,25 @@ public static void main(final String[] args) throws Exception {
     }
 
     private static void standardEncrypt(final String kmsArn, final String fileName) throws Exception {
-        // Standard user encrypting to both KMS and the escrow public key
+        // Standard practice: encrypt with the KMS CMK and the escrowed public key
         // 1. Instantiate the SDK
         final AwsCrypto crypto = new AwsCrypto();
 
-        // 2. Instantiate the providers
+        // 2. Instantiate a KMS master key provider
         final KmsMasterKeyProvider kms = new KmsMasterKeyProvider(kmsArn);
-        // Note that the standard user does not have access to the private escrow
-        // key and so simply passes in "null"
+        
+		// 3. Instantiate a JCE master key provider
+		// Because the standard user does not have access to the private 
+        // escrow key, they pass in "null" for the private key parameter.
         final JceMasterKey escrowPub = JceMasterKey.getInstance(publicEscrowKey, null, "Escrow", "Escrow",
                 "RSA/ECB/OAEPWithSHA-512AndMGF1Padding");
 
-        // 3. Combine the providers into a single one
+        // 4. Combine the providers into a single master key provider
         final MasterKeyProvider<?> provider = MultipleProviderFactory.buildMultiProvider(kms, escrowPub);
 
-        // 4. Encrypt the file
-        // To simplify the code, we'll be omitted Encryption Context this time. Production code
-        // should always use Encryption Context. Please see the other examples for more information.
+        // 5. Encrypt the file
+        // To simplify the code, we omit the encryption context. Production code should always 
+        // use an encryption context. For an example, see the other SDK samples.
         final FileInputStream in = new FileInputStream(fileName);
         final FileOutputStream out = new FileOutputStream(fileName + ".encrypted");
         final CryptoOutputStream<?> encryptingStream = crypto.createEncryptingStream(provider, out);
@@ -93,25 +100,26 @@ private static void standardEncrypt(final String kmsArn, final String fileName)
     }
 
     private static void standardDecrypt(final String kmsArn, final String fileName) throws Exception {
-        // A standard user decrypts the file. They can just use the same provider from before
-        // or could use a provider just referring to the KMS key. It doesn't matter.
+        // Standard practice: enncrypt with the KMS CMK and the escrow public key
 
         // 1. Instantiate the SDK
         final AwsCrypto crypto = new AwsCrypto();
 
-        // 2. Instantiate the providers
+        // 2. Instantiate a KMS master key provider
         final KmsMasterKeyProvider kms = new KmsMasterKeyProvider(kmsArn);
-        // Note that the standard user does not have access to the private escrow
-        // key and so simply passes in "null"
+        
+		// 3. Instantiate a JCE master key provider
+        // Because the standard user does not have access to the private 
+        // escrow key, they pass in "null" for the private key parameter.
         final JceMasterKey escrowPub = JceMasterKey.getInstance(publicEscrowKey, null, "Escrow", "Escrow",
                 "RSA/ECB/OAEPWithSHA-512AndMGF1Padding");
 
-        // 3. Combine the providers into a single one
+        // 4. Combine the providers into a single master key provider
         final MasterKeyProvider<?> provider = MultipleProviderFactory.buildMultiProvider(kms, escrowPub);
 
-        // 4. Decrypt the file
-        // To simplify the code, we'll be omitted Encryption Context this time. Production code
-        // should always use Encryption Context. Please see the other examples for more information.
+        // 5. Decrypt the file
+        // To simplify the code, we omit the encryption context. Production code should always 
+        // use an encryption context. For an example, see the other SDK samples.
         final FileInputStream in = new FileInputStream(fileName + ".encrypted");
         final FileOutputStream out = new FileOutputStream(fileName + ".decrypted");
         final CryptoOutputStream<?> decryptingStream = crypto.createDecryptingStream(provider, out);
@@ -121,19 +129,20 @@ private static void standardDecrypt(final String kmsArn, final String fileName)
     }
 
     private static void escrowDecrypt(final String fileName) throws Exception {
-        // The organization can decrypt using just the private escrow key with no calls to KMS
+        // The organization can decrypt the stream using only the private escrow key. 
+		// This method does not call KMS.
 
         // 1. Instantiate the SDK
         final AwsCrypto crypto = new AwsCrypto();
 
-        // 2. Instantiate the provider
-        // Note that the organization does have access to the private escrow key and can use it.
+        // 2. Instantiate a JCE master key provider
+        // This method call uses the escrowed private key 
         final JceMasterKey escrowPriv = JceMasterKey.getInstance(publicEscrowKey, privateEscrowKey, "Escrow", "Escrow",
                 "RSA/ECB/OAEPWithSHA-512AndMGF1Padding");
 
         // 3. Decrypt the file
-        // To simplify the code, we'll be omitted Encryption Context this time. Production code
-        // should always use Encryption Context. Please see the other examples for more information.
+        // To simplify the code, we omit the encryption context. Production code should always 
+        // use an encryption context. For an example, see the other SDK samples.
         final FileInputStream in = new FileInputStream(fileName + ".encrypted");
         final FileOutputStream out = new FileOutputStream(fileName + ".deescrowed");
         final CryptoOutputStream<?> decryptingStream = crypto.createDecryptingStream(escrowPriv, out);
diff --git a/src/examples/java/com/amazonaws/crypto/examples/FileStreamingExample.java b/src/examples/java/com/amazonaws/crypto/examples/FileStreamingExample.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * Copyright 2017 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
@@ -40,7 +40,7 @@
  * </ol>
  * 
  * <p>
- * This program demonstrates using a normal java {@link SecretKey} object as a {@link MasterKey} to
+ * This program demonstrates using a standard Java {@link SecretKey} object as a {@link MasterKey} to
  * encrypt and decrypt streaming data.
  */
 public class FileStreamingExample {
@@ -49,22 +49,21 @@ public class FileStreamingExample {
     public static void main(String[] args) throws IOException {
         srcFile = args[0];
 
-        // In this example, we'll pretend that we loaded this key from
-        // some existing store but actually just generate a random one
+        // In this example, we generate a random key. In practice, 
+        // you would get a key from an existing store
         SecretKey cryptoKey = retrieveEncryptionKey();
 
-        // Convert key into a provider. We'll use AES GCM because it is
-        // a good secure algorithm.
+        // Create a JCE master key provider using the random key and an AES-GCM encryption algorithm
         JceMasterKey masterKey = JceMasterKey.getInstance(cryptoKey, "Example", "RandomKey", "AES/GCM/NoPadding");
 
-        // Instantiate the SDKs
+        // Instantiate the SDK
         AwsCrypto crypto = new AwsCrypto();
 
-        // Create the encryption context to identify this ciphertext
+        // Create an encryption context to identify this ciphertext
         Map<String, String> context = Collections.singletonMap("Example", "FileStreaming");
 
-        // The file might be *really* big, so we don't want
-        // to load it all into memory. Streaming is necessary.
+        // Because the file might be to large to load into memory, we use 
+        // streaming, then encrypt the file stream.
         FileInputStream in = new FileInputStream(srcFile);
         CryptoInputStream<JceMasterKey> encryptingStream = crypto.createEncryptingStream(masterKey, in, context);
 
@@ -73,24 +72,24 @@ public static void main(String[] args) throws IOException {
         encryptingStream.close();
         out.close();
 
-        // Let's decrypt the file now, remembering to check the encryption context
+        // Decrypt the file. Verify the encryption context before returning the plaintext.
         in = new FileInputStream(srcFile + ".encrypted");
         CryptoInputStream<JceMasterKey> decryptingStream = crypto.createDecryptingStream(masterKey, in);
-        // Does it have the right encryption context?
+        // Does it contain the expected encryption context?
         if (!"FileStreaming".equals(decryptingStream.getCryptoResult().getEncryptionContext().get("Example"))) {
             throw new IllegalStateException("Bad encryption context");
         }
 
-        // Finally, actually write out the data
+        // Return the plaintext data
         out = new FileOutputStream(srcFile + ".decrypted");
         IOUtils.copy(decryptingStream, out);
         decryptingStream.close();
         out.close();
     }
 
     /**
-     * In the real world, this key will need to be persisted somewhere. For this demo we'll generate
-     * a new random one each time.
+     * In practice, this key would be saved in a secure location. 
+	 * For this demo we'll generate a new random key for each operation.
      */
     private static SecretKey retrieveEncryptionKey() {
         SecureRandom rnd = new SecureRandom();
diff --git a/src/examples/java/com/amazonaws/crypto/examples/StringExample.java b/src/examples/java/com/amazonaws/crypto/examples/StringExample.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * Copyright 2017 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
@@ -28,8 +28,8 @@
  * <p>
  * Arguments:
  * <ol>
- * <li>KMS Key Arn
- * <li>String to encrypt
+ * <li>Key ARN: To find the Amazon Resource Name of your KMS customer master key (CMK), 
+ *     see 'Viewing Keys' at http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html
  * </ol>
  */
 public class StringExample {
@@ -48,7 +48,7 @@ public static void main(final String[] args) {
 
         // Encrypt the data
         //
-        // Most encrypted data should have associated encryption context
+        // Most encrypted data should have an associated encryption context
         // to protect integrity. Here, we'll just use a placeholder value.
         //
         // For more information see:
@@ -60,21 +60,24 @@ public static void main(final String[] args) {
 
         // Decrypt the data
         final CryptoResult<String, KmsMasterKey> decryptResult = crypto.decryptString(prov, ciphertext);
-        // We need to check the encryption context (and ideally key) to ensure that
-        // this was the ciphertext we expected
+        
+		// Before returning the plaintext, verify that the customer master key that
+        // was used in the encryption operation was the one supplied to the master key provider. 
         if (!decryptResult.getMasterKeyIds().get(0).equals(keyArn)) {
             throw new IllegalStateException("Wrong key id!");
         }
 
-        // The SDK may add information to the encryption context, so we check to ensure
-        // that all of our values are present
+        // Also, verify that the encryption context in the result contains the
+        // encryption context supplied to the encryptString method. Because the
+        // SDK can add values to the encryption context, we don't require that 
+        // the entire context matches. 
         for (final Map.Entry<String, String> e : context.entrySet()) {
             if (!e.getValue().equals(decryptResult.getEncryptionContext().get(e.getKey()))) {
                 throw new IllegalStateException("Wrong Encryption Context!");
             }
         }
 
-        // Now that we know we have the correct data, we can output it.
+        // Now that we know we have the correct data, we can return it.
         System.out.println("Decrypted: " + decryptResult.getResult());
     }
 }
