mirrors/aws-secretsmanager-caching-java

Add PQ-TLS macOS/Windows compatibility note to README (#196)

Description

Why is this change being made?

Users attempting to use PQ-TLS on macOS or Windows may encounter unexpected behavior due to AWS CRT system library dependencies. This note proactively informs users of the known limitation.

What is changing?

1. Added a note in the “Enabling Post-Quantum TLS” section of the README warning that PQ-TLS may not work as expected on macOS or Windows due to AWS CRT system library dependencies, with a reference link.

Issue #, if available:

Testing

How was this tested?

Documentation-only change

When testing locally, provide testing artifact(s):

Verified README renders correctly using VS Code Markdown preview.

Reviewee Checklist

Update the checklist after submitting the PR

I have reviewed, tested and understand all changes If not, why:
I have filled out the Description and Testing sections above If not, why:
Build and Unit tests are passing If not, why:
Unit test coverage check is passing If not, why:
I have ensured no sensitive information is leaking (i.e., no logging of sensitive fields, or otherwise) If not, why:
I have added explanatory comments for complex logic, new classes/methods and new tests If not, why:
I have updated README/documentation (if needed) If not, why:
I have clearly called out breaking changes (if any) If not, why:

Reviewer Checklist

All reviewers please ensure the following are true before reviewing:

Reviewee checklist has been accurately filled out
Code changes align with stated purpose in description
Test coverage adequately validates the changes

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

Co-authored-by: Vedant Jaiswal vedjasy@amazon.com

AWS Secrets Manager Java caching client

The AWS Secrets Manager Java caching client enables in-process caching of secrets for Java applications.

Getting Started

Required Prerequisites

To use this client you must have:

A Java 8 development environment

If you do not have one, go to Java SE Downloads on the Oracle website, then download and install the Java SE Development Kit (JDK). Java 8 or higher is recommended.

An Amazon Web Services (AWS) account to access secrets stored in AWS Secrets Manager and use AWS SDK for Java.

To create an AWS account, go to Sign In or Create an AWS Account and then choose I am a new user. Follow the instructions to create an AWS account.
To create a secret in AWS Secrets Manager, go to Creating Secrets and follow the instructions on that page.
To download and install the AWS SDK for Java, go to Installing the AWS SDK for Java in the AWS SDK for Java documentation and then follow the instructions on that page.

Download

You can get the latest release from Maven:

<dependency>
  <groupId>com.amazonaws.secretsmanager</groupId>
  <artifactId>aws-secretsmanager-caching-java</artifactId>
  <version>2.2.0</version>
</dependency>

Don’t forget to enable the download of snapshot jars from Maven:

<profiles>
  <profile>
    <id>allow-snapshots</id>
    <activation><activeByDefault>true</activeByDefault></activation>
    <repositories>
      <repository>
        <id>snapshots-repo</id>
        <url>https://aws.oss.sonatype.org/content/repositories/snapshots</url>
        <releases><enabled>false</enabled></releases>
        <snapshots><enabled>true</enabled></snapshots>
      </repository>
    </repositories>
  </profile>
</profiles>

Get Started

The following code sample demonstrates how to get started:

Instantiate the caching client.
Request secret.

// This example shows how an AWS Lambda function can be written
// to retrieve a cached secret from AWS Secrets Manager caching
// client.
package com.amazonaws.secretsmanager.caching.examples;

import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import com.amazonaws.services.lambda.runtime.LambdaLogger;

import com.amazonaws.secretsmanager.caching.SecretCache;

/**
 * SampleClass.
 */
public class SampleClass implements RequestHandler<String, String> {

    private final SecretCache cache = new SecretCache();

    @Override
    public String handleRequest(String secretId, Context context) {
        final String secret = cache.getSecretString(secretId);
        // Use secret to connect to secured resource.
        return "Success!";
    }
}

Enabling Post-Quantum TLS

To enable Post-Quantum TLS for enhanced security:

import com.amazonaws.secretsmanager.caching.SecretCache;
import com.amazonaws.secretsmanager.caching.SecretCacheConfiguration;

SecretCache cache = new SecretCache(
    new SecretCacheConfiguration()
        .withPostQuantumTlsEnabled(true)
);

String secret = cache.getSecretString("my-secret-id");

NOTE: PQ-TLS uses the AWS Common Runtime (CRT) which relies on system libraries and may not work as expected on macOS or Windows at this time (ref).

License

This library is licensed under the Apache 2.0 License.