Merge pull request #23 from juneb/scrub-code-comments

Scrubbed code comments

Author: mattsb42-aws

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,33 @@
  * <p>
  * Arguments:
  * <ol>
- * <li>KMS KeyArn
- * <li>File Name
+ * <li>Key ARN: For help finding the Amazon Resource Name (ARN) of your KMS customer master 
+ *    key (CMK), see 'Viewing Keys' at http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html
+ *
+  * <li>Name of file containing plaintext data to encrypt
  * </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.
+ * You might use AWS Key Management Service (KMS) for most encryption and decryption operations, but 
+ * still want the option of decrypting your data offline independently of KMS. This sample 
+ * demonstrates one way to do this.
+ * 
+ * The sample encrypts data under both a KMS customer master key (CMK) and an "escrowed" RSA key pair
+ * so that either key alone can decrypt it. You might commonly use the KMS CMK for decryption. However, 
+ * at any time, you can use the private RSA key to decrypt the ciphertext independent of KMS.
+ *
+ * This sample uses the JCEMasterKey class to generate a RSA public-private key pair
+ * and saves the key pair in memory. In practice, you would store the private key in a secure offline 
+ * location, such as an offline HSM, and distribute the public key to your development team.
+ *
  */
 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.
+        // This sample generates a new random key for each operation.
+        // In practice, you would distribute the public key and save the private key in secure
+        // storage.
         generateEscrowKeyPair();
 
         final String kmsArn = args[0];
@@ -66,23 +75,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
+        // 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 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 +104,27 @@ 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.
+        // Decrypt with the KMS CMK and the escrow public key. You can use a combined provider, 
+        // as shown here, or just the KMS master key provider.
 
         // 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 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 +134,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
+        // You can decrypt the stream using only the private 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, not null 
         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);

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
@@ -32,15 +32,15 @@
 /**
  * <p>
  * Encrypts and then decrypts a file under a random key.
- * 
+ *
  * <p>
  * Arguments:
  * <ol>
- * <li>fileName
+ * <li>Name of file containing plaintext data to encrypt
  * </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 stream the data, instead of 
+        //loading it all at once.
         FileInputStream in = new FileInputStream(srcFile);
         CryptoInputStream<JceMasterKey> encryptingStream = crypto.createEncryptingStream(masterKey, in, context);
 
@@ -73,29 +72,29 @@ 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 generate a new random key for each operation.
      */
     private static SecretKey retrieveEncryptionKey() {
         SecureRandom rnd = new SecureRandom();
         byte[] rawKey = new byte[16]; // 128 bits
         rnd.nextBytes(rawKey);
         return new SecretKeySpec(rawKey, "AES");
     }
-}
+}

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,7 +28,8 @@
  * <p>
  * Arguments:
  * <ol>
- * <li>KMS Key Arn
+ * <li>Key ARN: For help finding the Amazon Resource Name (ARN) of your KMS customer master 
+ *    key (CMK), see 'Viewing Keys' at http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html
  * <li>String to encrypt
  * </ol>
  */
@@ -48,8 +49,8 @@ public static void main(final String[] args) {
 
         // Encrypt the data
         //
-        // Most encrypted data should have associated encryption context
-        // to protect integrity. Here, we'll just use a placeholder value.
+        // Most encrypted data should have an associated encryption context
+        // to protect integrity. This sample uses placeholder values.
         //
         // For more information see:
         // blogs.aws.amazon.com/security/post/Tx2LZ6WBJJANTNW/How-to-Protect-the-Integrity-of-Your-Encrypted-Data-by-Using-AWS-Key-Management
@@ -60,21 +61,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, 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 we can return the plaintext data
         System.out.println("Decrypted: " + decryptResult.getResult());
     }
 }