OpenTDF Java SDK

A Java implementation of the OpenTDF protocol, and access library for the services provided by the OpenTDF platform.

New to the OpenTDF SDK? See the OpenTDF SDK Quickstart Guide for a comprehensive introduction.

This SDK is available from Maven central as:

 <dependency>
<groupId>io.opentdf/platform</groupId>
<artifactId>sdk</artifactId>
</dependency>

Additional Maven Modules

• cmdline: Command line utility

Quick Start Example

This example demonstrates how to create and read TDF (Trusted Data Format) files using the OpenTDF SDK.

Prerequisites: Follow the OpenTDF Quickstart to get a local platform running, or if you already have a hosted version, replace the values with your OpenTDF platform details.

For more code examples, see:

• Creating TDFs
• Managing policy

packageio.opentdf.platform;
importio.opentdf.platform.sdk.Config;
importio.opentdf.platform.sdk.SDK;
importio.opentdf.platform.sdk.SDKBuilder;
importio.opentdf.platform.sdk.TDF;
importjava.io.ByteArrayInputStream;
importjava.io.FileOutputStream;
importjava.nio.channels.FileChannel;
importjava.nio.charset.StandardCharsets;
importjava.nio.file.Path;
importjava.nio.file.Paths;
importjava.nio.file.StandardOpenOption;
publicclassExample {
publicstaticvoidmain(String[] args) throwsException {
// Initialize SDK with platform endpoint and authentication// Replace these values with your actual configuration:StringplatformEndpoint = "localhost:8080"; // Your platform URLStringclientId = "opentdf"; // Your OAuth client IDStringclientSecret = "secret"; // Your OAuth client secretStringkasUrl = "http://localhost:8080/kas"; // Your KAS URLSDKsdk = newSDKBuilder()
.platformEndpoint(platformEndpoint)
.clientSecret(clientId, clientSecret)
.useInsecurePlaintextConnection(true) // Only for local development with HTTP
.build();
// Create a TDF// This attribute is created in the quickstart guideStringdataAttribute = "https://opentdf.io/attr/department/value/finance";
Stringplaintext = "Hello, world!";
varplaintextInputStream = newByteArrayInputStream(plaintext.getBytes(StandardCharsets.UTF_8));
varkasInfo = newConfig.KASInfo();
kasInfo.URL = kasUrl;
vartdfConfig = Config.newTDFConfig(
Config.withKasInformation(kasInfo),
Config.withDataAttributes(dataAttribute)
);
// Write encrypted TDF to filetry (FileOutputStreamout = newFileOutputStream("encrypted.tdf")) {
sdk.createTDF(plaintextInputStream, out, tdfConfig);
}
System.out.println("TDF created successfully");
// Decrypt the TDF// LoadTDF contacts the Key Access Service (KAS) to verify that this client// has been granted access to the data attributes, then decrypts the TDF.// Note: The client must have entitlements configured on the platform first.PathtdfPath = Paths.get("encrypted.tdf");
try (FileChanneltdfChannel = FileChannel.open(tdfPath, StandardOpenOption.READ)) {
TDF.Readerreader = sdk.loadTDF(tdfChannel, Config.newTDFReaderConfig());
// Write the decrypted plaintext to a filetry (FileOutputStreamout = newFileOutputStream("output.txt")) {
reader.readPayload(out);
}
}
System.out.println("Successfully created and decrypted TDF");
}
}

Configuration Values

Replace these placeholder values with your actual configuration:

Variable	Default (Quickstart)	Description
platformEndpoint	localhost:8080	Your OpenTDF platform URL
clientId	opentdf	OAuth client ID (from quickstart)
clientSecret	secret	OAuth client secret (from quickstart)
kasUrl	http://localhost:8080/kas	Your Key Access Service URL
dataAttribute	https://opentdf.io/attr/department/value/finance	Data attribute FQN (created in quickstart)

Before running:

1. Follow the OpenTDF Quickstart to start the platform
2. Create an OAuth client in Keycloak and note the credentials
3. Grant your client entitlements to the department attribute (see Managing policy)

Expected Output:

TDF created successfully
Successfully created and decrypted TDF

The output.txt file will contain the decrypted plaintext: Hello, world!

Cryptography Library

This SDK uses the Bouncy Castle Security library library. Note: When using this SDK, it may be necessary to register the Bouncy Castle Provider as follows:

static {
Security.addProvider(newBouncyCastleProvider());
}

Logging

The Java SDK makes use of the slf4j library, without providing a backend. log4j2 in leveraged within the included automated tests.

SSL - Untrusted Certificates

Leverage the SDKBuilder.withSSL methods to create an SDKBuilder as follows:

• An SSLFactory: sdkBuilder.sslFactory(mySSLFactory)
• Directory containing trusted certificates: sdkBuilder.sslFactoryFromDirectory(myDirectoryWithCerts)
• Java Keystore: sdkBuilder.sslFactoryFromKeyStore(keystorepath, keystorePassword)

Buf

Create an account, link that account with GitHub and then under User settings create a token

[INFO] --- antrun:3.1.0:run (generateSources) @ sdk ---
[INFO] Executing tasks
[INFO] [exec] Failure: too many requests
[INFO] [exec] [INFO] [exec] Please see https://buf.build/docs/bsr/rate-limits for details about BSR rate limiting.

Release Process

SNAPSHOT

Snapshots are from main latest

mvn versions:set -DnewVersion=1.2.3-SNAPSHOT

RELEASE

Releases are from tags created by the GitHub release process. Enter 'Release Please' to trigger the release process.