////
This guide is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
////
= Amazon KMS Client
:extension-status: preview

include::./attributes.adoc[]

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 https://aws.amazon.com/kms/[the AWS KMS website].

NOTE: The KMS extension is based on https://docs.aws.amazon.com/sdk-for-java/v2/developer-guide/welcome.html[AWS Java SDK 2.x].
It's a major rewrite of the 1.x code base that offers two programming models (Blocking & Async).

include::./status-include.adoc[]

The Quarkus extension supports two programming models:

* Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
* https://docs.aws.amazon.com/sdk-for-java/v2/developer-guide/basics-async.html[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 11+ installed with `JAVA_HOME` configured appropriately
* an IDE
* Apache Maven {maven-version}
* 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.

[source,bash,subs="verbatim,attributes"]
----
docker run --rm --name local-kms --publish 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:
[source,shell,subs="verbatim,attributes"]
----
$ 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.

[source,bash,subs="verbatim,attributes"]
----
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)
[source,bash,subs="verbatim,attributes"]
----
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
[source,bash,subs="verbatim,attributes"]
----
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 {quickstarts-clone-url}`, or download an {quickstarts-archive-url}[archive].

The solution is located in the `amazon-kms-quickstart` {quickstarts-tree-url}/amazon-kms-quickstart[directory].

== Creating the Maven project

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

[source,bash,subs=attributes+]
----
mvn io.quarkus.platform:quarkus-maven-plugin:{quarkus-version}:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=amazon-kms-quickstart \
    -DclassName="org.acme.kms.QuarkusKmsSyncResource" \
    -Dpath="/sync" \
    -Dextensions="resteasy,resteasy-jackson,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.

[source,java]
----
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:

[source,xml]
----
<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:
[source,properties]
----
quarkus.kms.sync-client.type=apache
----

And add the following dependency to the application `pom.xml`:
[source,xml]
----
<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>apache-client</artifactId>
</dependency>
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-apache-httpclient</artifactId>
</dependency>
----

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

[source,properties]
----
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:

include::./amazon-credentials.adoc[]

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/quarkus-app/quarkus-run.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.

[source,java]
----
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`:

[source,xml]
----
<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>netty-nio-client</artifactId>
</dependency>
----

== Configuration Reference

include::{generated-dir}/config/quarkus-amazon-kms.adoc[opts=optional, leveloffset=+1]
