Updating wording and adding more Deprecated annotations

Author: WesleyRosenblum

src/main/java/com/amazonaws/encryptionsdk/AwsCrypto.java

@@ -55,8 +55,8 @@
  * byte-arrays and streams. This data is encrypted using the specified {@link CryptoAlgorithm} and a
  * {@code plaintextDataKey} which is unique to each encrypted message. This {@code plaintextDataKey} is then encrypted
  * using one (or more) {@link MasterKey MasterKeys} or a {@link Keyring}. The process is reversed on decryption with the
- * code selecting a copy of the {@code EncryptedDataKey} protected by a usable {@code MasterKey} or {@code Keyring},
- * decrypting the {@code EncryptedDataKey}, and then decrypting the message.
+ * code selecting an {@code EncryptedDataKey} embedded in the encrypted message, decrypting the {@code EncryptedDataKey}
+ * using a {@link MasterKey MasterKey} or {@link Keyring}, and then decrypting the message.
  *
  * <p>
  * Note:

src/main/java/com/amazonaws/encryptionsdk/AwsCryptoResult.java

@@ -76,7 +76,7 @@ public Map<String, String> getEncryptionContext() {
     }
 
     /**
-     * Convenience method equivalent to {@link #getHeaders()}.{@code getCryptoAlgoId()}.
+     * Convenience method equivalent to {@link #getHeaders()}{@code .getCryptoAlgoId()}.
      */
     public CryptoAlgorithm getAlgorithmSuite() {
         return headers.getCryptoAlgoId();

src/main/java/com/amazonaws/encryptionsdk/internal/DecryptionHandler.java

@@ -34,6 +34,7 @@
 import com.amazonaws.encryptionsdk.MasterKeyProvider;
 import com.amazonaws.encryptionsdk.exception.AwsCryptoException;
 import com.amazonaws.encryptionsdk.exception.BadCiphertextException;
+import com.amazonaws.encryptionsdk.keyrings.Keyring;
 import com.amazonaws.encryptionsdk.keyrings.KeyringTrace;
 import com.amazonaws.encryptionsdk.model.CiphertextFooters;
 import com.amazonaws.encryptionsdk.model.CiphertextHeaders;
@@ -111,8 +112,11 @@ private DecryptionHandler(final CryptoMaterialsManager materialsManager, final C
      *            the key blobs encoded in the provided ciphertext.
      * @throws AwsCryptoException
      *             if the master key is null.
+     * @deprecated MasterKeyProviders have been deprecated in favor of {@link Keyring}s.
+     *             Use {@link #create(CryptoMaterialsManager)} instead.
      */
     @SuppressWarnings("unchecked")
+    @Deprecated
     public static <K extends MasterKey<K>> DecryptionHandler<K> create(
             final MasterKeyProvider<K> customerMasterKeyProvider
     ) throws AwsCryptoException {
@@ -136,8 +140,11 @@ public static <K extends MasterKey<K>> DecryptionHandler<K> create(
      *            {@link #processBytes(byte[], int, int, byte[], int)}
      * @throws AwsCryptoException
      *             if the master key is null.
+     * @deprecated MasterKeyProviders have been deprecated in favor of {@link Keyring}s.
+     *             Use {@link #create(CryptoMaterialsManager, CiphertextHeaders)} instead.
      */
     @SuppressWarnings("unchecked")
+    @Deprecated
     public static <K extends MasterKey<K>> DecryptionHandler<K> create(
             final MasterKeyProvider<K> customerMasterKeyProvider, final CiphertextHeaders headers
     ) throws AwsCryptoException {
@@ -537,7 +544,15 @@ public CiphertextHeaders getHeaders() {
         return ciphertextHeaders_;
     }
 
+    /**
+     * The master key that was used to decrypt the encrypted data key. This returns an
+     * empty list if Keyrings are in use.
+     *
+     * @deprecated MasterKeys have been deprecated in favor of {@link Keyring}s.
+     *             Use {@link #getKeyringTrace()} to view which key was used in decryption.
+     */
     @Override
+    @Deprecated
     public List<K> getMasterKeys() {
         if(dataKey_.getMasterKey() == null) {
             return Collections.emptyList();

src/main/java/com/amazonaws/encryptionsdk/internal/EncryptionHandler.java

@@ -21,12 +21,14 @@
 import java.security.Signature;
 import java.security.SignatureException;
 import java.security.interfaces.ECPrivateKey;
+import java.util.Collections;
 import java.util.List;
 import java.util.Map;
 
 import javax.crypto.Cipher;
 import javax.crypto.SecretKey;
 
+import com.amazonaws.encryptionsdk.keyrings.Keyring;
 import com.amazonaws.encryptionsdk.keyrings.KeyringTrace;
 import org.bouncycastle.asn1.ASN1Encodable;
 import org.bouncycastle.asn1.ASN1Integer;
@@ -408,8 +410,19 @@ private CiphertextHeaders signCiphertextHeaders(final CiphertextHeaders unsigned
         return unsignedHeaders;
     }
 
+    /**
+     * The master keys that were used to encrypt the data key. This returns an
+     * empty list if Keyrings are in use.
+     *
+     * @deprecated MasterKeys have been deprecated in favor of {@link Keyring}s.
+     *             Use {@link #getKeyringTrace()} to view which key were used in encryption.
+     */
     @Override
+    @Deprecated
     public List<? extends MasterKey<?>> getMasterKeys() {
+        if(masterKeys_ == null) {
+            return Collections.emptyList();
+        }
         //noinspection unchecked
         return (List)masterKeys_; // This is unmodifiable
     }

src/main/java/com/amazonaws/encryptionsdk/internal/MessageCryptoHandler.java

@@ -50,6 +50,8 @@ public interface MessageCryptoHandler extends CryptoHandler {
      * All <em>used</em> {@link MasterKey}s. For encryption flows, these are all the
      * {@link MasterKey}s used to protect the data. In the decryption flow, it is the single
      * {@link MasterKey} actually used to decrypt the data.
+     *
+     * @deprecated MasterKeys and MasterKeyProviders have been deprecated in favor of {@link Keyring}s
      */
     @Deprecated
     List<? extends MasterKey<?>> getMasterKeys();