Giters

mikedouglas / aws-kms-ethereum-accounts

Example implementation of an AWS customer master key (CMK) based Ethereum account using AWS Cloud Development Kit (CDK) and Python.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

AWS-KMS-Ethereum-Accounts

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:

  1. Use Key Management Service (AWS KMS) to securely manage Ethereum accounts: Part 1
  2. Use Key Management Service (AWS KMS) to securely manage Ethereum accounts: Part 2
  3. 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 AWS CDK

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:

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.

  1. Install the CDK and test the CDK CLI:

    npm install -g aws-cdk && cdk --version

  2. 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

  3. Install the dependencies using the Python package manager:

    pip install -r requirements.txt

  4. Deploy the example code with the CDK CLI:

    cdk deploy

Cleaning up

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

Appendinx

Running Ethereum Accounts on AWS CMK

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.

What is this about

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).

How does it work

  1. 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)

  2. 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))

  3. 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))

  4. 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)))

What are the Ethereum Foundations

  • Ethereum using ECDSA (Elliptic Curve Digital Signing Algorithm) standard secp256k1
  • secp256k1 is supported by AWS KMS ECC_SECG_P256K1

Ethereum Public Key Address

  • 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.

Signing

The recovery identifier (v)

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.

Security

See CONTRIBUTING for more information.

License

This library is licensed under the MIT-0 License. See the LICENSE file.

About

Example implementation of an AWS customer master key (CMK) based Ethereum account using AWS Cloud Development Kit (CDK) and Python.

License:MIT No Attribution

Languages

Language:Python 100.0%