Add examples for converting V2 materials providers to V3 keyrings.

Author: smswz

README.md

@@ -2,6 +2,100 @@
 
 This library provides an S3 client that supports client-side encryption.
 
+## Migration
+
+This version of the library supports reading encrypted objects from previous versions.
+It also supports writing objects with non-legacy algorithms.
+The list of legacy modes and operations will be provided below.
+
+### Examples
+#### V2 KMS Materials Provider to V3 KMS w/ Context Materials Manager and Keyring
+```java
+class Example {
+    public static void main(String[] args) {
+        // V2
+        EncryptionMaterialsProvider materialsProvider = new KMSEncryptionMaterialsProvider(KMS_WRAPPING_KEY_ID);
+        AmazonS3EncryptionV2 v2Client = AmazonS3EncryptionClientV2.encryptionBuilder()
+                .withEncryptionMaterialsProvider(materialsProvider)
+                .build();
+        
+        // V3
+        Keyring keyring = KmsContextKeyring.builder()
+                .wrappingKeyId(KMS_WRAPPING_KEY_ID)
+                .build();
+
+        MaterialsManager materialsManager = new DefaultMaterialsManager(keyring);
+        S3EncryptionClient v3Client = S3EncryptionClient.builder()
+                .materialsManager(materialsManager)
+                .build();
+    }
+}
+```
+
+#### V2 AES Key Materials Provider to V3 AES/GCM Materials Manager and Keyring
+```java
+class Example {
+    public static void main(String[] args) {
+        KeyGenerator keyGen = KeyGenerator.getInstance("AES");
+        keyGen.init(256);
+        SecretKey aesKey = keyGen.generateKey();
+        
+        // V2
+        EncryptionMaterialsProvider materialsProvider = new StaticEncryptionMaterialsProvider(new EncryptionMaterials(aesKey));
+        AmazonS3EncryptionV2 v2Client = AmazonS3EncryptionClientV2.encryptionBuilder()
+                .withEncryptionMaterialsProvider(materialsProvider)
+                .build();
+
+        // V3
+        Keyring keyring = AesGcmKeyring.builder()
+                .wrappingKey(aesKey)
+                .build();
+
+        MaterialsManager materialsManager = new DefaultMaterialsManager(keyring);
+        S3EncryptionClient v3Client = S3EncryptionClient.builder()
+                .materialsManager(materialsManager)
+                .build();
+    }
+}
+```
+
+#### V2 RSA Key Materials Provider to V3 RSA-OAEP Materials Manager and Keyring
+```java
+class Example {
+    public static void main(String[] args) {
+        KeyPairGenerator keyPairGen = KeyPairGenerator.getInstance("RSA");
+        keyPairGen.initialize(2048);
+        KeyPair rsaKey = keyPairGen.generateKeyPair();
+        
+        // V2
+        EncryptionMaterialsProvider materialsProvider = new StaticEncryptionMaterialsProvider(new EncryptionMaterials(rsaKey));
+        AmazonS3EncryptionV2 v2Client = AmazonS3EncryptionClientV2.encryptionBuilder()
+                .withEncryptionMaterialsProvider(materialsProvider)
+                .build();
+
+        // V3
+        Keyring keyring = RsaOaepKeyring.builder()
+                .wrappingKeyPair(rsaKey)
+                .build();
+
+        MaterialsManager materialsManager = new DefaultMaterialsManager(keyring);
+        S3EncryptionClient v3Client = S3EncryptionClient.builder()
+                .materialsManager(materialsManager)
+                .build();
+    }
+}
+```
+
+### Legacy Algorithms and Modes
+#### Content Encryption
+* AES/CBC
+#### Key Wrap Encryption
+* AESWrap
+* RSA-OAEP w/MGF-1 and SHA-256
+* KMS (without context)
+#### Encryption Metadata Storage
+* Instruction File
+
 ## Security
 
 See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.

src/main/java/software/amazon/encryption/s3/S3EncryptionClient.java

@@ -44,9 +44,13 @@ public class S3EncryptionClient implements S3Client {
     private final S3Client _wrappedClient;
     private final MaterialsManager _materialsManager;
 
-    public S3EncryptionClient(S3Client client, MaterialsManager materialsManager) {
-        _wrappedClient = client;
-        _materialsManager = materialsManager;
+    private S3EncryptionClient(Builder builder) {
+        _wrappedClient = builder._wrappedClient;
+        _materialsManager = builder._materialsManager;
+    }
+
+    public static Builder builder() {
+        return new Builder();
     }
 
     @Override
@@ -161,4 +165,25 @@ public String serviceName() {
     public void close() {
         _wrappedClient.close();
     }
+
+    public static class Builder {
+        private S3Client _wrappedClient = S3Client.builder().build();
+        private MaterialsManager _materialsManager;
+
+        private Builder() {}
+
+        public Builder wrappedClient(S3Client wrappedClient) {
+            this._wrappedClient = wrappedClient;
+            return this;
+        }
+
+        public Builder materialsManager(MaterialsManager materialsManager) {
+            this._materialsManager = materialsManager;
+            return this;
+        }
+
+        public S3EncryptionClient build() {
+            return new S3EncryptionClient(this);
+        }
+    }
 }