Quarkus - Amazon KMS Client

AWS Key Management Service (KMS) is a service that allows you to create and control the keys used to encrypt or digitally sign your data. Using KMS, you can create and manage cryptographic keys and control their use across a wide range of AWS services and in your application.

You can find more information about KMS at the AWS KMS website.

The Quarkus extension supports two programming models:

• Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client

• Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client.

In this guide, we see how you can get your REST services to use KMS locally and on AWS.

Prerequisites

To complete this guide, you need:

• JDK 1.8+ installed with JAVA_HOME configured appropriately

• an IDE

• Apache Maven 3.6.2+

• An AWS Account to access the KMS service

• Docker for your system to run KMS locally for testing purposes

Set up KMS locally

The easiest way to start working with KMS is to run a local instance as a container.

docker run --rm --name local-kms 8011:4599 -e SERVICES=kms -e START_WEB=0 -d localstack/localstack:0.11.1

This starts a KMS instance that is accessible on port 8011.

Create an AWS profile for your local instance using AWS CLI:

$ aws configure --profile localstack
AWS Access Key ID [None]: test-key
AWS Secret Access Key [None]: test-secret
Default region name [None]: us-east-1
Default output format [None]:

Create a KMS master key

Create a KMS master key queue using AWS CLI and store in MASTER_KEY_ARN environment variable.

MASTER_KEY_ARN=`aws kms create-key --profile localstack --endpoint-url=http://localhost:8011 | cut -f3`

Generate a key data as 256-bit symmetric key (AES 256)

aws kms generate-data-key --key-id $MASTER_KEY_ARN --key-spec AES_256 --profile localstack --endpoint-url=http://localhost:8011

Or, if you want to use your AWS account create a key using your default profile

MASTER_KEY_ARN=`aws kms create-key | cut -f3`
aws kms generate-data-key --key-id $MASTER_KEY_ARN --key-spec AES_256

Solution

The application built here allows to encrypt and decrypt text messages using a master key created on AWS KMS.

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

