From ed66ccbf7d3819064611ee56b859b113b2709d22 Mon Sep 17 00:00:00 2001 From: Paul Flynn Date: Wed, 16 Oct 2024 14:14:04 -0400 Subject: [PATCH 1/2] Add JavaDoc comments to improve code documentation 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. --- .../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 | 20 ++++++++++++----- .../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, 152 insertions(+), 8 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..6908cf0c 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/SDK.java +++ b/sdk/src/main/java/io/opentdf/platform/sdk/SDK.java @@ -22,10 +22,8 @@ import java.util.Optional; /** - * The SDK class represents a software development kit for interacting with the - * opentdf platform. It - * provides various services and stubs for making API calls to the opentdf - * platform. + * SDK provides an interface for interacting with various services + * and managing resources in a streamlined manner. */ public class SDK implements AutoCloseable { private final Services services; @@ -34,11 +32,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 +58,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 From d6bddfdba0af4393026be32a60ac4242f78b5eee Mon Sep 17 00:00:00 2001 From: Paul Flynn Date: Wed, 16 Oct 2024 14:17:58 -0400 Subject: [PATCH 2/2] rollback --- sdk/src/main/java/io/opentdf/platform/sdk/SDK.java | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) 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 6908cf0c..14affa4c 100644 --- a/sdk/src/main/java/io/opentdf/platform/sdk/SDK.java +++ b/sdk/src/main/java/io/opentdf/platform/sdk/SDK.java @@ -22,8 +22,10 @@ import java.util.Optional; /** - * SDK provides an interface for interacting with various services - * and managing resources in a streamlined manner. + * The SDK class represents a software development kit for interacting with the + * opentdf platform. It + * provides various services and stubs for making API calls to the opentdf + * platform. */ public class SDK implements AutoCloseable { private final Services services;