Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/orlowskilp/evm-signer-kms

Rust library for signing EVM transaction with secp256k1 keys hosted in AWS KMS
https://github.com/orlowskilp/evm-signer-kms

aws-kms blockchain cryptocurrency cryptography evm evm-blockchain kms signature

Last synced: about 2 months ago
JSON representation

Rust library for signing EVM transaction with secp256k1 keys hosted in AWS KMS

Host: GitHub
URL: https://github.com/orlowskilp/evm-signer-kms
Owner: orlowskilp
License: mit
Created: 2024-10-08T06:05:41.000Z (4 months ago)
Default Branch: master
Last Pushed: 2024-10-24T08:35:32.000Z (4 months ago)
Last Synced: 2024-10-24T19:42:17.138Z (4 months ago)
Topics: aws-kms, blockchain, cryptocurrency, cryptography, evm, evm-blockchain, kms, signature
Language: Rust
Homepage:
Size: 73.2 KB
Stars: 18
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

README

        # Library for signing EVM transactions with AWS KMS

![Crates.io Version](https://img.shields.io/crates/v/evm-signer-kms)

[![evm-signer-kms](https://github.com/orlowskilp/evm-signer-kms/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/orlowskilp/evm-signer-kms/actions/workflows/build-and-test.yml)

[![codecov](https://codecov.io/github/orlowskilp/evm-signer-kms/branch/master/graph/badge.svg?token=DGY9EZFV5L)](https://codecov.io/github/orlowskilp/evm-signer-kms)

[![MIT License](https://img.shields.io/badge/license-MIT-green)](/LICENSE)

EVM transaction signing library using key pairs generated and stored in

[AWS KMS](https://aws.amazon.com/kms).

**Built for**:

* Security - AWS KMS managed keys which never leave HSM devices.

* Speed and reliability - Implemented in Rust.

## Features

* Legacy (type 0) transactions

* [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930) (type 1) transactions

* [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) (type 2) transactions

* Easily expandable to future [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) typed transactions

* [EIP-55](https://eips.ethereum.org/EIPS/eip-55) address checksum validation if address has uppercase chars

## Tool chain compatibility

Works with [MUSL](https://musl.libc.org) and [GNU](https://www.gnu.org/software/libc) tool chains.

### Building

I suggest using the provided [`Makefile`](./Makefile) to get things running fast. The default build

target is `x86_64-unknown-linux-gnu`, so this command will build the library with the GNU tool

chain:

```bash

make build

```

If you wish to build it with a different tool chain, it suffices to specify it with the `TOOL_CHAIN`

environment variable, e.g.:

```bash

TOOL_CHAIN=x86_64-unknown-linux-musl make build

```

## Setting up

The library communicates with AWS KMS API endpoints and thus requires authorization. Additionally it

requires AWS region and KMS key ID to be specified in the environment. This is because it was

designed with containers and container orchestration in mind.

There are good chances that you will want to inject some secrets into the client application in

the container orchestration solution (e.g. using

[AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) or

[HashiCorp Vault](https://www.hashicorp.com/products/vault)).

### Key access policy

At the very least the key policy must allow these actions for the IAM role which you are going to

use as the principal (see [documentation](https://docs.rs/evm-signer-kms) for more details):

```test

kms:DescribeKey

kms:GetPublicKey

kms:Sign

kms:Verify

```

### Authorization

I suggest using STS to assume a role which is granted permissions to use the

[secp256k1](https://docs.aws.amazon.com/kms/latest/developerguide/symm-asymm-choose-key-spec.html)

key pair in KMS. Once the IAM role is set up, you can assume it by e.g. setting the following

environment variables:

```bash

export AWS_ACCESS_KEY_ID="[REDACTED]"

export AWS_SECRET_ACCESS_KEY="[REDACTED]"

export AWS_SESSION_TOKEN="[REDACTED]"

```

### Region specification

The region needs to be inferred from the environment, e.g.:

```bash

export AWS_REGION="[REDACTED]"

```

### KMS key ID

The KMS key which is going to be used for message digests signing can be identified using a key ID

in the UUID format:

```bash

export KMS_KEY_ID="[REDACTED]"

```

**Note:** The library doesn't understand the `KMS_KEY_ID` variable itself, it is just a suggested

way to pass the key ID to the library logic (see examples in the

[documentation](https://docs.rs/evm-signer-kms)) for more details.

### Testing configuration

The easiest way to check whether everything works the way it should is by running tests.

Before running the tests you need to download the public key PEM file and copy it to

`./tests/data/pub-key.pem` and then decode it to `./tests/data/pub-key.der`.

[`Makefile`](./Makefile) provides a directive for that:

```bash

make fetch-public-key

```

Once the PEM and DER files are there, run the tests with:

```bash

make test

```

**Note**: If you downloaded the PEM file using the management console it is going to have the

following format:

```text

-----BEGIN PUBLIC KEY-----

...

-----END PUBLIC KEY-----

```

You can use the supplied helper [`pem2der.sh`](./tests/data/scripts/pem2der.sh) shell script:

```bash

cd tests/data

./scripts/pem2der.sh ./pub-key.pem > pub-key.der

```

If the tests pass, you're all set!

## What's needed

* More more and better tests

* Derivation paths support

* ARM `aarch64` support