amzn / nimbus-jose-jwt_aws-kms-extension

This library package is an extension of nimbus-jose-jwt library. It provides JWE based encrypters/decrypters and JWS based signers/verifiers for doing operations with cryptographic keys stores in AWS KMS.

nimbus-jose-jwt_aws-kms-extension

This library package is an extension of nimbus-jose-jwt library. It is compatible with version >=9.0,<=9.31 of nimbus-jose-jwt. It provides JWE based encrypters/decrypters and JWS based signers/verifiers for doing operations with cryptographic keys stores in AWS KMS. This library requires Java 8 or above.

Usage

In the current version following encryption and signing operations are supported:

1. Symmetric encryption (AES based).
   1. Classes: com.nimbusds.jose.aws.kms.crypto.KmsSymmetricEncrypter and com.nimbusds.jose.aws.kms.crypto.KmsSymmetricDecrypter
2. Asymmetric or Symmetric encryption (RSA or ECDSA based for asymmetric keys and AES based for symmetric keys).
   1. Classes: com.nimbusds.jose.aws.kms.crypto.KmsDefaultEncrypter and com.nimbusds.jose.aws.kms.crypto.KmsDefaultDecrypter
3. Asymmetric signing (RSA or ECDSA based).
   1. Classes: com.nimbusds.jose.aws.kms.crypto.KmsAsymmetricSigner and com.nimbusds.jose.aws.kms.crypto.KmsAsymmetricVerifier

Above classes should be used in the same way any encryption or signing class, which is directly provided by nimbus-jose-jwt, is used.

Note: For encryption using symmetric KMS keys, you can use either the KmsDefaultEncrypter class or the KmsSymmetricEncrypter class (and similarly can use KmsDefaultDecrypter or KmsSymmetricDecrypter, for decryption). The difference between these two classes is that KmsDefaultEncrypter generates an in-memory CEK and sends it to KMS for encryption using KMS's Encrypt API, while KmsSymmetricEncrypter uses KMS's GenerateDataKey API to generate the CEK and fetch its plaintext and encrypted versions.

Encryption Example (Java 11)

    final var jweEncrypter = new KmsSymmetricEncrypter(AWSKMSClientBuilder.defaultClient(), kid);

    final var jweHeader = new JWEHeader.Builder(alg, enc).keyID(kid).build();

    final var jweObject = new JWEObject(jweHeader, new Payload(payload));

    jweObject.encrypt(jweEncrypter);

Signing Example (Java 11)

    final var jwsSigner = new KmsAsymmetricSigner(
        AWSKMSClientBuilder.defaultClient(),
        kid,
        MessageType.fromValue(messageType));

    final var jwsHeader = new JWSHeader.Builder(alg)
            .keyID(kid)
            .customParam(MESSAGE_TYPE, messageType)
            .build();

    final var jwsObject = new JWSObject(jwsHeader, new Payload(payload));

    jwsObject.sign(jwsSigner);

Installation

This library is available on Maven Central. Following are the installation details.

Apache Maven

<dependency>
    <groupId>software.amazon.lynx</groupId>
    <artifactId>nimbus-jose-jwt_aws-kms-extension</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle Groovy DSL

repositories {
    mavenCentral()
}

dependencies {
    implementation "software.amazon.lynx:nimbus-jose-jwt_aws-kms-extension:1.0.0"
}

Scripts

There are various scripts included in this package, which you can use to perform various encryption/signing operations. You can find Gradle tasks and available options of these scripts in scripts.gradle file.

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.

nimbus-jose-jwt_aws-kms-extension's Issues

Add support for ECDSA algorithms for asymmetric singer and verifiers

RFC-spec algorithm claims in header result in failures

Great work introducing this package, thanks for making it available, looking forward to contributing to it!

We're running into an issue where third-party receivers are unable to verify the JWTs produced through the use of this extension due to it requiring the use of KMS algorithm name strings in https://github.com/amzn/nimbus-jose-jwt_aws-kms-extension/blob/main/nimbus-jose-jwt_aws-kms-extension/src/main/java/com/nimbusds/jose/aws/kms/crypto/impl/KmsAsymmetricSigningCryptoProvider.java#L89-L95

This results in a JWT header that looks like:

{
  "kid": "arn:aws:kms:us-west-2:975050201494:key/42487782-1f85-46fb-83a4-0a89c38df041",
  "typ": "JWT",
  "alg": "ECDSA_SHA_384"
}

Downstream verifiers fail because they don't recognize the alg value; they're expecting the JWS algorithm names defined in the JWS RFC spec (https://datatracker.ietf.org/doc/html/rfc7518#section-3.1).

Is there any requirement blocking an update that would enable the implementation from accepting a spec-compliant algorithm and translating that internally to KMS?

Add caching support for caching CEK for KMS base encryption and decryption operations

Currently KmsSymmetricEncrypter class generates a new CEK (Content Encryption Key, as know as data-key in KMS's context) for every ecnryption operation. Similarly the KmsSymmetricDecrypter class always calls KMS to decrypt a CEK for decryption operation. We can cache the CEKs in both operation (for a small amount of time, like few minutes or few hours) to reduce the number of API calls to KMS for these operations.

Add support for asymmetric KMS encryption keys

Current this lib only supports symmetric KMS encryption keys (for JWE encryption and decryption operations). Under this issue we'll add support for asymmetric KMS encryption keys (for JWE encryption and decryption operations).