docs: Add Java docs (#229)

Co-authored-by: Tony Knapp <[email protected]>
Co-authored-by: Andrew Jewell <[email protected]>

Author: 3 people

DynamoDbEncryption/dafny/DynamoDbEncryption/Model/DynamoDbEncryption.smithy

@@ -3,6 +3,7 @@
 namespace aws.cryptography.dbEncryptionSdk.dynamoDb.itemEncryptor
 
 use aws.polymorph#localService
+use aws.polymorph#javadoc
 
 use com.amazonaws.dynamodb#DynamoDB_20120810
 use com.amazonaws.dynamodb#AttributeMap
@@ -39,6 +40,7 @@ service DynamoDbItemEncryptor {
     errors: [DynamoDbItemEncryptorException],
 }
 
+@javadoc("The configuration for the client-side encryption of DynamoDB items.")
 structure DynamoDbItemEncryptorConfig {
     //= specification/dynamodb-encryption-client/ddb-table-encryption-config.md#structure
     //= type=implication
@@ -59,43 +61,54 @@ structure DynamoDbItemEncryptorConfig {
     //# - [Plaintext Policy](#plaintext-policy)
 
     @required
+    @javadoc("The logical table name for this table. This is the name that is cryptographically bound with your data. This can be the same as the actual DynamoDB table name. It's purpose is to be distinct from the DynamoDB table name so that the data may still be authenticated if being read from different (but logically similar) tables, such as a backup table.")
     logicalTableName: String,
 
     //= specification/dynamodb-encryption-client/ddb-table-encryption-config.md#dynamodb-partition-key-name
     //= type=implication
     //# This Partition Key Name MUST be a valid DynamoDB Key Schema Attribute Name
     @required
+    @javadoc("The name of the partition key on the table this item will be written to or was read from.")
     partitionKeyName: KeySchemaAttributeName,
 
     //= specification/dynamodb-encryption-client/ddb-table-encryption-config.md#dynamodb-sort-key-name
     //= type=implication
     //# This Sort Key Name MUST be a valid DynamoDB Key Schema Attribute Name
+    @javadoc("If this table contains a sort key, the name of the sort key on the table this item will be written to or was read from.")
     sortKeyName: KeySchemaAttributeName,
 
     @required
+    @javadoc("A map that describes what attributes should be encrypted and/or signed on encrypt. This map must contain all attributes that might be encountered during encryption.")
     attributeActionsOnEncrypt: AttributeActions,
 
     //= specification/dynamodb-encryption-client/ddb-table-encryption-config.md#unauthenticated-attributes
     //= type=implication
     //# Unauthenticated Attributes MUST be a set of Attribute Names.
+    @javadoc("A list of attribute names such that, if encountered during decryption, those attributes are treated as unsigned.")
     allowedUnsignedAttributes: AttributeNameList,
 
     //= specification/dynamodb-encryption-client/ddb-table-encryption-config.md#unauthenticated-attribute-prefix
     //= type=implication
     //# Unauthenticated Attribute Prefix MUST be a string.
+    @javadoc("A prefix such that, if during decryption any attribute has a name with this prefix, it is treated as unsigned.")
     allowedUnsignedAttributePrefix: String,
 
     //= specification/dynamodb-encryption-client/ddb-table-encryption-config.md#algorithm-suite
     //= type=implication
     //# This algorithm suite MUST be a [Structured Encryption Library Supported algorithm suite](../../submodules/MaterialProviders/aws-encryption-sdk-specification/framework/algorithm-suites.md).
+    @javadoc("An ID for the algorithm suite to use during encryption and decryption.")
     algorithmSuiteId: DBEAlgorithmSuiteId,
 
     // Requires a Keyring XOR a CMM
+    @javadoc("The Keyring that should be used to wrap and unwrap data keys. If specified a Default Cryptographic Materials Manager with this Keyring is used to obtain materials for encryption and decryption. Either a Keyring or a Cryptographic Materials Manager must be specified.")
     keyring: KeyringReference,
+    @javadoc("The Cryptographic Materials Manager that is used to obtain materials for encryption and decryption.  Either a Keyring or a Cryptographic Materials Manager must be specified.")
     cmm: CryptographicMaterialsManagerReference,
 
+    @javadoc("A configuration that override encryption and/or decryption to instead perform legacy encryption and/or decryption. Used as part of migration from version 2.x to version 3.x.")
     legacyOverride: LegacyOverride,
 
+    @javadoc("A configuration that override encryption and/or decryption to instead passthrough and write and/or read plaintext. Used to update plaintext tables to fully use client-side encryption.")
     plaintextOverride: PlaintextOverride,
 }
 
@@ -108,20 +121,26 @@ structure DynamoDbItemEncryptorConfig {
 //#     calculated using the Crypto Legend in the header, the signature scope used for decryption, and the data in the structure,
 //#     converted into Attribute Actions.
 //#   - [Encrypted Data Keys](./header.md#encrypted-data-keys): The Encrypted Data Keys stored in the header.
+@javadoc("A parsed version of the header that was written with or read on an encrypted DynamoDB item.")
 structure ParsedHeader {
     @required
+    @javadoc("The non-DO_NOTHING Crypto Actions that were configured when this item was originally encrypted.")
     attributeActionsOnEncrypt: AttributeActions,
     @required
+    @javadoc("The ID of the algorithm suite that was used to encrypt this item.")
     algorithmSuiteId: DBEAlgorithmSuiteId,
     @required
+    @javadoc("The encrypted data keys that are stored in the header of this item.")
     encryptedDataKeys: EncryptedDataKeyList,
     @required
+    @javadoc("The portion of the encryption context that was stored in the header of this item.")
     storedEncryptionContext: EncryptionContext
 }
 
 //= specification/dynamodb-encryption-client/ddb-item-encryptor.md#encryptitem
 //= type=implication
 //# The DynamoDB Item Encryptor MUST provide a function that adheres to [EncryptItem](./encrypt-item.md).
+@javadoc("Encrypt a DynamoDB Item.")
 operation EncryptItem {
     input: EncryptItemInput,
     output: EncryptItemOutput,
@@ -130,6 +149,7 @@ operation EncryptItem {
 //= specification/dynamodb-encryption-client/ddb-item-encryptor.md#decryptitem
 //= type=implication
 //# The DynamoDB Item Encryptor MUST provide a function that adheres to [DecryptItem](./decrypt-item.md).
+@javadoc("Decrypt a DynamoDB Item.")
 operation DecryptItem {
     input: DecryptItemInput,
     output: DecryptItemOutput,
@@ -139,37 +159,47 @@ operation DecryptItem {
 //= type=implication
 //# The following inputs to this behavior are REQUIRED:
 //# - DynamoDB Item
+@javadoc("Inputs for encrypting a DynamoDB Item.")
 structure EncryptItemInput {
     @required
+    @javadoc("The DynamoDB item to encrypt.")
     plaintextItem: AttributeMap,
 }
 
+@javadoc("Outputs for encrypting a DynamoDB Item.")
 structure EncryptItemOutput {
     @required
+    @javadoc("The encrypted DynamoDB item.")
     encryptedItem: AttributeMap,
 
     // MAY be None if in plaintext/legacy mode
+    @javadoc("A parsed version of the header written with the encrypted DynamoDB item.")
     parsedHeader: ParsedHeader,
 }
 
 //= specification/dynamodb-encryption-client/decrypt-item.md#input
 //= type=implication
 //# The following inputs to this behavior are REQUIRED:
 //# - DynamoDB Item
+@javadoc("Inputs for decrypting a DynamoDB Item.")
 structure DecryptItemInput {
     @required
+    @javadoc("The encrypted DynamoDB item to decrypt.")
     encryptedItem: AttributeMap,
 }
 
+@javadoc("Outputs for decrypting a DynamoDB Item.")
 structure DecryptItemOutput {
     //= specification/dynamodb-encryption-client/decrypt-item.md#output
     //= type=implication
     //# This operation MUST output the following:
     //#   - [DynamoDb Item](#dynamodb-item-1)
     @required
+    @javadoc("The decrypted DynamoDB item.")
     plaintextItem: AttributeMap,
 
     // MAY be None if in plaintext/legacy mode
+    @javadoc("A parsed version of the header on the encrypted DynamoDB item.")
     parsedHeader: ParsedHeader,
 }
 

DynamoDbEncryption/dafny/DynamoDbItemEncryptor/Model/DynamoDbItemEncryptor.smithy

@@ -24,6 +24,8 @@ java {
     sourceSets["test"].java {
         srcDir("src/test")
     }
+    withJavadocJar()
+    withSourcesJar()
 }
 
 var caUrl: URI? = null
@@ -117,6 +119,12 @@ tasks.withType<JavaCompile>() {
     options.encoding = "UTF-8"
 }
 
+tasks.withType<Jar>() {
+    // to compile a sources jar we need a strategy on how to deal with duplicates;
+    // we choose to include duplicate classes.
+    duplicatesStrategy = DuplicatesStrategy.INCLUDE
+}
+
 tasks.test {
     useTestNG()
     dependsOn("CopyDynamoDb")
@@ -170,3 +178,10 @@ tasks.register<Copy>("CopyDynamoDb")  {
     }
     into("build/libs")
 }
+
+tasks.javadoc {
+    options {
+        (this as CoreJavadocOptions).addStringOption("Xdoclint:none", "-quiet")
+    }
+    exclude("src/main/dafny-generated")
+}

DynamoDbEncryption/runtimes/java/build.gradle.kts

@@ -18,8 +18,8 @@ public class DynamoDbEncryption {
   private final IDynamoDbEncryptionClient _impl;
 
   protected DynamoDbEncryption(BuilderImpl builder) {
-    DynamoDbEncryptionConfig nativeValue = builder.DynamoDbEncryptionConfig();
-    software.amazon.cryptography.dbencryptionsdk.dynamodb.internaldafny.types.DynamoDbEncryptionConfig dafnyValue = ToDafny.DynamoDbEncryptionConfig(nativeValue);
+    DynamoDbEncryptionConfig input = builder.DynamoDbEncryptionConfig();
+    software.amazon.cryptography.dbencryptionsdk.dynamodb.internaldafny.types.DynamoDbEncryptionConfig dafnyValue = ToDafny.DynamoDbEncryptionConfig(input);
     Result<DynamoDbEncryptionClient, Error> result = __default.DynamoDbEncryption(dafnyValue);
     if (result.is_Failure()) {
       throw ToNative.Error(result.dtor_error());
@@ -35,9 +35,15 @@ public static Builder builder() {
     return new BuilderImpl();
   }
 
+  /**
+   * Create a Branch Key Supplier for use with the Hierarchical Keyring that decides what Branch Key to use based on the primary key of the DynamoDB item being read or written.
+   *
+   * @param input Inputs for creating a Branch Key Supplier from a DynamoDB Key Branch Key Id Supplier
+   * @return Outputs for creating a Branch Key Supplier from a DynamoDB Key Branch Key Id Supplier
+   */
   public CreateDynamoDbEncryptionBranchKeyIdSupplierOutput CreateDynamoDbEncryptionBranchKeyIdSupplier(
-      CreateDynamoDbEncryptionBranchKeyIdSupplierInput nativeValue) {
-    software.amazon.cryptography.dbencryptionsdk.dynamodb.internaldafny.types.CreateDynamoDbEncryptionBranchKeyIdSupplierInput dafnyValue = ToDafny.CreateDynamoDbEncryptionBranchKeyIdSupplierInput(nativeValue);
+      CreateDynamoDbEncryptionBranchKeyIdSupplierInput input) {
+    software.amazon.cryptography.dbencryptionsdk.dynamodb.internaldafny.types.CreateDynamoDbEncryptionBranchKeyIdSupplierInput dafnyValue = ToDafny.CreateDynamoDbEncryptionBranchKeyIdSupplierInput(input);
     Result<software.amazon.cryptography.dbencryptionsdk.dynamodb.internaldafny.types.CreateDynamoDbEncryptionBranchKeyIdSupplierOutput, Error> result = this._impl.CreateDynamoDbEncryptionBranchKeyIdSupplier(dafnyValue);
     if (result.is_Failure()) {
       throw ToNative.Error(result.dtor_error());

DynamoDbEncryption/runtimes/java/src/main/smithy-generated/software/amazon/cryptography/dbencryptionsdk/dynamodb/DynamoDbEncryption.java

@@ -39,9 +39,15 @@ public software.amazon.cryptography.dbencryptionsdk.dynamodb.internaldafny.types
     return this._impl;
   }
 
+  /**
+   * Get the Branch Key that should be used for wrapping and unwrapping data keys based on the primary key of the item being read or written.
+   *
+   * @param input Inputs for getting the Branch Key that should be used for wrapping and unwrapping data keys.
+   * @return Outputs for getting the Branch Key that should be used for wrapping and unwrapping data keys.
+   */
   public GetBranchKeyIdFromDdbKeyOutput GetBranchKeyIdFromDdbKey(
-      GetBranchKeyIdFromDdbKeyInput nativeValue) {
-    software.amazon.cryptography.dbencryptionsdk.dynamodb.internaldafny.types.GetBranchKeyIdFromDdbKeyInput dafnyValue = ToDafny.GetBranchKeyIdFromDdbKeyInput(nativeValue);
+      GetBranchKeyIdFromDdbKeyInput input) {
+    software.amazon.cryptography.dbencryptionsdk.dynamodb.internaldafny.types.GetBranchKeyIdFromDdbKeyInput dafnyValue = ToDafny.GetBranchKeyIdFromDdbKeyInput(input);
     Result<software.amazon.cryptography.dbencryptionsdk.dynamodb.internaldafny.types.GetBranchKeyIdFromDdbKeyOutput, Error> result = this._impl.GetBranchKeyIdFromDdbKey(dafnyValue);
     if (result.is_Failure()) {
       throw ToNative.Error(result.dtor_error());

DynamoDbEncryption/runtimes/java/src/main/smithy-generated/software/amazon/cryptography/dbencryptionsdk/dynamodb/DynamoDbKeyBranchKeyIdSupplier.java

@@ -7,6 +7,11 @@
 import software.amazon.cryptography.dbencryptionsdk.dynamodb.model.GetBranchKeyIdFromDdbKeyOutput;
 
 public interface IDynamoDbKeyBranchKeyIdSupplier {
-  GetBranchKeyIdFromDdbKeyOutput GetBranchKeyIdFromDdbKey(
-      GetBranchKeyIdFromDdbKeyInput nativeValue);
+  /**
+   * Get the Branch Key that should be used for wrapping and unwrapping data keys based on the primary key of the item being read or written.
+   *
+   * @param input Inputs for getting the Branch Key that should be used for wrapping and unwrapping data keys.
+   * @return Outputs for getting the Branch Key that should be used for wrapping and unwrapping data keys.
+   */
+  GetBranchKeyIdFromDdbKeyOutput GetBranchKeyIdFromDdbKey(GetBranchKeyIdFromDdbKeyInput input);
 }

DynamoDbEncryption/runtimes/java/src/main/smithy-generated/software/amazon/cryptography/dbencryptionsdk/dynamodb/IDynamoDbKeyBranchKeyIdSupplier.java

@@ -20,8 +20,8 @@ public class DynamoDbItemEncryptor {
   private final IDynamoDbItemEncryptorClient _impl;
 
   protected DynamoDbItemEncryptor(BuilderImpl builder) {
-    DynamoDbItemEncryptorConfig nativeValue = builder.DynamoDbItemEncryptorConfig();
-    software.amazon.cryptography.dbencryptionsdk.dynamodb.itemencryptor.internaldafny.types.DynamoDbItemEncryptorConfig dafnyValue = ToDafny.DynamoDbItemEncryptorConfig(nativeValue);
+    DynamoDbItemEncryptorConfig input = builder.DynamoDbItemEncryptorConfig();
+    software.amazon.cryptography.dbencryptionsdk.dynamodb.itemencryptor.internaldafny.types.DynamoDbItemEncryptorConfig dafnyValue = ToDafny.DynamoDbItemEncryptorConfig(input);
     Result<DynamoDbItemEncryptorClient, Error> result = __default.DynamoDbItemEncryptor(dafnyValue);
     if (result.is_Failure()) {
       throw ToNative.Error(result.dtor_error());
@@ -37,17 +37,29 @@ public static Builder builder() {
     return new BuilderImpl();
   }
 
-  public DecryptItemOutput DecryptItem(DecryptItemInput nativeValue) {
-    software.amazon.cryptography.dbencryptionsdk.dynamodb.itemencryptor.internaldafny.types.DecryptItemInput dafnyValue = ToDafny.DecryptItemInput(nativeValue);
+  /**
+   * Decrypt a DynamoDB Item.
+   *
+   * @param input Inputs for decrypting a DynamoDB Item.
+   * @return Outputs for decrypting a DynamoDB Item.
+   */
+  public DecryptItemOutput DecryptItem(DecryptItemInput input) {
+    software.amazon.cryptography.dbencryptionsdk.dynamodb.itemencryptor.internaldafny.types.DecryptItemInput dafnyValue = ToDafny.DecryptItemInput(input);
     Result<software.amazon.cryptography.dbencryptionsdk.dynamodb.itemencryptor.internaldafny.types.DecryptItemOutput, Error> result = this._impl.DecryptItem(dafnyValue);
     if (result.is_Failure()) {
       throw ToNative.Error(result.dtor_error());
     }
     return ToNative.DecryptItemOutput(result.dtor_value());
   }
 
-  public EncryptItemOutput EncryptItem(EncryptItemInput nativeValue) {
-    software.amazon.cryptography.dbencryptionsdk.dynamodb.itemencryptor.internaldafny.types.EncryptItemInput dafnyValue = ToDafny.EncryptItemInput(nativeValue);
+  /**
+   * Encrypt a DynamoDB Item.
+   *
+   * @param input Inputs for encrypting a DynamoDB Item.
+   * @return Outputs for encrypting a DynamoDB Item.
+   */
+  public EncryptItemOutput EncryptItem(EncryptItemInput input) {
+    software.amazon.cryptography.dbencryptionsdk.dynamodb.itemencryptor.internaldafny.types.EncryptItemInput dafnyValue = ToDafny.EncryptItemInput(input);
     Result<software.amazon.cryptography.dbencryptionsdk.dynamodb.itemencryptor.internaldafny.types.EncryptItemOutput, Error> result = this._impl.EncryptItem(dafnyValue);
     if (result.is_Failure()) {
       throw ToNative.Error(result.dtor_error());
@@ -60,8 +72,14 @@ protected IDynamoDbItemEncryptorClient impl() {
   }
 
   public interface Builder {
+    /**
+     * @param DynamoDbItemEncryptorConfig The configuration for the client-side encryption of DynamoDB items.
+     */
     Builder DynamoDbItemEncryptorConfig(DynamoDbItemEncryptorConfig DynamoDbItemEncryptorConfig);
 
+    /**
+     * @return The configuration for the client-side encryption of DynamoDB items.
+     */
     DynamoDbItemEncryptorConfig DynamoDbItemEncryptorConfig();
 
     DynamoDbItemEncryptor build();

DynamoDbEncryption/runtimes/java/src/main/smithy-generated/software/amazon/cryptography/dbencryptionsdk/dynamodb/itemencryptor/DynamoDbItemEncryptor.java

@@ -7,13 +7,22 @@
 import java.util.Objects;
 import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
 
+/**
+ * Inputs for decrypting a DynamoDB Item.
+ */
 public class DecryptItemInput {
+  /**
+   * The encrypted DynamoDB item to decrypt.
+   */
   private final Map<String, AttributeValue> encryptedItem;
 
   protected DecryptItemInput(BuilderImpl builder) {
     this.encryptedItem = builder.encryptedItem();
   }
 
+  /**
+   * @return The encrypted DynamoDB item to decrypt.
+   */
   public Map<String, AttributeValue> encryptedItem() {
     return this.encryptedItem;
   }
@@ -27,8 +36,14 @@ public static Builder builder() {
   }
 
   public interface Builder {
+    /**
+     * @param encryptedItem The encrypted DynamoDB item to decrypt.
+     */
     Builder encryptedItem(Map<String, AttributeValue> encryptedItem);
 
+    /**
+     * @return The encrypted DynamoDB item to decrypt.
+     */
     Map<String, AttributeValue> encryptedItem();
 
     DecryptItemInput build();