Skip to content

Latest commit

 

History

History
80 lines (55 loc) · 2.99 KB

README.md

File metadata and controls

80 lines (55 loc) · 2.99 KB
Raw

JWT::Aws::KMS

AWS KMS algorithm extensions for ruby-jwt.

Installation

Add this line to your application's Gemfile:

gem 'jwt-aws-kms'

And require the gem in your code.

require `jwt-aws-kms`

Supported algorithms

The gem supports the following AWS KMS algorithms:

Algorithm Name Description JWA Name
RSASSA_PKCS1_V1_5_SHA_256 RSASSA PKCS1 v1.5 using SHA-256 RS256
RSASSA_PKCS1_V1_5_SHA_384 RSASSA PKCS1 v1.5 using SHA-384 RS384
RSASSA_PKCS1_V1_5_SHA_512 RSASSA PKCS1 v1.5 using SHA-512 RS512
RSASSA_PSS_SHA_256 RSASSA PSS using SHA-256 PS256
RSASSA_PSS_SHA_384 RSASSA PSS using SHA-384 PS384
RSASSA_PSS_SHA_512 RSASSA PSS using SHA-512 PS512
ECDSA_SHA_256 ECDSA using P-256 and SHA-256 ES256
ECDSA_SHA_384 ECDSA using P-384 and SHA-384 ES384
ECDSA_SHA_512 ECDSA using P-521 and SHA-512 ES512

Usage

Basic usage

# Create a key, for example with the ruby AWS SDK
key = Aws::KMS::Client.new.create_key(key_spec: "HMAC_512", key_usage: "GENERATE_VERIFY_MAC")

algo = ::JWT::Aws::KMS.for(algorithm: "HS512")

token = JWT.encode(payload, key.key_metadata.key_id, algo)
decoded_token = JWT.decode(token, key.key_metadata.key_id, true, algorithm: algo)

Replace default algorithms

You can swap the default algorithms in the JWT gem to AWS backed ones by calling ::JWT::Aws::KMS.replace_defaults!.

::JWT::Aws::KMS.replace_defaults! # Called in a initializer of some kind

token = JWT.encode(payload, "e25c502b-a383-44ac-a778-0d97e8688cb7", "HS512") # Encode payload with KMS key e25c502b-a383-44ac-a778-0d97e8688cb7

Development

Localstack can be used to simulate the AWS KMS environment.

docker run \
  --rm -it \
  -p 127.0.0.1:4566:4566 \
  -p 127.0.0.1:4510-4559:4510-4559 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  localstack/localstack

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/anakinj/jwt-aws-kms. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Jwt::Kms project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.