Sync code comments with SDK examples

Author: juneb

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

@@ -36,29 +36,33 @@
  * <p>
  * Arguments:
  * <ol>
- * <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
+ * <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>
  *
- * 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.
+ * 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.
  * 
- * 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 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.
  *
- * 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 practice, the organization would distribute the public key.
-        // For this demo, we generate a new random key for each operation.
+        // 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];
@@ -71,16 +75,16 @@ public static void main(final String[] args) throws Exception {
     }
 
     private static void standardEncrypt(final String kmsArn, final String fileName) throws Exception {
-        // Standard practice: encrypt with the KMS CMK and the escrowed public key
+        // Encrypt with the KMS CMK and the escrowed public key
         // 1. Instantiate the SDK
         final AwsCrypto crypto = new AwsCrypto();
 
         // 2. Instantiate a KMS master key provider
         final KmsMasterKeyProvider kms = new KmsMasterKeyProvider(kmsArn);
 
-		// 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.
+        // 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");
 
@@ -100,16 +104,17 @@ private static void standardEncrypt(final String kmsArn, final String fileName)
     }
 
     private static void standardDecrypt(final String kmsArn, final String fileName) throws Exception {
-        // Standard practice: enncrypt with the KMS CMK and the escrow public key
+        // 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 a KMS master key provider
         final KmsMasterKeyProvider kms = new KmsMasterKeyProvider(kmsArn);
 
-		// 3. Instantiate a JCE master key provider
-        // Because the standard user does not have access to the private 
+        // 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");
@@ -129,14 +134,14 @@ private static void standardDecrypt(final String kmsArn, final String fileName)
     }
 
     private static void escrowDecrypt(final String fileName) throws Exception {
-        // The organization can decrypt the stream using only the private escrow key. 
-		// This method does not call 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 a JCE master key provider
-        // This method call uses the escrowed private key 
+        // This method call uses the escrowed private key, not null 
         final JceMasterKey escrowPriv = JceMasterKey.getInstance(publicEscrowKey, privateEscrowKey, "Escrow", "Escrow",
                 "RSA/ECB/OAEPWithSHA-512AndMGF1Padding");
 

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

@@ -32,13 +32,13 @@
 /**
  * <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 standard Java {@link SecretKey} object as a {@link MasterKey} to
  * encrypt and decrypt streaming data.
@@ -62,8 +62,8 @@ public static void main(String[] args) throws IOException {
         // Create an encryption context to identify this ciphertext
         Map<String, String> context = Collections.singletonMap("Example", "FileStreaming");
 
-        // Because the file might be to large to load into memory, we use 
-        // streaming, then encrypt the file stream.
+        // 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);
 
@@ -89,12 +89,12 @@ public static void main(String[] args) throws IOException {
 
     /**
      * In practice, this key would be saved in a secure location. 
-	 * For this demo we'll generate a new random key for each operation.
+     * 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

@@ -28,8 +28,9 @@
  * <p>
  * Arguments:
  * <ol>
- * <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>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>
  */
 public class StringExample {
@@ -49,7 +50,7 @@ public static void main(final String[] args) {
         // Encrypt the data
         //
         // Most encrypted data should have an associated encryption context
-        // to protect integrity. Here, we'll just use a placeholder value.
+        // 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
@@ -61,23 +62,23 @@ public static void main(final String[] args) {
         // Decrypt the data
         final CryptoResult<String, KmsMasterKey> decryptResult = crypto.decryptString(prov, ciphertext);
 
-		// Before returning the plaintext, verify that the customer master key that
+        // 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!");
         }
 
         // 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 
+        // 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 return it.
+        // Now we can return the plaintext data
         System.out.println("Decrypted: " + decryptResult.getResult());
     }
 }