-
Notifications
You must be signed in to change notification settings - Fork 2.8k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #9413 from marcinczeczko/amazon-kms-ses
Amazon KMS + SES extensions
- Loading branch information
Showing
37 changed files
with
1,878 additions
and
5 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,294 @@ | ||
| //// | ||
| This guide is maintained in the main Quarkus repository | ||
| and pull requests should be submitted there: | ||
| https://github.com/quarkusio/quarkus/tree/master/docs/src/main/asciidoc | ||
| //// | ||
| = Quarkus - Amazon KMS Client | ||
| :extension-status: preview | ||
|
|
||
| include::./attributes.adoc[] | ||
|
|
||
| Amazon 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 Amazon 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 1.8+ 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,shell,subs="verbatim,attributes"] | ||
| ---- | ||
| 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: | ||
| [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,shell,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 symnmetric key (AES 256) | ||
| [source,shell,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,shell,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,shell,subs=attributes+] | ||
| ---- | ||
| mvn io.quarkus:quarkus-maven-plugin:{quarkus-version}: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. | ||
|
|
||
| Lets 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> | ||
| ---- | ||
|
|
||
| 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: | ||
| - Java System Properties - `aws.accessKeyId` and `aws.secretKey` | ||
| * 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 EC2 container service 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. | ||
|
|
||
| [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().apply(EncryptResponse::ciphertextBlob) | ||
| .onItem().apply(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().produceCompletionStage(msg -> kms.decrypt(req -> req.keyId(keyArn).ciphertextBlob(msg))) | ||
| .onItem().apply(DecryptResponse::plaintext) | ||
| .onItem().apply(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] |
Oops, something went wrong.