Clone the Git repository: git clone [https://github.com/quarkusio/quarkus-quickstarts.git](https://github.com/quarkusio/quarkus-quickstarts.git), or download an archive.

The solution is located in the amazon-kms-quickstart directory.

Creating the Maven project

First, we need a new project. Create a new project with the following command:

mvn io.quarkus:quarkus-maven-plugin:1.7.6.Final:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=amazon-kms-quickstart \
    -DclassName="org.acme.kms.QuarkusKmsSyncResource" \
    -Dpath="/sync" \
    -Dextensions="resteasy-jsonb,amazon-kms,resteasy-mutiny"
cd amazon-kms-quickstart

This command generates a Maven structure importing the RESTEasy/JAX-RS, Mutiny and Amazon KMS Client extensions. After this, the amazon-kms extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.

Creating JSON REST service

In this example, we will create an application that allows to encrypt and decrypt text message provided in the request. The example application will demonstrate the two programming models supported by the extension.

Let’s create a org.acme.kms.QuarkusKmsSyncResource that will provide an API to encrypt and decrypt message using the synchronous client.

package org.acme.kms;
import javax.inject.Inject;
import javax.ws.rs.Consumes;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import org.apache.commons.codec.binary.Base64;
import org.eclipse.microprofile.config.inject.ConfigProperty;
import software.amazon.awssdk.core.SdkBytes;
import software.amazon.awssdk.services.kms.KmsClient;
import software.amazon.awssdk.services.kms.model.DecryptResponse;
@Path("/sync")
@Produces(MediaType.TEXT_PLAIN)
@Consumes(MediaType.TEXT_PLAIN)
public class QuarkusKmsSyncResource {
    @Inject
    KmsClient kms;
    @ConfigProperty(name = "key.arn")
    String keyArn;
    @POST
    @Path("/encrypt")
    public String encrypt(String data) {
        SdkBytes encryptedBytes = kms.encrypt(req -> req.keyId(keyArn).plaintext(SdkBytes.fromUtf8String(data))).ciphertextBlob();
        return Base64.encodeBase64String(encryptedBytes.asByteArray());
    }
    @POST
    @Path("/decrypt")
    public String decrypt(String data) {
        SdkBytes encryptedData = SdkBytes.fromByteArray(Base64.decodeBase64(data.getBytes()));
        DecryptResponse decrypted = kms.decrypt(req -> req.keyId(keyArn).ciphertextBlob(encryptedData));
        return decrypted.plaintext().asUtf8String();
    }
}

An encrypted message is in the form of a bytes array. To return it to the user we need to encode it as Base64 string in the encrypt endpoint. On the decrypt endpoint we need to decode from the Base64 string back to the bytes array before sending it out to the KMS client.

Configuring KMS clients

Both KMS clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory. Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so you need to add a URL connection client dependency to the pom.xml file:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>url-connection-client</artifactId>
</dependency>

If you want to use Apache HTTP client instead, configure it as follows:

quarkus.kms.sync-client.type=apache

And add the following dependency to the application pom.xml:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>apache-client</artifactId>
</dependency>

If you’re going to use a local KMS instance, configure it as follows:

quarkus.kms.endpoint-override=http://localhost:8011
quarkus.kms.aws.region=us-east-1
quarkus.kms.aws.credentials.type=static
quarkus.kms.aws.credentials.static-provider.access-key-id=test-key
quarkus.kms.aws.credentials.static-provider.secret-access-key=test-secret

• quarkus.kms.aws.region - It’s required by the client, but since you’re using a local KMS instance use us-east-1 as it’s a default region of localstack’s KMS.

• quarkus.kms.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key

• quarkus.kms.endpoint-override - Override the KMS client to use a local instance instead of an AWS service

If you want to work with an AWS account, you can simply remove or comment out all Amazon KMS related properties. By default, the KMS client extension will use the default credentials provider chain that looks for credentials in this order:

• Java System Properties - aws.accessKeyId and aws.secretAccessKey

• Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY

• Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI

• Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,

• Instance profile credentials delivered through the Amazon EC2 metadata service

And the region from your AWS CLI profile will be used.

Next steps

Packaging

Packaging your application is as simple as ./mvnw clean package. It can be run with java -Dkey.arn=$MASTER_KEY_ARN -jar target/amazon-kms-quickstart-1.0-SNAPSHOT-runner.jar.

With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative. Depending on your system, that will take some time.

Going asynchronous

Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.

Create a org.acme.kms.QuarkusKmsAsyncResource REST resource that will be similar to our QuarkusKmsSyncResource but using an asynchronous programming model.

package org.acme.kms;
import io.smallrye.mutiny.Uni;
import javax.inject.Inject;
import javax.ws.rs.Consumes;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import org.apache.commons.codec.binary.Base64;
import org.eclipse.microprofile.config.inject.ConfigProperty;
import software.amazon.awssdk.core.SdkBytes;
import software.amazon.awssdk.services.kms.KmsAsyncClient;
import software.amazon.awssdk.services.kms.model.DecryptResponse;
import software.amazon.awssdk.services.kms.model.EncryptResponse;
@Path("/async")
@Produces(MediaType.TEXT_PLAIN)
@Consumes(MediaType.TEXT_PLAIN)
public class QuarkusKmsAsyncResource {
    @Inject
    KmsAsyncClient kms;
    @ConfigProperty(name = "key.arn")
    String keyArn;
    @POST
    @Path("/encrypt")
    public Uni<String> encrypt(String data) {
        return Uni.createFrom().completionStage(kms.encrypt(req -> req.keyId(keyArn).plaintext(SdkBytes.fromUtf8String(data))))
            .onItem().transform(EncryptResponse::ciphertextBlob)
            .onItem().transform(blob -> Base64.encodeBase64String(blob.asByteArray()));
    }
    @POST
    @Path("/decrypt")
    public Uni<String> decrypt(String data) {
        return Uni.createFrom().item(SdkBytes.fromByteArray(Base64.decodeBase64(data.getBytes())))
            .onItem().transformToUni(msg ->
                Uni.createFrom().completionStage(kms.decrypt(req -> req.keyId(keyArn).ciphertextBlob(msg)))
            )
            .onItem().transform(DecryptResponse::plaintext)
            .onItem().transform(SdkBytes::asUtf8String);
    }
}

We create Uni instances from the CompletionStage objects returned by the asynchronous KMS client, and then transform the emitted item.

And we need to add the Netty HTTP client dependency to the pom.xml:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>netty-nio-client</artifactId>
</dependency>

Configuration Reference