MaterialsDescription Support for Keyrings (#467)

* I created the MaterialsDescription class to help identify AES + RSA keys for reEncryptInstructionFile feature Co-authored-by: Anirav Kareddy <aniravk@amazon.com>

Author: akareddy04

src/main/java/software/amazon/encryption/s3/internal/ContentMetadata.java

@@ -15,7 +15,13 @@ public class ContentMetadata {
 
  private final EncryptedDataKey _encryptedDataKey;
  private final String _encryptedDataKeyAlgorithm;
- private final Map<String, String> _encryptedDataKeyContext;
+
+ /**
+ * This field stores either encryption context or material description.
+ * We use a single field to store both in order to maintain backwards
+ * compatibility with V2, which treated both as the same.
+ */
+ private final Map<String, String> _encryptionContextOrMatDesc;
 
  private final byte[] _contentIv;
  private final String _contentCipher;
@@ -27,7 +33,7 @@ private ContentMetadata(Builder builder) {
 
  _encryptedDataKey = builder._encryptedDataKey;
  _encryptedDataKeyAlgorithm = builder._encryptedDataKeyAlgorithm;
- _encryptedDataKeyContext = builder._encryptedDataKeyContext;
+ _encryptionContextOrMatDesc = builder._encryptionContextOrMatDesc;
 
  _contentIv = builder._contentIv;
  _contentCipher = builder._contentCipher;
@@ -51,14 +57,15 @@ public String encryptedDataKeyAlgorithm() {
  return _encryptedDataKeyAlgorithm;
  }
 
+
  /**
  * Note that the underlying implementation uses a Collections.unmodifiableMap which is
  * immutable.
  */
  @SuppressFBWarnings(value = "EI_EXPOSE_REP", justification = "False positive; underlying"
  + " implementation is immutable")
  public Map<String, String> encryptedDataKeyContext() {
- return _encryptedDataKeyContext;
+ return _encryptionContextOrMatDesc;
  }
 
  public byte[] contentIv() {
@@ -85,7 +92,7 @@ public static class Builder {
 
  private EncryptedDataKey _encryptedDataKey;
  private String _encryptedDataKeyAlgorithm;
- private Map<String, String> _encryptedDataKeyContext;
+ private Map<String, String> _encryptionContextOrMatDesc;
 
  private byte[] _contentIv;
  private String _contentCipher;
@@ -111,8 +118,8 @@ public Builder encryptedDataKeyAlgorithm(String encryptedDataKeyAlgorithm) {
  return this;
  }
 
- public Builder encryptedDataKeyContext(Map<String, String> encryptedDataKeyContext) {
- _encryptedDataKeyContext = Collections.unmodifiableMap(encryptedDataKeyContext);
+ public Builder encryptionContextOrMatDesc(Map<String, String> encryptionContextOrMatDesc) {
+ _encryptionContextOrMatDesc = Collections.unmodifiableMap(encryptionContextOrMatDesc);
  return this;
  }
 

src/main/java/software/amazon/encryption/s3/internal/ContentMetadataDecodingStrategy.java

@@ -136,8 +136,8 @@ private ContentMetadata readFromMap(Map<String, String> metadata, GetObjectRespo
  .keyProviderInfo(keyProviderInfo.getBytes(StandardCharsets.UTF_8))
  .build();
 
- // Get encrypted data key encryption context
- final Map<String, String> encryptionContext = new HashMap<>();
+ // Get encrypted data key encryption context or materials description (depending on the keyring)
+ final Map<String, String> encryptionContextOrMatDesc = new HashMap<>();
  // The V2 client treats null value here as empty, do the same to avoid incompatibility
  String jsonEncryptionContext = metadata.getOrDefault(MetadataKeyConstants.ENCRYPTED_DATA_KEY_CONTEXT, "{}");
  // When the encryption context contains non-US-ASCII characters,
@@ -149,7 +149,7 @@ private ContentMetadata readFromMap(Map<String, String> metadata, GetObjectRespo
  JsonNode objectNode = parser.parse(decodedJsonEncryptionContext);
 
  for (Map.Entry<String, JsonNode> entry : objectNode.asObject().entrySet()) {
- encryptionContext.put(entry.getKey(), entry.getValue().asString());
+ encryptionContextOrMatDesc.put(entry.getKey(), entry.getValue().asString());
  }
  } catch (Exception e) {
  throw new RuntimeException(e);
@@ -161,7 +161,7 @@ private ContentMetadata readFromMap(Map<String, String> metadata, GetObjectRespo
  return ContentMetadata.builder()
  .algorithmSuite(algorithmSuite)
  .encryptedDataKey(edk)
- .encryptedDataKeyContext(encryptionContext)
+ .encryptionContextOrMatDesc(encryptionContextOrMatDesc)
  .contentIv(iv)
  .contentRange(contentRange)
  .build();

src/main/java/software/amazon/encryption/s3/internal/ContentMetadataEncodingStrategy.java

@@ -80,11 +80,16 @@ private Map<String, String> addMetadataToMap(Map<String, String> map, Encryption
 
  try (JsonWriter jsonWriter = JsonWriter.create()) {
  jsonWriter.writeStartObject();
- for (Map.Entry<String, String> entry : materials.encryptionContext().entrySet()) {
- jsonWriter.writeFieldName(entry.getKey()).writeValue(entry.getValue());
+ if (!materials.encryptionContext().isEmpty() && materials.materialsDescription().isEmpty()) {
+ for (Map.Entry<String, String> entry : materials.encryptionContext().entrySet()) {
+ jsonWriter.writeFieldName(entry.getKey()).writeValue(entry.getValue());
+ }
+ } else if (materials.encryptionContext().isEmpty() && !materials.materialsDescription().isEmpty()) {
+ for (Map.Entry<String, String> entry : materials.materialsDescription().entrySet()) {
+ jsonWriter.writeFieldName(entry.getKey()).writeValue(entry.getValue());
+ }
  }
  jsonWriter.writeEndObject();
-
  String jsonEncryptionContext = new String(jsonWriter.getBytes(), StandardCharsets.UTF_8);
  metadata.put(MetadataKeyConstants.ENCRYPTED_DATA_KEY_CONTEXT, jsonEncryptionContext);
  } catch (JsonWriter.JsonGenerationException e) {

src/main/java/software/amazon/encryption/s3/materials/AesKeyring.java

@@ -20,7 +20,7 @@
  * This keyring can wrap keys with the active keywrap algorithm and
  * unwrap with the active and legacy algorithms for AES keys.
  */
-public class AesKeyring extends S3Keyring {
+public class AesKeyring extends RawKeyring {
 
  private static final String KEY_ALGORITHM = "AES";
 
@@ -88,6 +88,11 @@ public boolean isLegacy() {
  return false;
  }
 
+ @Override
+ public EncryptionMaterials modifyMaterials(EncryptionMaterials materials) {
+ return modifyMaterialsForRawKeyring(materials);
+ }
+
  @Override
  public String keyProviderInfo() {
  return KEY_PROVIDER_INFO;
@@ -98,13 +103,6 @@ public EncryptionMaterials generateDataKey(EncryptionMaterials materials) {
  return defaultGenerateDataKey(materials);
  }
 
- @Override
- public EncryptionMaterials modifyMaterials(EncryptionMaterials materials) {
- warnIfEncryptionContextIsPresent(materials);
-
- return materials;
- }
-
  @Override
  public byte[] encryptDataKey(SecureRandom secureRandom,
  EncryptionMaterials materials)
@@ -177,7 +175,7 @@ protected Map<String, DecryptDataKeyStrategy> decryptDataKeyStrategies() {
  return decryptDataKeyStrategies;
  }
 
-  public static class Builder extends S3Keyring.Builder<AesKeyring, Builder> {
+ public static class Builder extends RawKeyring.Builder<AesKeyring, Builder> {
  private SecretKey _wrappingKey;
 
  private Builder() {
@@ -199,7 +197,6 @@ public Builder wrappingKey(final SecretKey wrappingKey) {
  _wrappingKey = wrappingKey;
  return builder();
  }
-
  public AesKeyring build() {
  return new AesKeyring(this);
  }

src/main/java/software/amazon/encryption/s3/materials/EncryptionMaterials.java

@@ -4,6 +4,7 @@
 
 import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
 import software.amazon.awssdk.services.s3.model.S3Request;
+import software.amazon.encryption.s3.S3EncryptionClientException;
 import software.amazon.encryption.s3.algorithms.AlgorithmSuite;
 import software.amazon.encryption.s3.internal.CipherMode;
 import software.amazon.encryption.s3.internal.CipherProvider;
@@ -27,6 +28,7 @@ final public class EncryptionMaterials implements CryptographicMaterials {
  // Additional information passed into encrypted that is required on decryption as well
  // Should NOT contain sensitive information
  private final Map<String, String> _encryptionContext;
+ private final MaterialsDescription _materialsDescription;
 
  private final List<EncryptedDataKey> _encryptedDataKeys;
  private final byte[] _plaintextDataKey;
@@ -43,6 +45,7 @@ private EncryptionMaterials(Builder builder) {
  this._cryptoProvider = builder._cryptoProvider;
  this._plaintextLength = builder._plaintextLength;
  this._ciphertextLength = _plaintextLength + _algorithmSuite.cipherTagLengthBytes();
+ this._materialsDescription = builder._materialsDescription;
  }
 
  static public Builder builder() {
@@ -101,6 +104,9 @@ public Provider cryptoProvider() {
  return _cryptoProvider;
  }
 
+ public MaterialsDescription materialsDescription() {
+ return _materialsDescription;
+ }
  @Override
  public CipherMode cipherMode() {
  return CipherMode.ENCRYPT;
@@ -119,6 +125,7 @@ public Builder toBuilder() {
  .encryptedDataKeys(_encryptedDataKeys)
  .plaintextDataKey(_plaintextDataKey)
  .cryptoProvider(_cryptoProvider)
+ .materialsDescription(_materialsDescription)
  .plaintextLength(_plaintextLength);
  }
 
@@ -132,6 +139,7 @@ static public class Builder {
  private byte[] _plaintextDataKey = null;
  private long _plaintextLength = -1;
  private Provider _cryptoProvider = null;
+ private MaterialsDescription _materialsDescription = MaterialsDescription.builder().build();
 
  private Builder() {
  }
@@ -145,7 +153,12 @@ public Builder algorithmSuite(AlgorithmSuite algorithmSuite) {
  _algorithmSuite = algorithmSuite;
  return this;
  }
-
+ public Builder materialsDescription(MaterialsDescription materialsDescription) {
+ _materialsDescription = materialsDescription == null
+ ? MaterialsDescription.builder().build()
+ : materialsDescription;
+ return this;
+ }
  public Builder encryptionContext(Map<String, String> encryptionContext) {
  _encryptionContext = encryptionContext == null
  ? Collections.emptyMap()
@@ -175,6 +188,9 @@ public Builder plaintextLength(long plaintextLength) {
  }
 
  public EncryptionMaterials build() {
+ if (!_materialsDescription.isEmpty() && !_encryptionContext.isEmpty()) {
+ throw new S3EncryptionClientException("MaterialsDescription and EncryptionContext cannot both be set!");
+ }
  return new EncryptionMaterials(this);
  }
  }

src/main/java/software/amazon/encryption/s3/materials/MaterialsDescription.java

@@ -0,0 +1,111 @@
+// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+package software.amazon.encryption.s3.materials;
+
+import java.util.Collection;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * This class is used to provide key-value pairs that describe the key material used with the Keyring, specifically for AES and RSA Keyrings.
+ * This will be useful during the re-encryption of instruction file.
+ * The stored Materials Description is immutable once created.
+ */
+public class MaterialsDescription implements Map<String, String> {
+ private final Map<String, String> materialsDescription;
+
+ private MaterialsDescription(Builder builder) {
+ this.materialsDescription = Collections.unmodifiableMap(new HashMap<>(builder.materialsDescription));
+ }
+ public static Builder builder() {
+ return new Builder();
+ }
+ public Map<String, String> getMaterialsDescription() {
+ return this.materialsDescription;
+ }
+
+ @Override
+ public int size() {
+ return materialsDescription.size();
+ }
+
+ @Override
+ public boolean isEmpty() {
+ return materialsDescription.isEmpty();
+ }
+
+ @Override
+ public boolean containsKey(Object key) {
+ return materialsDescription.containsKey(key);
+ }
+
+ @Override
+ public boolean containsValue(Object value) {
+ return materialsDescription.containsValue(value);
+ }
+
+ @Override
+ public String get(Object key) {
+ return materialsDescription.get(key);
+ }
+
+ @Override
+ public String put(String key, String value) {
+ throw new UnsupportedOperationException("This map is immutable");
+ }
+
+ @Override
+ public String remove(Object key) {
+ return materialsDescription.remove(key);
+ }
+
+ @Override
+ public void putAll(Map<? extends String, ? extends String> m) {
+ throw new UnsupportedOperationException("This map is immutable");
+ }
+
+ @Override
+ public void clear() {
+ materialsDescription.clear();
+ }
+
+ @Override
+ public Set<String> keySet() {
+ return materialsDescription.keySet();
+ }
+
+ @Override
+ public Collection<String> values() {
+ return materialsDescription.values();
+ }
+
+ @Override
+ public Set<Entry<String, String>> entrySet() {
+ return materialsDescription.entrySet();
+ }
+
+
+ public static class Builder {
+ private final Map<String, String> materialsDescription = new HashMap<>();
+ public Builder put(String key, String value) {
+ if (key == null || value == null) {
+ throw new IllegalArgumentException("Key and value must not be null");
+ }
+ materialsDescription.put(key, value);
+ return this;
+ }
+ public Builder putAll(Map<String, String> description) {
+ if (description == null) {
+ throw new IllegalArgumentException("Description must not be null");
+ }
+ materialsDescription.putAll(description);
+ return this;
+ }
+ public MaterialsDescription build() {
+ return new MaterialsDescription(this);
+ }
+ }
+}