gcloud_hsm_wallet

Documentation for eth_defi.gcloud_hsm_wallet Python module.

Google Clooud HSM wallet support.

  • HSM is Hardware Security Module-backed wallet where the private key cannot be stolen

  • Create Google Cloud HSM-backed wallets with automatic environment configuration

  • Sign transactions securely using Cloud HSM

  • Support batched transaction signing with nonce management

Setting up Google Cloud credentidals for HSM wallet

To get started with Google Cloud

  • Sign up, create a project

  • Create a new Keyring

  • Create a new key with parameters - Purpose and algorithm: Asymmetric sign - Algorithm: ec-sign-secp256k1-sha256

  • Create a service account that can access this key ring in IAM - See scripts/hsm/create-hsm-service-account-credentials.sh on Github

    for permissions needed and automation

Example environment configuration for source shell script credentials.env:

export GOOGLE_CLOUD_PROJECT="your-gcp-project-425310"
export GOOGLE_CLOUD_REGION="global"
export KEY_RING="Github-CI"
export KEY_NAME="github-ci"
export GCP_ADC_CREDENTIALS_STRING=$(cat << EOF
{
  "type": "service_account",
  "project_id": "trading-strategy-425310",
  "private_key_id": "snip",
  "private_key": "-----BEGIN PRIVATE KEY----- snip -----END PRIVATE KEY-----",
  "client_email": "tradingstrategy-hsm@trading-strategy-425310.iam.gserviceaccount.com",
  "client_id": "snip",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/tradingstrategy-hsm%40trading-strategy-425310.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}
EOF

Include this is in your environment as:

source credentials.env

To test that Google Cloud HSM setup work, copy-paste the following snippet to IPython console using %cpaste`, or use ``scripts/hsm/check-hsm-address.py script:

import os
import json
from web3_google_hsm.config import BaseConfig
from eth_defi.gcloud_hsm_wallet import HSMWallet

credentials = json.loads(os.environ["GCP_ADC_CREDENTIALS_STRING"])
config = BaseConfig.from_env()
print("Environment configured successfully!")
print(f"Project ID: {config.project_id}")
print(f"Region: {config.location_id}")
print(f"Credentials client email {credentials['client_email']}")

# This will crash if your credentials have access issues,
# or other Google Cloud configuration issues
hsm_wallet = HSMWallet(config, credentials=credentials)
print(f"Google Cloud HSM wallet configured.")
print(f"HSM account is: {hsm_wallet.address}")

Troubleshooting

If you get error CRYPTO_SCHEME_MISMATCH:

FailedPrecondition: 400 Operation requested for Key projects/trading-strategy-425310/locations/global/keyRings/Github-CI/cryptoKeys/github-ci/cryptoKeyVersions/1 has incorrect key purpose:
ENCRYPT_DECRYPT [violations {
  type: "CRYPTO_SCHEME_MISMATCH"
  subject: "projects/trading-strategy-425310/locations/global/keyRings/Github-CI/cryptoKeys/github-ci/cryptoKeyVersions/1"
}
]

Make sure the key algorith is set to ec-sign-secp256k1-sha256 on your Google Cloud key.

Classes

GCloudHSMWallet

HSM-backed wallet for secure transaction signing, on Google Cloud.