DOCSP-7658: Java CSFLE fixes (#572)

* Fixes to CSFLE Guide for the Java sections

Author: Chris Cho

source/includes/steps-fle-configure-the-mongodb-client.yaml

@@ -40,13 +40,13 @@ content: |
         :tabid: java-sync
 
         .. code-block:: java
-           :emphasize-lines: 2,3
+           :emphasize-lines: 2,5
+
+           Map<String, Object> keyMap = new HashMap<String, Object>();
+           keyMap.put("key", localMasterKey);
 
-           Map<String, Map<String, Object>> kmsProviders = new HashMap<String, Map<String, Object>>() {{
-             put("local", new HashMap<String, Object>() {{
-               put("key", localMasterKey);
-             }});
-           }};
+           Map<String, Map<String, Object>> kmsProviders = new HashMap<String, Map<String, Object>>();
+           kmsProviders.put("local", keyMap);
      .. tab::
         :tabid: nodejs
 
@@ -86,9 +86,8 @@ content: |
         .. code-block:: java
            :emphasize-lines: 2
 
-           HashMap<String, BsonDocument> schemaMap = new HashMap<String, BsonDocument>() {{
-             put("medicalRecords.patients", BsonDocument.parse(jsonSchema));
-           }}
+           HashMap<String, BsonDocument> schemaMap = new HashMap<String, BsonDocument>();
+           schemaMap.put("medicalRecords.patients", BsonDocument.parse(jsonSchema));
      .. tab::
         :tabid: nodejs
 
@@ -124,9 +123,8 @@ content: |
         .. code-block:: java
            :emphasize-lines: 2
 
-           final Map<String, Object> extraOptions = new HashMap<String, Object>() {{
-             put("mongocryptdSpawnPath", "/usr/local/bin/mongocryptd");
-           }};
+           Map<String, Object> extraOptions = new HashMap<String, Object>();
+           extraOptions.put("mongocryptdSpawnPath", "/usr/local/bin/mongocryptd");
 
         .. admonition:: Encryption Binary Daemon
            :class: note
@@ -199,14 +197,14 @@ content: |
            :emphasize-lines: 3-8
 
            MongoClientSettings clientSettings = MongoClientSettings.builder()
-             .applyConnectionString(new ConnectionString("mongodb://localhost:27017"))
-             .autoEncryptionSettings(AutoEncryptionSettings.builder()
-               .keyVaultNamespace(keyVaultNamespace)
-               .kmsProviders(kmsProviders)
-               .schemaMap(schemaMap)
-               .extraOptions(extraOptions)
-               .build())
-             .build();
+               .applyConnectionString(new ConnectionString("mongodb://localhost:27017"))
+               .autoEncryptionSettings(AutoEncryptionSettings.builder()
+                   .keyVaultNamespace(keyVaultNamespace)
+                   .kmsProviders(kmsProviders)
+                   .schemaMap(schemaMap)
+                   .extraOptions(extraOptions)
+                   .build())
+               .build();
 
            MongoClient mongoClient = MongoClients.create(clientSettings);
      .. tab::

source/includes/steps-fle-convert-to-a-remote-master-key.yaml

@@ -46,18 +46,19 @@ content: |
         :tabid: java-sync
 
         .. code-block:: java
-           :emphasize-lines: 5-8
-
-           final BsonString masterKeyRegion = new BsonString("<Master Key AWS Region>"); // e.g. "us-east-2"
-           final BsonString awsAccessKeyId = new BsonString("<IAM User Access Key ID>");
-           final BsonString awsSecretAccessKey = new BsonString("<IAM User Secret Access Key>");
-           Map<String, Map<String, Object>> kmsProviders = new HashMap<String, Map<String, Object>>() {{
-             put("aws", new HashMap<String, Object>() {{
-               put("region", masterKeyRegion);
-               put("accessKeyId", awsAccessKeyId);
-               put("secretAccessKey", awsSecretAccessKey);
-             }});
-           }};
+           :emphasize-lines: 7-9, 11
+
+           BsonString masterKeyRegion = new BsonString("<Master Key AWS Region>"); // e.g. "us-east-2"
+           BsonString awsAccessKeyId = new BsonString("<IAM User Access Key ID>");
+           BsonString awsSecretAccessKey = new BsonString("<IAM User Secret Access Key>");
+           Map<String, Map<String, Object>> kmsProviders = new HashMap<String, Map<String, Object>>();
+           Map<String, Object> providerDetails = new HashMap<String, Object>();
+
+           providerDetails.put("accessKeyId", awsAccessKeyId);
+           providerDetails.put("secretAccessKey", awsSecretAccessKey);
+           providerDetails.put("region", masterKeyRegion);
+
+           kmsProviders.put("aws", providerDetails);
      .. tab::
         :tabid: nodejs
 
@@ -100,7 +101,7 @@ content: |
         :tabid: java-sync
 
         .. code-block:: Java
-           :emphasize-lines: 9-14, 17
+           :emphasize-lines: 9-14, 16-17
 
            ClientEncryption clientEncryption = ClientEncryptions.create(ClientEncryptionSettings.builder()
                .keyVaultMongoClientSettings(MongoClientSettings.builder()
@@ -110,12 +111,12 @@ content: |
                .kmsProviders(kmsProviders)
                .build());
 
-           final BsonString masterKeyRegion = new BsonString("<Master Key AWS Region>"); // e.g. "us-east-2"
-           final BsonString masterKeyArn = new BsonString("<Master Key ARN>"); // e.g. "arn:aws:kms:us-east-2:111122223333:alias/test-key"
-           DataKeyOptions dataKeyOptions = new DataKeyOptions().masterKey(new BsonDocument() {{
-             put("region", masterKeyRegion);
-             put("key", masterKeyArn);
-           }})
+           BsonString masterKeyRegion = new BsonString("<Master Key AWS Region>"); // e.g. "us-east-2"
+           BsonString masterKeyArn = new BsonString("<Master Key ARN>"); // e.g. "arn:aws:kms:us-east-2:111122223333:alias/test-key"
+           DataKeyOptions dataKeyOptions = new DataKeyOptions().masterKey(
+               new BsonDocument()
+                   .append("region", masterKeyRegion)
+                   .append("key", masterKeyArn));
 
            BsonBinary dataKeyId = clientEncryption.createDataKey("aws", dataKeyOptions);
            String base64DataKeyId = Base64.getEncoder().encodeToString(dataKeyId.getData());

source/includes/steps-fle-create-data-encryption-key.yaml

@@ -11,19 +11,23 @@ content: |
         :tabid: java-sync
 
         .. code-block:: java
-           :emphasize-lines: 11
+           :emphasize-lines: 6
 
            String path = "master-key.txt";
 
-           byte[] fileBytes = new byte[96];
+           byte[] localMasterKey= new byte[96];
 
            try (FileInputStream fis = new FileInputStream(path)) {
-             fileBytes = fis.readAllBytes();
-           } catch (IOException e) {
-             e.printStackTrace();
+               fis.readNBytes(localMasterKey, 0, 96);
            }
+        .. note::
 
-           final byte[] localMasterKey = Arrays.copyOf(fileBytes, 96);
+           The `FileInputStream#readNBytes <https://docs.oracle.com/javase/9/docs/api/java/io/InputStream.html#readNBytes-byte:A-int-int->`_
+           method was introduced in Java 9. The helper method is used in
+           this guide to keep the implementation concise. If you are using
+           JDK 8, you may consider
+           `implementing a custom solution <https://stackoverflow.com/questions/858980/file-to-byte-in-java>`_
+           to read a file into a byte array.
      .. tab::
         :tabid: nodejs
 
@@ -62,15 +66,13 @@ content: |
         for the ClientEncryptionSettings Builder.
 
         .. code-block:: java
-           :emphasize-lines: 4,5
+           :emphasize-lines: 2,5
 
-           String kmsProvider = "local";
+           Map<String, Object> keyMap = new HashMap<String, Object>();
+           keyMap.put("key", localMasterKey);
 
-           Map<String, Map<String, Object>> kmsProviders = new HashMap<String, Map<String, Object>>() {{
-             put(kmsProvider, new HashMap<String, Object>() {{
-               put("key", localMasterKey);
-             }});
-           }};
+           Map<String, Map<String, Object>> kmsProviders = new HashMap<String, Map<String, Object>>();
+           kmsProviders.put("local", keyMap);
      .. tab::
         :tabid: nodejs
 
@@ -115,18 +117,18 @@ content: |
            String keyVaultNamespace = "encryption.__keyVault";
 
            ClientEncryptionSettings clientEncryptionSettings = ClientEncryptionSettings.builder()
-             .keyVaultMongoClientSettings(MongoClientSettings.builder()
-               .applyConnectionString(new ConnectionString(connectionString))
-               .build())
-             .keyVaultNamespace(keyVaultNamespace)
-             .kmsProviders(kmsProviders)
-             .build();
+               .keyVaultMongoClientSettings(MongoClientSettings.builder()
+                   .applyConnectionString(new ConnectionString(connectionString))
+                   .build())
+               .keyVaultNamespace(keyVaultNamespace)
+               .kmsProviders(kmsProviders)
+               .build();
 
            ClientEncryption clientEncryption = ClientEncryptions.create(clientEncryptionSettings);
            BsonBinary dataKeyId = clientEncryption.createDataKey(kmsProvider, new DataKeyOptions());
            System.out.println("DataKeyId [UUID]: " + dataKeyId.asUuid());
 
-           final String base64DataKeyId = Base64.getEncoder().encodeToString(dataKeyId.getData());
+           String base64DataKeyId = Base64.getEncoder().encodeToString(dataKeyId.getData());
            System.out.println("DataKeyId [base64]: " + base64DataKeyId);
 
         The ``createDataKey()`` method returns a :java-docs-latest:`BsonBinary
@@ -190,7 +192,7 @@ content: |
 
            client = MongoClient(connection_string)
            client_encryption = ClientEncryption(
-               kms_providers,  # pass in the kms_providers variable from  the previous step
+               kms_providers, # pass in the kms_providers variable from the previous step
                key_vault_namespace,
                client,
                CodecOptions(uuid_representation=STANDARD)
@@ -338,7 +340,7 @@ content: |
                _bsontype: 'Binary',
                sub_type: 0,
                position: 160,
-               buffer: <Buffer f1 4a 9f bd aa ac c9 89 e9 b3 da 48 72 8e a8 62 97 2a 4a a0 d2 d4 2d a8 f0 74 9c 16 4d  2c 95 34 19 22 05 05 84 0e 41 42 12 1e e3 b5 f0 b1 c5 a8 37 b8 ... 110 more bytes>
+               buffer: <Buffer f1 4a 9f bd aa ac c9 89 e9 b3 da 48 72 8e a8 62 97 2a 4a a0 d2 d4 2d a8 f0 74 9c 16 4d 2c 95 34 19 22 05 05 84 0e 41 42 12 1e e3 b5 f0 b1 c5 a8 37 b8 ... 110 more bytes>
              },
              creationDate: 2019-09-25T22:22:54.017Z,
              updateDate: 2019-09-25T22:22:54.017Z,

source/use-cases/client-side-field-level-encryption-guide.txt

@@ -181,8 +181,21 @@ Additional Dependencies
    .. tab::
       :tabid: java-sync
 
-      No additional dependencies are required for the Java driver.
+      .. list-table::
+         :header-rows: 1
 
+         * - Dependency Name
+           - Description
+
+         * - `JDK 8 or later
+             <https://www.oracle.com/technetwork/java/javase/downloads/index.html>`_
+           - While the current driver is compatible with older versions of
+             the JDK, the CSFLE feature is only compatible with JDK 8
+             and later.
+
+         * - :java-docs-latest:`libmongocrypt <driver/tutorials/client-side-encryption/>`
+           - The `libmongocrypt` library contains bindings to communicate
+             with the native library that manages the encryption.
    .. tab::
       :tabid: nodejs
 
@@ -251,17 +264,15 @@ To begin development, MedcoMD engineers generate a locally-managed master key:
         import java.security.SecureRandom;
 
         public class CreateMasterKeyFile {
-          public static void main(final String[] args) {
+            public static void main(String[] args) throws IOException {
 
-            final byte[] localMasterKey = new byte[96];
-            new SecureRandom().nextBytes(localMasterKey);
+                byte[] localMasterKey = new byte[96];
+                new SecureRandom().nextBytes(localMasterKey);
 
-            try (FileOutputStream stream = new FileOutputStream("master-key.txt")) {
-              stream.write(localMasterKey);
-            } catch (IOException e)  {
-              e.printStackTrace();
+                try (FileOutputStream stream = new FileOutputStream("master-key.txt")) {
+                    stream.write(localMasterKey);
+                }
             }
-          }
         }
    .. tab::
       :tabid: nodejs
@@ -597,15 +608,18 @@ MedcoMD engineers write a function to create a new patient record:
              int policyNumber,
              String provider
          ) {
+
+             Document insurance = new Document()
+                 .append("policyNumber", policyNumber)
+                 .append("provider", provider);
+
              Document patient = new Document()
                  .append("name", name)
                  .append("ssn", ssn)
                  .append("bloodType", bloodType)
-                 .append("medicalRecords", medicalRecords);
-             Document insurance = new Document()
-                 .append("policyNumber", policyNumber)
-                 .append("provider", provider)
+                 .append("medicalRecords", medicalRecords)
                  .append("insurance", insurance);
+
              collection.insertOne(patient);
          }
    .. tab::