From 33c9513de68954cccba854d501ba26b62216df89 Mon Sep 17 00:00:00 2001 From: Paul Flynn <43211074+pflynn-virtru@users.noreply.github.com> Date: Fri, 18 Oct 2024 11:03:10 -0400 Subject: [PATCH] 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 --- .../java/io/opentdf/platform/sdk/AesGcm.java | 5 +++++ .../opentdf/platform/sdk/AssertionConfig.java | 4 ++++ .../opentdf/platform/sdk/AsymDecryption.java | 3 +++ .../opentdf/platform/sdk/AsymEncryption.java | 4 ++++ .../platform/sdk/AutoConfigureException.java | 3 +++ .../opentdf/platform/sdk/Autoconfigure.java | 12 +++++++++- .../java/io/opentdf/platform/sdk/Config.java | 4 ++++ .../io/opentdf/platform/sdk/CryptoUtils.java | 3 +++ .../platform/sdk/InvalidZipException.java | 5 +++++ .../io/opentdf/platform/sdk/KASClient.java | 5 +++++ .../io/opentdf/platform/sdk/KASKeyCache.java | 22 +++++++++++++++++++ .../io/opentdf/platform/sdk/Manifest.java | 4 ++++ .../java/io/opentdf/platform/sdk/NanoTDF.java | 5 +++++ .../io/opentdf/platform/sdk/PolicyObject.java | 3 +++ .../java/io/opentdf/platform/sdk/SDK.java | 14 +++++++++++- .../io/opentdf/platform/sdk/SDKBuilder.java | 2 -- .../io/opentdf/platform/sdk/SDKException.java | 5 +++++ .../java/io/opentdf/platform/sdk/TDF.java | 13 +++++++++++ .../io/opentdf/platform/sdk/TDFReader.java | 5 +++++ .../io/opentdf/platform/sdk/TDFWriter.java | 4 ++++ .../io/opentdf/platform/sdk/ZipReader.java | 6 +++++ .../io/opentdf/platform/sdk/ZipWriter.java | 4 ++++ .../io/opentdf/platform/sdk/package-info.java | 19 ++++++++++++++++ 23 files changed, 150 insertions(+), 4 deletions(-) create mode 100644 sdk/src/main/java/io/opentdf/platform/sdk/package-info.java diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/AesGcm.java b/sdk/src/main/java/io/opentdf/platform/sdk/AesGcm.java index 0d79c460..71445f69 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/AesGcm.java +++ b/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 diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/AssertionConfig.java b/sdk/src/main/java/io/opentdf/platform/sdk/AssertionConfig.java index 510a008c..100f824f 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/AssertionConfig.java +++ b/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 { diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/AsymDecryption.java b/sdk/src/main/java/io/opentdf/platform/sdk/AsymDecryption.java index b7eb1e92..b76d1523 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/AsymDecryption.java +++ b/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-----"; diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/AsymEncryption.java b/sdk/src/main/java/io/opentdf/platform/sdk/AsymEncryption.java index 415fc375..3a81b1f5 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/AsymEncryption.java +++ b/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-----"; diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/AutoConfigureException.java b/sdk/src/main/java/io/opentdf/platform/sdk/AutoConfigureException.java index c134806c..157e6a8a 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/AutoConfigureException.java +++ b/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); diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/Autoconfigure.java b/sdk/src/main/java/io/opentdf/platform/sdk/Autoconfigure.java index 372daee2..6113a681 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/Autoconfigure.java +++ b/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); diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/Config.java b/sdk/src/main/java/io/opentdf/platform/sdk/Config.java index a8766820..c7d4f092 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/Config.java +++ b/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; diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/CryptoUtils.java b/sdk/src/main/java/io/opentdf/platform/sdk/CryptoUtils.java index 6a53e7e5..404637df 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/CryptoUtils.java +++ b/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; diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/InvalidZipException.java b/sdk/src/main/java/io/opentdf/platform/sdk/InvalidZipException.java index e8ac4648..8bba58bd 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/InvalidZipException.java +++ b/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); diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/KASClient.java b/sdk/src/main/java/io/opentdf/platform/sdk/KASClient.java index 4732865b..727eda83 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/KASClient.java +++ b/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 channelFactory; diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/KASKeyCache.java b/sdk/src/main/java/io/opentdf/platform/sdk/KASKeyCache.java index 22c4764c..5879dd05 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/KASKeyCache.java +++ b/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 cache; @@ -50,6 +54,17 @@ public void store(Config.KASInfo kasInfo) { } } +/** + * A class representing Key Aggregation Service (KAS) information along with a timestamp. + *

+ * 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}. + *

+ * 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; diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/Manifest.java b/sdk/src/main/java/io/opentdf/platform/sdk/Manifest.java index f9434c6b..bc4c4c3c 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/Manifest.java +++ b/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"; diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/NanoTDF.java b/sdk/src/main/java/io/opentdf/platform/sdk/NanoTDF.java index 9132e570..75d0e734 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/NanoTDF.java +++ b/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); diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/PolicyObject.java b/sdk/src/main/java/io/opentdf/platform/sdk/PolicyObject.java index 15d2d0bb..9d708699 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/PolicyObject.java +++ b/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; diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/SDK.java b/sdk/src/main/java/io/opentdf/platform/sdk/SDK.java index fe2a8005..14affa4c 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/SDK.java +++ b/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(); diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/SDKBuilder.java b/sdk/src/main/java/io/opentdf/platform/sdk/SDKBuilder.java index 4068b5e0..8c6b1804 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/SDKBuilder.java +++ b/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() diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/SDKException.java b/sdk/src/main/java/io/opentdf/platform/sdk/SDKException.java index 2d0b390d..58e7adbe 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/SDKException.java +++ b/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); diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/TDF.java b/sdk/src/main/java/io/opentdf/platform/sdk/TDF.java index ba7c5b97..aec26e80 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/TDF.java +++ b/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. + *

+ * 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); } diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/TDFReader.java b/sdk/src/main/java/io/opentdf/platform/sdk/TDFReader.java index 24b05940..6691888a 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/TDFReader.java +++ b/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; diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/TDFWriter.java b/sdk/src/main/java/io/opentdf/platform/sdk/TDFWriter.java index a5f3509b..048822f6 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/TDFWriter.java +++ b/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"; diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/ZipReader.java b/sdk/src/main/java/io/opentdf/platform/sdk/ZipReader.java index 17bc51c5..cb6d5ffd 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/ZipReader.java +++ b/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); diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/ZipWriter.java b/sdk/src/main/java/io/opentdf/platform/sdk/ZipWriter.java index d775a0a8..71aea34c 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/ZipWriter.java +++ b/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; diff --git a/sdk/src/main/java/io/opentdf/platform/sdk/package-info.java b/sdk/src/main/java/io/opentdf/platform/sdk/package-info.java new file mode 100644 index 00000000..cd3ae44a --- /dev/null +++ b/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; \ No newline at end of file