This quickstart guide will demonstrate how to:
- Start a
vault
dev server and configure akv
v2 secret engine with basic approle access control - Configure Quorum to use the
vault
for account management by using the Hashicorp Vaultaccount
plugin - Create new accounts in
vault
- Use an account to sign some data
This quickstart uses the
vault
dev server. The dev server is quick and easy to set up but should not be used for production.The dev server does not:
- persist data between restarts
- encrypt HTTP communications with TLS
For more advanced Vault topics (such as configuring storage, TLS, and approle token renewal) see the Vault docs.
-
Start the dev server:
$ vault server -dev -dev-root-token-id=root WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory and starts unsealed with a single unseal key. The root token is already authenticated to the CLI, so you can immediately begin using Vault. You may need to set the following environment variable: $ export VAULT_ADDR='http://127.0.0.1:8200' The unseal key and root token are displayed below in case you want to seal/unseal the Vault or re-authenticate. Unseal Key: 89TmuvV1EWRWSLCPXf7Ei7XfQ4MMfEs8DQ1pUKZz6J4= Root Token: root Development mode should NOT be used in production installations!
-
Setup the
vault
CLI using the values printed during start up:$ export VAULT_ADDR=http://127.0.0.1:8200 $ export VAULT_TOKEN=root
-
The dev Vault server has a
kv
v2 secret engine pre-configured (with namesecret
):$ vault secrets list -detailed Path Plugin Options Description ---- ------ ------- ----------- ... ... ... ... secret/ kv map[version:2] key/value secret storage
Older versions of Vault come configured with a
kv
v1 secret engine by default. If the value ofOptions
is notmap[version:2]
, upgrade to version 2 withvault kv enable-versioning secret/
-
Setup basic access control using approle:
-
Enable approle authentication:
$ vault auth enable approle Success! Enabled approle auth method at: approle/
-
Create a basic access policy for all secrets in the
secret
kv engine:$ cat <<EOF >policy.hcl path "secret/*" { capabilities = ["create", "update", "read"] } EOF
$ vault policy write basicpolicy policy.hcl Success! Uploaded policy: basicpolicy
-
Create a new approle role with the access defined by
basicpolicy
:$ vault write auth/approle/role/basicrole \ token_policies="basicpolicy" \ secret_id_ttl=0 \ token_ttl=0 Success! Data written to: auth/approle/role/basicrole
$ vault read auth/approle/role/basicrole/role-id Key Value --- ----- role_id dab8be4b-f17d-a9fd-f124-19fbec9bb688
$ vault write -f auth/approle/role/basicrole/secret-id Key Value --- ----- secret_id 5442577d-22e2-423f-6e11-0980af45a4fc secret_id_accessor 93f3fdc5-e878-4955-e557-d7a25afef6ef
The
secret_id
andsecret_id_accessor
should never be shared -
Make a note of the
role_id
andsecret_id
. Quorum/the plugin will need these to authenticate with Vault
-
-
Create the config file that defines the plugins used by Quorum,
quorum.json
:$ cat <<EOF >quorum.json { "baseDir": "plugins-basedir", "providers": { "account": { "name": "quorum-account-plugin-hashicorp-vault", "version": "0.x.0", "config": "file:///path/to/plugin.json" } } } EOF
-
Create the config file used by the Hashicorp Vault account plugin,
plugin.json
:$ cat <<EOF >plugin.json { "vault": "http://localhost:8200", "kvEngineName": "secret", "accountDirectory": "file:///path/to/kv-accts", "authentication": { "roleId": "env://HASHICORP_ROLE_ID", "secretId": "env://HASHICORP_SECRET_ID", "approlePath": "approle" } } EOF
-
Use the CLI to create a new account and store it in Hashicorp Vault
$ export HASHICORP_ROLE_ID=dab8be4b-f17d-a9fd-f124-19fbec9bb688 $ export HASHICORP_SECRET_ID=5442577d-22e2-423f-6e11-0980af45a4fc
$ geth account plugin new \ --plugins file:///path/to/quorum.json \ --plugins.skipverify \ --plugins.account.config '{"secretName": "demoacct","overwriteProtection": {"currentVersion": 0}}' Your new plugin-backed account was generated Public address of the account: 0x88133AcAf18Fb9db5A79066e0dB5208cd9491Cc9 Account URL: localhost:8200/v1/secret/data/demoacct?version=1 - You can share your public address with anyone. Others need it to interact with you. - You must NEVER share the secret key with anyone! The key controls access to your funds! - Consider BACKING UP your account! The specifics of backing up will depend on the plugin backend being used. - The plugin backend may require you to REMEMBER part/all of the new account config to retrieve the key in the future! See the plugin specific documentation for more info. - See the documentation for the plugin being used for more info.
-
The
accountDirectory
will contain a new account file:$ ls kv-accts UTC--2020-06-29T19-57-11.071220000Z--88133acaf18fb9db5a79066e0db5208cd9491cc9
$ cat kv-accts/UTC--2020-06-29T19-57-11.071220000Z--88133acaf18fb9db5a79066e0db5208cd9491cc9 {"Address":"88133acaf18fb9db5a79066e0db5208cd9491cc9","VaultAccount":{"SecretName":"demoacct","SecretVersion":1},"Version":1}
-
Vault will contain the new account address and private key:
$ vault kv get secret/demoacct ====== Metadata ====== Key Value --- ----- created_time 2020-06-29T20:01:02.572383Z deletion_time n/a destroyed false version 1 ====================== Data ====================== Key Value --- ----- 88133acaf18fb9db5a79066e0db5208cd9491cc9 915b18a038546d28350fb88d686f40b99e482f4264d1acadd53c734c71488643
-
Start Quorum with the Hashicorp Vault plugin:
$ PRIVATE_CONFIG=ignore geth \ --nodiscover \ --verbosity 5 \ --networkid 10 \ --raft \ --raftjoinexisting 1 \ --datadir datadir \ --rpc \ --rpcapi eth,debug,admin,net,web3,plugin@account \ --plugins file:///path/to/quorum.json \ --plugins.skipverify
-
Attach to the node, create another account using the RPC API (available on the
geth
console), and use the account$ geth attach datadir/geth.ipc Welcome to the Geth JavaScript console! instance: Geth/v1.9.7-stable-f343ba05(quorum-v2.6.0)/darwin-amd64/go1.13.7 coinbase: 0x88133acaf18fb9db5a79066e0db5208cd9491cc9 at block: 0 (Thu, 01 Jan 1970 01:00:00 BST) datadir: /vault-plugin-demo/datadir modules: admin:1.0 debug:1.0 eth:1.0 ethash:1.0 miner:1.0 net:1.0 personal:1.0 plugin@account:1.0 raft:1.0 rpc:1.0 txpool:1.0 web3:1.0 > plugin_account.newAccount({"secretName": "anotherdemoacct","overwriteProtection": {"currentVersion": 0}}) { address: "0x8effa64323cd1d737f068c09021dccdee1f2ce6d", url: "http://localhost:8200/v1/secret/data/anotherdemoacct?version=1" } > personal.listWallets [{ accounts: [{ address: "0x8effa64323cd1d737f068c09021dccdee1f2ce6d", url: "http://localhost:8200/v1/secret/data/anotherdemoacct?version=1" }, { address: "0x88133acaf18fb9db5a79066e0db5208cd9491cc9", url: "http://localhost:8200/v1/secret/data/demoacct?version=1" }], status: "0 unlocked account(s)", url: "plugin://account-plugin-hashicorp-vault" }] > personal.sign("0xaaaaaa", "0x88133acaf18fb9db5a79066e0db5208cd9491cc9", "") "0x051f8a957aa73f51dae58ad4fc387aae93b0901031114adac39caffc667547ca3746e0982744226a2ffdf763ed747f21aba36237fc4382cac72cf81d721303511b"