added keys concepts, reg key tutorial

This commit is contained in:
Jennifer Hasegawa
2018-01-30 13:19:00 -08:00
parent 4967081bb3
commit e5fc4f2b9f
3 changed files with 404 additions and 0 deletions

View File

@@ -3,6 +3,7 @@
A _Transaction_ is the only way to modify the XRP Ledger. Transactions are only valid if signed, submitted, and accepted into a validated ledger version following the [consensus process](https://ripple.com/build/ripple-ledger-consensus-process/). Some ledger rules also generate _[pseudo-transactions](#pseudo-transactions)_, which aren't signed or submitted, but still must be accepted by consensus. Transactions that fail are also included in ledgers because they modify balances of XRP to pay for the anti-spam [transaction cost](concept-transaction-cost.html).
* [Authorizing Transactions](#authorizing-transactions)
* [Understanding Master and Regular Keys](#understanding-master-and-regular-keys)
* [Common Fields of All Transactions](#common-fields)
* [Transaction Types](#transaction-types)
* [Reliable Transaction Submission](#reliable-transaction-submission)
@@ -25,6 +26,64 @@ Any signature type can authorize any type of transaction, with the following exc
* Only the master key can [permanently give up the ability to freeze](concept-freeze.html#no-freeze).
* You can never remove the last method of signing transactions from an address.
## Understanding Master and Regular Keys
In the XRP Ledger, a digital signature proves that a transaction is authorized to do a specific set of actions. A digital signature is created based on a key pair associated with the transaction's sending account. There are two types of key pairs available: master keys and regular keys. A key pair includes a private key and a public key.
### Master Keys
When you create an account using the [`wallet_propose`](reference-rippled.html#wallet-propose) method, the `master_seed` (private key) and `public_key` returned in the response are the master keys for the account. These keys are an intrinsic part of the account's identity as the `account_id` (account address), also returned in the `wallet_propose` response, is derived from the `public_key` value.
Here's a sample `wallet_propose` response, including the `master_seed` (private key), `public_key`, and `account_id` (account address) values:
```
{
"result": {
"account_id": "rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt",
"key_type": "secp256k1",
"master_key": "SAY ARMY KITE LETS PAN WAVE JUKE ACRE MAT TILT FEAT LED",
"master_seed": "PrivateKeyXXXXXXXXXXXXXXXXXXX",
"master_seed_hex": "47E8F7F59D0CC9A3F01FD3D69CCAE93A",
"public_key": "aBQEK3r6hb8isnCWmortkNdv3MSMKP74o7gj3kHZQF9vDkbXo4Qs",
"public_key_hex": "032D911AE9887278110A8FE25169546D4E95A82AF5EFA25525FC3FDFFDC5A8B604"
},
"status": "success",
"type": "response"
}
```
We refer to this key pair that is an intrinsic part of an account as the **master keys** for the account.
Master keys have more powerful signing authority than regular keys. In addition to being able to sign all transactions that regular keys can, master keys are the only keys that can be used to perform the following actions:
* Use the master private key to [disable the master public key](#accountset-flags).
* Permanently give up the ability to [freeze counterparties](concept-freeze.html#no-freeze).
**Important:** Master keys cannot be changed. This means that if your master private key is [compromised](concept-issuing-and-operational-addresses.html), you cannot change it to stop the compromise.
This is a compelling reason to keep your master keys offline and set up regular keys to sign transactions from your master account instead.
### Regular Keys
When you create an account using the [`wallet_propose`](reference-rippled.html#wallet-propose) method, the `master_seed` (private key) and `public_key` returned in the response are the master keys for the account. For the purposes of this discussion, let's call this account the master account. Ripple recommends that you keep the master account's master keys offline and assign regular keys to the master account to sign your transactions instead.
You generate regular keys using the same `wallet_propose` method used to generate a master account and master keys. However, you use this second account and key pair specifically with the `SetRegularKey` method to assign **regular keys** to the master account.
Once you've assigned the regular keys, the master account has two key pairs associated with it:
* Master keys that are intrinsically related to its address and which you keep offline.
* Regular keys that you've assigned to sign transactions.
You can assign one regular key pair to a master account and use it to sign all transactions, except for the ones reserved for the [master keys](#master-keys).
You can remove or change the regular keys at any time. This means that if a regular private key is compromised (but the master private key is not), you can regain control of your master account by simply removing or changing the regular key pair.
For more information about assigning regular keys, see [Working with Regular Keys](tutorial-regular-keys.html).
## Signing and Submitting Transactions
Sending a transaction to the XRP Ledger involves several steps:

View File

@@ -0,0 +1,338 @@
# Working with Regular Keys
Assign regular keys to your account to enable you to sign most transactions with regular keys, while keeping your master keys offline. A master key [compromise](concept-issuing-and-operational-addresses.html) can be difficult to recover from, while removing or changing compromised regular keys is a simpler task.
For an overview of master and regular keys, see [Understanding Master and Regular Keys](reference-transaction-format.html#understanding-master-and-regular-keys).
This tutorial covers:
* [Assigning Regular Keys](#assigning-regular-keys)
* [Removing or Changing Regular Keys](#removing-or-changing-regular-keys)
## Assigning Regular Keys
This tutorial walks you through the steps required to assign regular keys to an account:
1. [Generate a master account and its master keys](#1-generate-a-master-account-and-its-master-keys)
2. [Fund the master account](#2-fund-the-master-account)
3. [Generate a regular account and its regular keys](#3-generate-a-regular-account-and-its-regular-keys)
4. [Assign the regular keys to the master account](#4-assign-the-regular-keys-to-the-master-account)
5. [Submit a test payment using regular keys](#5-submit-a-test-payment-using-regular-keys)
6. [Explore next steps](#6-explore-next-steps)
### 1. Generate a Master Account and Its Master Keys
If you already have a master account and master keys, skip this step.
Use the [`wallet_propose`](reference-rippled.html#wallet-propose) method to generate a master account, along with its master keys.
Here's an example `wallet_propose` request and response.
#### WebSocket Request
```
{
"method": "wallet_propose"
}
```
#### WebSocket Response
```
{
"result": {
"account_id": "rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt",
"key_type": "secp256k1",
"master_key": "SAY ARMY KITE LETS PAN WAVE JUKE ACRE MAT TILT FEAT LED",
"master_seed": "MasterPrivateKeyXXXXXXXXXXXXX",
"master_seed_hex": "47E8F7F59D0CC9A3F01FD3D69CCAE93A",
"public_key": "aBQEK3r6hb8isnCWmortkNdv3MSMKP74o7gj3kHZQF9vDkbXo4Qs",
"public_key_hex": "032D911AE9887278110A8FE25169546D4E95A82AF5EFA25525FC3FDFFDC5A8B604"
},
"status": "success",
"type": "response"
}
```
### 2. Fund the Master Account
If you already have a funded master account, skip this step.
A master account, such as the one created in step 1, must be funded before you can assign regular keys to it. Use the [`Payment`](reference-transaction-format.html#payment) transaction type to fund your master account.
In the request, send the funder's `account_id` as the `Account` value, the funder's `master_seed` (private key) as the `secret` value, and the master account's `account_id` as the `Destination` value.
Here's an example `Payment` request and response.
#### WebSocket Request
```
{
"command" : "submit",
"tx_json" : {
"TransactionType" : "Payment",
"Account" : "rPZXdWPxSXCBfnSXGnnBhXjhJ8V5K7oB5s",
"Destination" : "rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt",
"Amount" : "100000000"
},
"secret" : "FunderPrivateKeyXXXXXXXXXXXXX"
}
```
#### WebSocket Response
```
{
"result": {
"engine_result": "tesSUCCESS",
"engine_result_code": 0,
"engine_result_message": "The transaction was applied. Only final in a validated ledger.",
"tx_blob": "12000022800000002400000001614000000005F5E10068400000000000000A7321029FAB5CE43E10B0743EC6045616D674B0953DF1730EB53DB377D2164EB68A2CC17446304402207AD76AB81C15F44AF77757D796BB6A51DA851C2EF62C24FEF3A7DFC56D8BBB80022040C11F79C52BF15B7D3C5630F894B0047740C30932117D8B971A461FD2682E798114F779A56C00EF101471C8ADED9343532063E73AFE8314E40BE141DFE3544627F98879C9A600974C4C37B3",
"tx_json": {
"Account": "rPZXdWPxSXCBfnSXGnnBhXjhJ8V5K7oB5s",
"Amount": "100000000",
"Destination": "rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt",
"Fee": "10",
"Flags": 2147483648,
"Sequence": 1,
"SigningPubKey": "029FAB5CE43E10B0743EC6045616D674B0953DF1730EB53DB377D2164EB68A2CC1",
"TransactionType": "Payment",
"TxnSignature": "304402207AD76AB81C15F44AF77757D796BB6A51DA851C2EF62C24FEF3A7DFC56D8BBB80022040C11F79C52BF15B7D3C5630F894B0047740C30932117D8B971A461FD2682E79",
"hash": "D3EDA40C31BC4679C1C429EACF81953065C2D9AD0879F36EA1B6AD6BDFBDD054"
}
},
"status": "success",
"type": "response"
}
```
### 3. Generate a Regular Account and Its Regular Keys
Use the [`wallet_propose`](reference-rippled.html#wallet-propose) method to generate a second account, along with its key pair to be used as regular keys for the master account.
Here's an example `wallet_propose` request and response.
#### WebSocket Request
```
{
"method": "wallet_propose"
}
```
#### WebSocket Response
```
{
"result": {
"account_id": "rf9vUoqa83foreMr6CYFCEPTZUFagZv83c",
"key_type": "secp256k1",
"master_key": "SAFE TUM GLEN CUR BALD WELT TIDY HO WAYS MALE DON SON",
"master_seed": "RegularPrivateKeyXXXXXXXXXXXX",
"master_seed_hex": "7AF430DBE26743EBF3155506325268D5",
"public_key": "aBR9dmoHfrfU24q1cbjdehNsFiuV9k5PrrQTLiH42qxhWr5ybc1K",
"public_key_hex": "03A45E8E4BFECA7473F932839B982C33CD2FB7B788932A21DCDD8536AE63A1614C"
},
"status": "success",
"type": "response"
}
```
### 4. Assign the Regular Keys to the Master Account
Use the [`SetRegularKey`](reference-transaction-format.html#setregularkey) method to assign the regular keys to your master account.
In the request, send the master account's `account_ID` as the `account` value, the master account's `master_seed` (private key) as the `secret` value, and the regular account's `account_id` (generated in step 3) as the `RegularKey` value.
Here's an example `SetRegularKey` request and response.
***TODO: We tell the user to keep the master private key offline - but we are sending it in few transactions in this tutorial. I'm being too literal - but I think we should acknowledge that what we really mean is to strictly limit online use of the master private key. What do you think?***
#### WebSocket Request:
```
{
"command" : "submit",
"tx_json" : {
"TransactionType" : "SetRegularKey",
"Account" : "rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt",
"RegularKey" : "rf9vUoqa83foreMr6CYFCEPTZUFagZv83c"
},
"secret" : "MasterPrivateKeyXXXXXXXXXXXXX"
}
```
#### WebSocket Response:
```
{
"result": {
"engine_result": "tesSUCCESS",
"engine_result_code": 0,
"engine_result_message": "The transaction was applied. Only final in a validated ledger.",
"tx_blob": "1200052280000000240000000168400000000000000A7321032D911AE9887278110A8FE25169546D4E95A82AF5EFA25525FC3FDFFDC5A8B604744730450221008EBFA6ABE01BB31A772816FF8560DA78273FA4DC982D0C85A6A516A9188AD70A02205CE1E9E3A685D4D29C62C9DA334BC8BB16468AAA11B572320AD2E98AE1B551BB8114E40BE141DFE3544627F98879C9A600974C4C37B3881443807E97EA8BCB97F4032DEFB4AC9208A359493E",
"tx_json": {
"Account": "rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt",
"Fee": "10",
"Flags": 2147483648,
"RegularKey": "rf9vUoqa83foreMr6CYFCEPTZUFagZv83c",
"Sequence": 1,
"SigningPubKey": "032D911AE9887278110A8FE25169546D4E95A82AF5EFA25525FC3FDFFDC5A8B604",
"TransactionType": "SetRegularKey",
"TxnSignature": "30450221008EBFA6ABE01BB31A772816FF8560DA78273FA4DC982D0C85A6A516A9188AD70A02205CE1E9E3A685D4D29C62C9DA334BC8BB16468AAA11B572320AD2E98AE1B551BB",
"hash": "A9EE659DC08E6589F3454186C1D846763E55DEEF5525A8AE1F3D87B53EF5B86A"
}
},
"status": "success",
"type": "response"
}
```
### 5. Submit a Test Payment Using Regular Keys
To verify that the regular keys are set correctly on the master account, submit a test payment using the [`Payment`](reference-transaction-format.html#payment) transaction type using the regular keys.
In the request, send the regular account's `master_seed` (regular private key) (generated in step 3) as the `secret` value and the master account's `account_id` as the `Account` value.
Here's an example `Payment` request and response.
#### WebSocket Request:
```
{
"method":"submit",
"secret":"RegularPrivateKeyXXXXXXXXXXXX",
"tx_json": {
"Account":"rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt",
"Fee":"10",
"Amount":"10000000",
"Destination":"rPZXdWPxSXCBfnSXGnnBhXjhJ8V5K7oB5s",
"TransactionType":"Payment"
}
}
```
#### WebSocket Response:
***TODO: I think it would be useful to call out the SigningPubKey and/or TxnSignature in the response to surface/link to a discussion about signatures and how they are created from keys. I think it's relevant in that the keys topic is surfaced through a discussion of transaction authorization via signing. Useful? Does a topic on signatures exist?***
```
{
"result": {
"engine_result": "tesSUCCESS",
"engine_result_code": 0,
"engine_result_message": "The transaction was applied. Only final in a validated ledger.",
"tx_blob": "1200002280000000240000000361400000000098968068400000000000000A732103A45E8E4BFECA7473F932839B982C33CD2FB7B788932A21DCDD8536AE63A1614C74463044022037DC86BEE1D0E1F394273B80E4072A35B2E221880879CC2C47FE0AD152B3E2120220511A6555B8A524321E962164EC830A83267AF97E9FDF24CCEC7B38944E2CC95C8114E40BE141DFE3544627F98879C9A600974C4C37B38314F779A56C00EF101471C8ADED9343532063E73AFE",
"tx_json": {
"Account": "rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt",
"Amount": "10000000",
"Destination": "rPZXdWPxSXCBfnSXGnnBhXjhJ8V5K7oB5s",
"Fee": "10",
"Flags": 2147483648,
"Sequence": 3,
"SigningPubKey": "03A45E8E4BFECA7473F932839B982C33CD2FB7B788932A21DCDD8536AE63A1614C",
"TransactionType": "Payment",
"TxnSignature": "3044022037DC86BEE1D0E1F394273B80E4072A35B2E221880879CC2C47FE0AD152B3E2120220511A6555B8A524321E962164EC830A83267AF97E9FDF24CCEC7B38944E2CC95C",
"hash": "A8C3D091245794A664A5C1F0D275D1DB9A9349F1F873AABAD7AD1E43E8A117FB"
}
},
"status": "success",
"type": "response"
}
```
### 6. Explore Next Steps
Now that you're familiar with the benefits of assigning regular keys to an account, consider taking a look at these related topics and tutorials:
* [How to Multi-Sign](tutorial-multisign.html)
* [Issuing and Operational Addresses](concept-issuing-and-operational-addresses.html)
* [Listing XRP as an Exchange](tutorial-listing-xrp.html)
## Removing or Changing Regular keys
If your regular keys are compromised, or if you just want to periodically change regular keys as a security measure, use the [`SetRegularKey`](reference-transaction-format.html#setregularkey) method to remove or change the regular keys for the master account. ***TODO: I believe the first if is valid. How about the second if? Is this something that someone might want to do?***
To change your regular keys, see steps 3 - 5 of [Assigning Regular Keys](#assigning-regular-keys).
If you want to remove compromised regular keys and assign new regular keys later, use the [`SetRegularKey`](reference-transaction-format.html#setregularkey) method, omitting the `RegularKey` value. Here's an example `SetRegularKey` request and response that removes any existing regular keys.
***TODO: Is it valid to treat these are two separate flows? Change vs Remove? If the keys are compromised, you may want to just quickly remove the key and generate and assign new keys later, or not at all. If you are just doing security maintenance, it may be more convenient to change them using a single method call.***
#### WebSocket Request:
```
{
"command" : "submit",
"tx_json" : {
"TransactionType" : "SetRegularKey",
"Account" : "rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt"
},
"secret" : "MasterPrivateKeyXXXXXXXXXXXXX"
}
```
#### WebSocket Response:
```
{
"result": {
"engine_result": "tesSUCCESS",
"engine_result_code": 0,
"engine_result_message": "The transaction was applied. Only final in a validated ledger.",
"tx_blob": "1200052280000000240000000468400000000000000A7321032D911AE9887278110A8FE25169546D4E95A82AF5EFA25525FC3FDFFDC5A8B60474463044022035B3076FED158D1CBFE2898521BDB068C6A2BE5C1BEA111D7F8611B1A35A10C302204CD5F547A7538C70404A5A157F5C1D4607B1F739C6C70D33895012E5B83E301E8114E40BE141DFE3544627F98879C9A600974C4C37B3",
"tx_json": {
"Account": "rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt",
"Fee": "10",
"Flags": 2147483648,
"Sequence": 4,
"SigningPubKey": "032D911AE9887278110A8FE25169546D4E95A82AF5EFA25525FC3FDFFDC5A8B604",
"TransactionType": "SetRegularKey",
"TxnSignature": "3044022035B3076FED158D1CBFE2898521BDB068C6A2BE5C1BEA111D7F8611B1A35A10C302204CD5F547A7538C70404A5A157F5C1D4607B1F739C6C70D33895012E5B83E301E",
"hash": "81F8D1D892D2A18814337470B02DD7AFA123CDDF85150DCE333674435254D046"
}
},
"status": "success",
"type": "response"
}
```
Here's an example response for a `Payment` transaction signed using an invalid regular key.
#### WebSocket Response:
```
{
"error": "badSecret",
"error_code": 41,
"error_message": "Secret does not match account.",
"request": {
"method": "submit",
"secret": "RegularPrivateKeyXXXXXXXXXXXX",
"tx_json": {
"Account": "rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt",
"Amount": "10000000",
"Destination": "rPZXdWPxSXCBfnSXGnnBhXjhJ8V5K7oB5s",
"Fee": "10",
"TransactionType": "Payment"
}
},
"status": "error",
"type": "response"
}
```

View File

@@ -255,6 +255,13 @@ pages:
- local
- ripple.com
- md: tutorial-regular-keys.md
html: tutorial-regular-keys.html
category: Tutorials
targets:
- local
- ripple.com
#Features describe how the XRP Ledger works in a mostly conceptual manner
- name: Accounts
category: Features