github.com/gnolang/gno@v0.0.0-20240520182011-228e9d0192ce/docs/getting-started/local-setup/working-with-key-pairs.md (about) 1 --- 2 id: working-with-key-pairs 3 --- 4 5 # Working with Key Pairs 6 7 ## Overview 8 In this tutorial, you will learn how to manage private user keys, which are 9 required for interacting with the Gno.land blockchain. You will understand what 10 mnemonics are, how they are used, and how you can make interaction seamless with 11 Gno. 12 13 ## Prerequisites 14 - **`gnokey` installed.** Reference the 15 [Local Setup](installation.md#2-installing-the-required-tools-) guide for steps 16 17 ## Listing available keys 18 `gnokey` works by creating a local directory in the filesystem for storing 19 (encrypted!) user private keys. 20 21 You can find this repository by checking the value of the `--home` flag when 22 running the following command: 23 24 ```bash 25 gnokey --help 26 ``` 27 28 Example output: 29 30 ```bash 31 USAGE 32 <subcommand> [flags] [<arg>...] 33 34 Manages private keys for the node 35 36 SUBCOMMANDS 37 add Adds key to the keybase 38 delete Deletes a key from the keybase 39 generate Generates a bip39 mnemonic 40 export Exports private key armor 41 import Imports encrypted private key armor 42 list Lists all keys in the keybase 43 sign Signs the document 44 verify Verifies the document signature 45 query Makes an ABCI query 46 broadcast Broadcasts a signed document 47 maketx Composes a tx document to sign 48 49 FLAGS 50 -config ... config file (optional) 51 -home $XDG_CONFIG/gno home directory 52 -insecure-password-stdin=false WARNING! take password from stdin 53 -quiet=false suppress output during execution 54 -remote 127.0.0.1:26657 remote node URL 55 ``` 56 57 In this example, the directory where `gnokey` will store working data 58 is `/Users/zmilos/Library/Application Support/gno`. 59 60 Keep note of this directory, in case you need to reset the keystore, or migrate 61 it for some reason. 62 You can provide a specific `gnokey` working directory using the `--home` flag. 63 64 To list keys currently present in the keystore, we can run: 65 66 ```bash 67 gnokey list 68 ``` 69 70 In case there are no keys present in the keystore, the command will simply 71 return an empty response. 72 Otherwise, it will return the list of keys and their accompanying metadata as a 73 list, for example: 74 75 ```bash 76 0. Manfred (local) - addr: g15uk9d6feap7z078ttcnwc94k60ullrvhmynxjt pub: gpub1pgfj7ard9eg82cjtv4u4xetrwqer2dntxyfzxz3pqvn87u43scec4zfgn4la3nt237nehzydzayqxe43fx63lq6rty9c5almet4, path: <nil> 77 1. Milos (local) - addr: g15lppu0tuxets0c0t80tncs4enqzgxt7v4eftcj pub: gpub1pgfj7ard9eg82cjtv4u4xetrwqer2dntxyfzxz3pqw2kkzujprgrfg7vumg85mccsf790n5ep6htpygkuwedwuumf2g7ydm4vqf, path: <nil> 78 ``` 79 80 The key response consists of a few pieces of information: 81 82 - The name of the private key 83 - The derived address (`addr`) 84 - The public key (`pub`) 85 86 Using these pieces of information, we can interact with Gno.land tools and write 87 blockchain applications. 88 89 ## Generating a BIP39 mnemonic 90 91 Using `gnokey`, we can generate a [mnemonic phrase](https://en.bitcoin.it/wiki/Seed_phrase) based on 92 the [BIP39 standard](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki). 93 94 To generate the mnemonic phrase in the console, you can run: 95 96 ```bash 97 gnokey generate 98 ``` 99 100  101 102 ## Adding a random private key 103 If we wanted to add a new private key to the keystore, we can run the following 104 command: 105 106 ```bash 107 gnokey add MyKey 108 ``` 109 110 Of course, you can replace `MyKey` with whatever name you want for your key. 111 112 The `gnokey` tool will prompt you to enter a password to encrypt the key on disk 113 (don't forget this!). 114 After you enter the password, the `gnokey` tool will add the key to the keystore, 115 and return the accompanying [mnemonic phrase](https://en.bitcoin.it/wiki/Seed_phrase), which you should remember 116 somewhere if you want to recover the key at a future point in time. 117 118  119 120 You can check that the key was indeed added to the keystore, by listing available 121 keys: 122 123 ```bash 124 gnokey list 125 ``` 126 127  128 129 ## Adding a private key using a mnemonic 130 To add a private key to the `gnokey` keystore [using an existing mnemonic](#generating-a-bip39-mnemonic), 131 we can run the following command with the 132 `--recover` flag: 133 134 ```bash 135 gnokey add --recover MyKey 136 ``` 137 138 Of course, you can replace `MyKey` with whatever name you want for your key. 139 140 By following the prompts to encrypt the key on disk, and providing a BIP39 141 mnemonic, we can successfully add the key to the keystore. 142 143  144 145 ## Deleting a private key 146 To delete a private key from the `gnokey` keystore, we need to know the name or 147 address of the key to remove. 148 After we have this information, we can run the following command: 149 150 ```bash 151 gnokey delete MyKey 152 ``` 153 154 After entering the key decryption password, the key will be deleted from the keystore. 155 156 :::caution Recovering a private key 157 In case you delete or lose access to your private key in the `gnokey` keystore, 158 you can recover it using the key's mnemonic, or by importing it if it was exported 159 at a previous point in time. 160 ::: 161 162 ## Exporting a private key 163 Private keys stored in the `gnokey` keystore can be exported to a desired place 164 on the user's filesystem. 165 166 Keys are exported in their original armor, encrypted or unencrypted. 167 168 To export a key from the keystore, you can run: 169 170 ```bash 171 gnokey export -key MyKey -output-path ~/Work/gno-key.asc 172 ``` 173 174 Follow the prompts presented in the terminal. Namely, you will be asked to 175 decrypt the key in the keystore, and later to encrypt the armor file on disk. 176 It is worth noting that you can also export unencrypted key armor, using the `--unsafe` flag. 177 178  179 180 ## Importing a private key 181 If you have an exported private key file, you can import it into `gnokey` fairly 182 easily. 183 184 For example, if the key is exported at `~/Work/gno-key.asc`, you can run the 185 following command: 186 187 ```bash 188 gnokey import -armor-path ~/Work/gno-key.asc -name ImportedKey 189 ``` 190 191 You will be asked to decrypt the encrypted private key armor on disk 192 (if it is encrypted, if not, use the `--unsafe` flag), and then to provide an 193 encryption password for storing the key in the keystore. 194 195 After executing the previous command, the `gnokey` keystore will have imported 196 `ImportedKey`. 197 198 