docs: JavaDoc (#196)

Added JavaDoc comments to multiple classes and methods across the SDK,
providing detailed descriptions of their functionality and usage. This
enhances the readability and maintainability of the code.

DSP-119

Author: pflynn-virtru

sdk/src/main/java/io/opentdf/platform/sdk/AesGcm.java

@@ -12,6 +12,11 @@
 import java.security.NoSuchAlgorithmException;
 import java.security.SecureRandom;
 
+/**
+ * The AesGcm class provides encryption and decryption methods using AES-GCM mode.
+ * It includes methods to encrypt and decrypt byte arrays using a specified
+ * symmetric key.
+ */
 public class AesGcm {
     public static final int GCM_NONCE_LENGTH = 12; // in bytes
     public static final int GCM_TAG_LENGTH = 16; // in bytes

sdk/src/main/java/io/opentdf/platform/sdk/AssertionConfig.java

@@ -3,6 +3,10 @@
 
 import java.util.Objects;
 
+/**
+ * Represents the configuration for assertions, encapsulating various types, scopes, states, keys,
+ * and statements involved in assertion handling.
+ */
 public class AssertionConfig {
 
     public enum Type {

sdk/src/main/java/io/opentdf/platform/sdk/AsymDecryption.java

@@ -9,6 +9,9 @@
 import java.security.spec.PKCS8EncodedKeySpec;
 import java.util.Base64;
 
+/**
+ * Class providing functionality for asymmetric decryption using an RSA private key.
+ */
 public class AsymDecryption {
     private final PrivateKey privateKey;
     private static final String PRIVATE_KEY_HEADER = "-----BEGIN PRIVATE KEY-----";

sdk/src/main/java/io/opentdf/platform/sdk/AsymEncryption.java

@@ -15,6 +15,10 @@
 import java.util.Base64;
 import java.util.Objects;
 
+/**
+ * AsymEncryption class provides methods for asymmetric encryption and
+ * handling public keys in PEM format.
+ */
 public class AsymEncryption {
     private final PublicKey publicKey;
     private static final String PUBLIC_KEY_HEADER = "-----BEGIN PUBLIC KEY-----";

sdk/src/main/java/io/opentdf/platform/sdk/AutoConfigureException.java

@@ -1,5 +1,8 @@
 package io.opentdf.platform.sdk;
 
+/**
+ * Exception thrown when automatic configuration fails.
+ */
 public class AutoConfigureException extends RuntimeException  {
     public AutoConfigureException(String message) {
         super(message);

sdk/src/main/java/io/opentdf/platform/sdk/Autoconfigure.java

@@ -35,7 +35,11 @@
 import java.util.regex.Pattern;
 import java.util.stream.Collectors;
 
-// Attribute rule types: operators!
+/**
+ * The RuleType class defines a set of constants that represent various types of attribute rules.
+ * These constants are used to specify the nature and behavior of attribute rules in the context
+ * of key management and policy enforcement.
+ */
 class RuleType {
     public static final String HIERARCHY = "hierarchy";
     public static final String ALL_OF = "allOf";
@@ -44,6 +48,12 @@ class RuleType {
     public static final String EMPTY_TERM = "DEFAULT";
 }
 
+/**
+ * The Autoconfigure class provides methods for configuring and retrieving
+ * grants related to attribute values and KAS (Key Access Server) keys.
+ * This class includes functionality to create granter instances based on
+ * attributes either from a list of attribute values or from a service.
+ */
 public class Autoconfigure {
 
     public static Logger logger = LoggerFactory.getLogger(Autoconfigure.class);

sdk/src/main/java/io/opentdf/platform/sdk/Config.java

@@ -10,6 +10,10 @@
 import java.util.*;
 import java.util.function.Consumer;
 
+/**
+ * Configuration class for setting various configurations related to TDF.
+ * Contains nested classes and enums for specific configuration settings.
+ */
 public class Config {
 
     public static final int TDF3_KEY_SIZE = 2048;

sdk/src/main/java/io/opentdf/platform/sdk/CryptoUtils.java

@@ -5,6 +5,9 @@
 import java.security.*;
 import java.util.Base64;
 
+/**
+ * Utility class for cryptographic operations such as generating RSA key pairs and calculating HMAC.
+ */
 public class CryptoUtils {
     private static final int KEYPAIR_SIZE = 2048;
 

sdk/src/main/java/io/opentdf/platform/sdk/InvalidZipException.java

@@ -1,5 +1,10 @@
 package io.opentdf.platform.sdk;
 
+/**
+ * InvalidZipException is thrown to indicate that a ZIP file being read
+ * is invalid or corrupted in some way. This exception extends RuntimeException,
+ * allowing it to be thrown during the normal operation of the Java Virtual Machine.
+ */
 public class InvalidZipException extends RuntimeException {
     public InvalidZipException(String message) {
         super(message);

sdk/src/main/java/io/opentdf/platform/sdk/KASClient.java

@@ -30,6 +30,11 @@
 
 import static java.lang.String.format;
 
+/**
+ * A client implementation that communicates with a Key Access Service (KAS).
+ * This class provides methods to retrieve public keys, unwrap encrypted keys,
+ * and manage key caches.
+ */
 public class KASClient implements SDK.KAS {
 
     private final Function<String, ManagedChannel> channelFactory;

sdk/src/main/java/io/opentdf/platform/sdk/KASKeyCache.java

@@ -8,6 +8,10 @@
 import java.util.HashMap;
 import java.util.Map;
 
+/**
+ * Class representing a cache for KAS (Key Access Server) information.
+ * It stores key information along with a timestamp to manage the freshness of cached data.
+ */
 public class KASKeyCache {
     private static final Logger log = LoggerFactory.getLogger(KASKeyCache.class);
     Map<KASKeyRequest, TimeStampedKASInfo> cache;
@@ -50,6 +54,17 @@ public void store(Config.KASInfo kasInfo) {
     }
 }
 
+/**
+ * A class representing Key Aggregation Service (KAS) information along with a timestamp.
+ * <p>
+ * This class holds information related to KAS, as well as a timestamp indicating when the
+ * information was recorded or generated. It encapsulates two main attributes: {@code kasInfo}
+ * and {@code timestamp}.
+ * <p>
+ * The {@code kasInfo} field is an instance of {@code Config.KASInfo}, which contains the KAS-specific
+ * data. The {@code timestamp} field is an instance of {@code LocalDateTime}, representing
+ * the date and time when the KAS information was recorded.
+ */
 class TimeStampedKASInfo {
     Config.KASInfo kasInfo;
     LocalDateTime timestamp;
@@ -60,6 +75,13 @@ public TimeStampedKASInfo(Config.KASInfo kasInfo, LocalDateTime timestamp) {
     }
 }
 
+/**
+ * Represents a request for a Key Access Server (KAS) key.
+ * This class is used to request keys using a specified URL and algorithm.
+ *
+ * This class also overrides equals and hashCode methods
+ * to ensure proper functioning within hash-based collections.
+ */
 class KASKeyRequest {
     private String url;
     private String algorithm;

sdk/src/main/java/io/opentdf/platform/sdk/Manifest.java

@@ -27,6 +27,10 @@
 import java.util.List;
 import java.util.Objects;
 
+/**
+ * The Manifest class represents a detailed structure encapsulating various aspects
+ * of data integrity, encryption, payload, and assertions within a certain context.
+ */
 public class Manifest {
 
     private static final String kAssertionHash = "assertionHash";

sdk/src/main/java/io/opentdf/platform/sdk/NanoTDF.java

@@ -16,6 +16,11 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * The NanoTDF class provides methods to create and read NanoTDF (Tiny Data Format) files.
+ * The NanoTDF format is intended for securely encrypting small data payloads using elliptic-curve cryptography
+ * and authenticated encryption.
+ */
 public class NanoTDF {
 
     public static Logger logger = LoggerFactory.getLogger(NanoTDF.class);

sdk/src/main/java/io/opentdf/platform/sdk/PolicyObject.java

@@ -2,6 +2,9 @@
 
 import java.util.List;
 
+/**
+ * The PolicyObject class represents a policy with a unique identifier and a body containing data attributes.
+ */
 public class PolicyObject {
     static public class AttributeObject {
         public String attribute;

sdk/src/main/java/io/opentdf/platform/sdk/SDK.java

@@ -34,11 +34,20 @@ public class SDK implements AutoCloseable {
 
     private static final Logger log = LoggerFactory.getLogger(SDK.class);
 
+    /**
+     * Closes the SDK, including its associated services.
+     *
+     * @throws Exception if an error occurs while closing the services.
+     */
     @Override
     public void close() throws Exception {
         services.close();
     }
 
+    /**
+     * KAS (Key Access Service) interface to define methods related to key access and management.
+     * This interface extends AutoCloseable to allow for resource management during close operations.
+     */
     public interface KAS extends AutoCloseable {
         Config.KASInfo getPublicKey(Config.KASInfo kasInfo);
 
@@ -51,7 +60,10 @@ public interface KAS extends AutoCloseable {
         KASKeyCache getKeyCache();
     }
 
-    // TODO: add KAS
+    /**
+     * The Services interface provides access to various gRPC service stubs and a Key Authority Service (KAS).
+     * It extends the AutoCloseable interface, allowing for the release of resources when no longer needed.
+     */
     public interface Services extends AutoCloseable {
         AuthorizationServiceFutureStub authorization();
 

sdk/src/main/java/io/opentdf/platform/sdk/SDKBuilder.java

@@ -69,7 +69,6 @@ public SDKBuilder sslFactory(SSLFactory sslFactory) {
      * Add SSL Context with trusted certs from certDirPath
      * 
      * @param certsDirPath Path to a directory containing .pem or .crt trusted certs
-     * @return
      */
     public SDKBuilder sslFactoryFromDirectory(String certsDirPath) throws Exception {
         File certsDir = new File(certsDirPath);
@@ -91,7 +90,6 @@ public SDKBuilder sslFactoryFromDirectory(String certsDirPath) throws Exception
      * 
      * @param keystorePath     Path to keystore
      * @param keystorePassword Password to keystore
-     * @return
      */
     public SDKBuilder sslFactoryFromKeyStore(String keystorePath, String keystorePassword) {
         this.sslFactory = SSLFactory.builder().withDefaultTrustMaterial().withSystemTrustMaterial()

sdk/src/main/java/io/opentdf/platform/sdk/SDKException.java

@@ -1,5 +1,10 @@
 package io.opentdf.platform.sdk;
 
+/**
+ * SDKException serves as a custom exception class for handling errors
+ * specific to the SDK's operations and processes. It extends
+ * RuntimeException, making it an unchecked exception.
+ */
 public class SDKException extends RuntimeException {
     public SDKException(String message, Exception reason) {
         super(message, reason);

sdk/src/main/java/io/opentdf/platform/sdk/TDF.java

@@ -28,10 +28,23 @@
 import java.util.*;
 import java.util.concurrent.ExecutionException;
 
+/**
+ * The TDF class is responsible for handling operations related to
+ * Trusted Data Format (TDF). It includes methods to create and load
+ * TDF objects, as well as utility functions to handle cryptographic
+ * operations and configurations.
+ */
 public class TDF {
 
     private final long maximumSize;
 
+    /**
+     * Constructs a new TDF instance using the default maximum input size defined by MAX_TDF_INPUT_SIZE.
+     * <p>
+     * This constructor is primarily used to initialize the TDF object with the standard maximum
+     * input size, which controls the maximum size of the input data that can be processed.
+     * For test purposes, an alternative constructor allows for setting a custom maximum input size.
+     */
     public TDF() {
         this(MAX_TDF_INPUT_SIZE);
     }

sdk/src/main/java/io/opentdf/platform/sdk/TDFReader.java

@@ -12,6 +12,11 @@
 import static io.opentdf.platform.sdk.TDFWriter.TDF_MANIFEST_FILE_NAME;
 import static io.opentdf.platform.sdk.TDFWriter.TDF_PAYLOAD_FILE_NAME;
 
+/**
+ * TDFReader is responsible for reading and processing Trusted Data Format (TDF) files.
+ * The class initializes with a TDF file channel, extracts the manifest and payload entries,
+ * and provides methods to retrieve the manifest content, read payload bytes, and read policy objects.
+ */
 public class TDFReader {
 
     private final ZipReader.Entry manifestEntry;

sdk/src/main/java/io/opentdf/platform/sdk/TDFWriter.java

@@ -4,6 +4,10 @@
 import java.io.OutputStream;
 import java.nio.charset.StandardCharsets;
 
+/**
+ * The TDFWriter class provides functionalities for creating a TDF (Trusted Data Format) archive.
+ * This includes appending a manifest file and appending payload data to the archive.
+ */
 public class TDFWriter {
     public static final String TDF_PAYLOAD_FILE_NAME = "0.payload";
     public static final String TDF_MANIFEST_FILE_NAME = "0.manifest.json";

sdk/src/main/java/io/opentdf/platform/sdk/ZipReader.java

@@ -12,6 +12,12 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * The ZipReader class provides functionality to read basic ZIP file
+ * structures, such as the End of Central Directory Record and the
+ * Local File Header. This class supports standard ZIP archives as well
+ * as ZIP64 format.
+ */
 public class ZipReader {
 
     public static final Logger logger = LoggerFactory.getLogger(ZipReader.class);

sdk/src/main/java/io/opentdf/platform/sdk/ZipWriter.java

@@ -9,6 +9,10 @@
 import java.util.ArrayList;
 import java.util.zip.CRC32;
 
+/**
+ * The ZipWriter class provides functionalities to create ZIP archive files.
+ * It writes files and data to an underlying output stream in the ZIP file format.
+ */
 public class ZipWriter {
 
     private static final int ZIP_VERSION = 0x2D;

sdk/src/main/java/io/opentdf/platform/sdk/package-info.java

@@ -0,0 +1,19 @@
+/**
+ * The io.opentdf.platform.sdk package provides a comprehensive set of
+ * classes, interfaces, enums, and exceptions designed for interacting with
+ * the OpenTDF platform. At its core, the {@link io.opentdf.platform.sdk.SDK} class
+ * serves as the centerpiece for this package, representing a software development kit
+ * that facilitates integration with the OpenTDF services. The package also includes
+ * classes for various encryption and decryption operations such as {@link io.opentdf.platform.sdk.AesGcm}
+ * and its inner classes, as well as support for assertions and configurations through
+ * classes like {@link io.opentdf.platform.sdk.AssertionConfig} and {@link io.opentdf.platform.sdk.Config}.
+ * Additionally, utility classes such as {@link io.opentdf.platform.sdk.CryptoUtils} and
+ * functionality for reading and writing TDF files are provided via {@link io.opentdf.platform.sdk.TDFReader}
+ * and {@link io.opentdf.platform.sdk.TDFWriter}. The package also defines a collection of
+ * enums for various configurations and state definitions, alongside a comprehensive
+ * set of exceptions to handle different error scenarios, ensuring robust and secure
+ * operations within the OpenTDF ecosystem.
+ *
+ * @since 1.0
+ */
+package io.opentdf.platform.sdk;