This project represents an example implementation of an AWS customer master key (CMK) based Ethereum account.
It's implemented in AWS Cloud Development Kit (CDK) and Python.
This repository contains all code artifacts for the following three blog posts:
- Use Key Management Service (AWS KMS) to securely manage Ethereum accounts: Part 1
- Use Key Management Service (AWS KMS) to securely manage Ethereum accounts: Part 2
- How to sign Ethereum EIP-1559 transactions using AWS KMS
For a detailed explanation of how AWS Cloud Development Kit (CDK) can be used to create an AWS Key Management Service (KMS) based Ethereum account please have a look at the first blog post.
For a detailed explanation of the inner workings of Ethereum and how Ethereum signatures can be created using AWS KMS please have a look ath the second blog post.
For a detailed explanation of how EIP-1559 transactions can be created and signed using AWS KMS have a look at How to sign Ethereum EIP-1559 transactions using AWS KMS.
Deploying the solution with the AWS CDK The AWS CDK is an open-source framework for defining and provisioning cloud application resources. It uses common programming languages such as JavaScript, C#, and Python. The AWS CDK command line interface (CLI) allows you to interact with CDK applications. It provides features like synthesizing AWS CloudFormation templates, confirming the security changes, and deploying applications.
This section shows how to prepare the environment for running CDK and the sample code. For this walkthrough, you must have the following prerequisites:
- An AWS account.
- An IAM user with administrator access
- Configured AWS credentials
- Installed Node.js, Python 3, and pip. To install the example application:
When working with Python, it’s good practice to use venv to
create project-specific virtual environments. The use of venv
also reflects AWS CDK standard behavior. You can find
out more in the
workshop Activating the virtualenv.
-
Install the CDK and test the CDK CLI:
npm install -g aws-cdk && cdk --version
-
Download the code from the GitHub repo and switch in the new directory:
git clone https://github.com/aws-samples/aws-kms-ethereum-accounts.git && cd aws-kms-ethereum-accounts
-
Install the dependencies using the Python package manager:
pip install -r requirements.txt
-
Deploy the example code with the CDK CLI:
cdk deploy
Once you have completed the deployment and tested the application, clean up the environment to avoid incurring extra cost. This command removes all resources in this stack provisioned by the CDK:
cdk destroy
The explanation below just covers the inner workings of Ethereum legacy transactions (pre. EIP-155/EIP1559). For an explanation of how EIP-155 or EIP-1559 transactions can be signed using AWS KMS please have a look at How to sign Ethereum EIP-1559 transactions using AWS KMS.
This repository represents a PoC of how Ethereum accounts (private/public key) can be hosted on AWS KMS-CMK and how AWS KMS can be used to create valid offline signatures on Ethereum transactions.
In this simple example, a transaction is created to send some Ether from one Ethereum account to another. For testing
purposes it is recommended to use Ethereum Rinkeby (https://www.rinkeby.io
) network for example and to create an
account via Metamask.
To bootstrap the AWS KMS-CMK based Ethereum account, the Rinkeby crypto faucet can be used (https://www.rinkeby.io/#faucet).
-
The public key is being calculated and turned into an Ethereum checksum address.
pub_key = get_kms_public_key(params.get_kms_key_id()) _logger.info('pub_key encoded: {}'.format(pub_key)) eth_addr = calc_eth_address(pub_key) eth_checksum_addr = w3.toChecksumAddress(eth_addr)
-
A raw transaction is being assembled and the raw hash value is taken.
tx_params = get_tx_params(eth_checksum_addr, params.get_eth_dst_addr()) _logger.debug('tx params: {}'.format(tx_params)) tx_unsigned = serializable_unsigned_transaction_from_dict(tx_params) tx_hash = tx_unsigned.hash() _logger.debug('tx serialized: {}\n tx hash: {}'.format(tx_unsigned, tx_hash))
-
The signature is calculated over the raw hash value and the missing parameter
v
is being determined.tx_sig = find_eth_signature(params=params, plaintext=tx_hash) _logger.info('tx signature: \n\tr(x): {} \n\ts(proof):{}'.format(tx_sig['r'], tx_sig['s'])) tx_eth_recovered_pub_addr = get_recovery_id(tx_hash, tx_sig['r'], tx_sig['s'], eth_checksum_addr) _logger.info('tx eth recovered addr: {}'.format(tx_eth_recovered_pub_addr))
-
The final transaction is being assembled and sent of as a raw transaction.
tx_encoded = encode_transaction(tx_unsigned, vrs=(tx_eth_recovered_pub_addr['v'], tx_sig['r'], tx_sig['s'])) _logger.debug('tx encoded: {}'.format(tx_encoded)) eth_balance = w3.eth.get_balance(eth_checksum_addr) / 10 ** 18 _logger.info('eth balance: {}'.format(eth_balance)) tx_id = w3.eth.sendRawTransaction(tx_encoded) print('tx id: {}'.format(w3.toHex(tx_id)))
- Ethereum using ECDSA (Elliptic Curve Digital Signing Algorithm) standard
secp256k1
secp256k1
is supported by AWS KMSECC_SECG_P256K1
- https://cryptobook.nakov.com/asymmetric-key-ciphers/elliptic-curve-cryptography-ecc
- https://en.bitcoin.it/wiki/Secp256k1
-
Per default KMS public key is DER encoded
https://tools.ietf.org/html/rfc5280 (Page 16)
SubjectPublicKeyInfo ::= SEQUENCE { algorithm AlgorithmIdentifier, subjectPublicKey BIT STRING }
-
We need to ignore the first OCTET string since that it is just an indicator. https://tools.ietf.org/html/rfc5280 (Page 16)
The first octet of the OCTET STRING indicates whether the key is compressed or uncompressed. The uncompressed form is indicated by 0x04 and the compressed form is indicated by either 0x02 or 0x03
-
The address is defined by KECCAK / (SHA3) hash of raw public key.
https://www.oreilly.com/library/view/mastering-ethereum/9781491971932/ch04.html
Ethereum addresses are hexadecimal numbers, identifiers derived from the last 20 bytes of the Keccak-256 hash of the public key. Most often you will see Ethereum addresses with the prefix 0x that indicates they are hexadecimal-encoded [..].
-
Address needs to be converted to checksum address otherwise tools/libs will complain.
https://github.com/ethereum/EIPs/blob/master/EIPS/eip-55.md
In English, convert the address to hex, but if the ith digit is a letter (ie. it's one of abcdef) print it in uppercase if the 4*ith bit of the hash of the lowercase hexadecimal address is 1 otherwise print it in lowercase.
-
Ethereum ECDSA signatures consist of:
{r, s, v}
-
The signature needs to be taken over a SHA3 hash of the payload. To avoid re-hashing
MessageType='DIGEST'
needs to be specified.Due to random value
k
signatures of the same value are different all the time.AWS KMS does not make use of DDSG (Deterministic Digital Signature Generation) in the signing operation right now.
Even differences in bitcoin library implementations: https://bitcoin.stackexchange.com/a/83785
-
AWS KMS Signature is DER encoded.
r (x), s (proof) can be extracted from DER signature returned by AWS KMS.
https://tools.ietf.org/html/rfc3279#section-2.2.3
Ecdsa-Sig-Value ::= SEQUENCE { r INTEGER, s INTEGER }
-
S needs to be flipped if
>secp256k1n / 2
https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2.md
All transaction signatures whose s-value is greater than secp256k1n/2 are now considered invalid. The ECDSA recover precompiled contract remains unchanged and will keep accepting high s-values; this is useful e.g. if a contract recovers old Bitcoin signatures.
https://www.secg.org/sec2-v2.pdf (n = FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFE BAAEDCE6 AF48A03B BFD25E8C D0364141)
https://ethereum.stackexchange.com/a/55728
This is why a signature with a value of s > secp256k1n / 2 (greater than half of the curve) is invalid.
-
v needs to be recovered separately v is determined during ethereum signing process based on
CHAIN_ID
.https://github.com/ethereum/EIPs/blob/master/EIPS/eip-155.md#specification
[...] {0,1} + CHAIN_ID * 2 + 35 where {0,1} is the parity of the y value of the curve point for which r is the x-value in the secp256k1 signing process.
v
is usually created along during theEthereum
signing process. Since that KMS is used,v
needs to be recovered e.g. via lib or solidity function likeecrecover()
pub_key = Account.recoverHash(msg_hash, vrs=(v, r, s))
https://eips.ethereum.org/EIPS/eip-155
The currently existing signature scheme using v = 27 and v = 28 remains valid and continues to operate under the same rules as it did previously.
- https://cryptobook.nakov.com/digital-signatures/ecdsa-sign-verify-messages
- https://medium.com/mycrypto/the-magic-of-digital-signatures-on-ethereum-98fe184dc9c7
https://www.secg.org/sec1-v2.pdf
The extra value that Ethereum uses makes it possible to recover the public key from the signature which means that an Ethereum transaction does not include the public key. The purpose is to save space here.
If given, ethereum determines v
via the chainid to implement a replay protection. Since that KMS is signing the tx, a
fallback to the [27, 28]
is necessary. Solidity offers ecrecover
.
v
is constantly fluctuating between 27
and 28
due to the unstable signatures due to a random value k
as
mentioned above.
https://eips.ethereum.org/EIPS/eip-155
v is the last byte of the signature, and is either 27 (0x1b) or 28 (0x1c). This identifier is important because since we are working with elliptic curves, multiple points on the curve can be calculated from r and s alone. This would result in two different public keys (thus addresses) that can be recovered. The v simply indicates which one of these points to use.
https://ethereum.github.io/yellowpaper/paper.pdf
The value 27 represents an even y value and 28 represents an odd y value.
See CONTRIBUTING for more information.
This library is licensed under the MIT-0 License. See the LICENSE file.