ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-12-03 01:55:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

addressed feedback

Browse Source
This commit is contained in:
Jennifer Hasegawa
2018-02-05 16:00:34 -08:00
parent efebb666f3
commit f240e11459
7 changed files with 184 additions and 157 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
content/concept-keys.md
View File

@@ -1,17 +1,17 @@
# 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. A key pair is composed of a private key and a public key.
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.
You generate keys using the `wallet_propose` method. Here's a sample `wallet_propose` response:
You generate a key pair using the `wallet_propose` method. Here's a sample `wallet_propose` response:
```
{
"result": {
"account_id": "rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt",
"key_type": "secp256k1",
"master_key": "SAY ARMY KITE LETS PAN WAVE JUKE ACRE MAT TILT FEAT LED",
"master_key": "PRIV ATE KEY RFC 1751 XXX XXXX XXX XXXX XXX XXX XXXX",
"master_seed": "PrivateKeyXXXXXXXXXXXXXXXXXXX",
"master_seed_hex": "47E8F7F59D0CC9A3F01FD3D69CCAE93A",
"master_seed_hex": "PrivateKeyHexXXXXXXXXXXXXXXXXXXX",
"public_key": "aBQEK3r6hb8isnCWmortkNdv3MSMKP74o7gj3kHZQF9vDkbXo4Qs",
"public_key_hex": "032D911AE9887278110A8FE25169546D4E95A82AF5EFA25525FC3FDFFDC5A8B604"
},
@@ -20,48 +20,65 @@ You generate keys using the `wallet_propose` method. Here's a sample `wallet_pro
}
```
The `master_key`, `master_seed`, and `master_seed_hex` are the private key in various formats, all of which can be used to sign transactions. Despite being prefixed with `master_`, these keys are not necessarily the master keys for an account. For more information, see [Master Keys](#master-keys).
As you can see, in the context of the XRP Ledger, a key pair is composed of a bit more than a private key and a public key.
#### Private Key
The `master_key`, `master_seed`, and `master_seed_hex` are the private key in various formats, all of which can be used to sign transactions. Despite being prefixed with `master_`, these keys are not necessarily the master keys for an account. In this context, the `master_` prefix refers more to the keys' role as private keys.
#### Public Key
The `public_key` and `public_key_hex` are the public key in various formats, with the `public_key_hex` being the public key used to sign transactions.
For more information about the `wallet_propose` response, see [`wallet_propose`](reference-rippled.html#wallet-propose). ***TODO: JHA update wallet_propose response details with info from Rome in the PR.***
***TODO: Question: Okay, this is a nit of a clarification -- but I need to mention it to ensure that I understand how this works. When we talk about signing transactions - specifically authorizing transactions - from what I've seen of the `SetRegularKey` and `Payment` transactions, the sender must sign these transactions with a private key. This makes sense to me. In the paragraph above, we say that the `public_key_hex` is the "public key used to sign transactions." A sender cannot use a public key to sign a transaction, correct? Is what we are really trying to say that the `public_key_hex` value is the value that the XRP Ledger exposes publicly as the `SigningPubKey` to indicate the signer that authorized the transaction (the public-facing version of the private key?)***
You can use these generated key pairs in one two ways: as master keys or as regular keys.
#### `account_id`
The `account_id` is a [hash of the public key](concept-accounts.html#address-encoding) and designates the *potential* for an account to be created in the XRP Ledger. It is important to know that while an `account_id` exists, no actual account exists in the XRP Ledger until the `account_id` receives its first XRP payment. To create a funded account stored in the ledger, the `account_id` must [receive a `Payment` transaction](reference-transaction-format.html#creating-accounts) that provides enough XRP to meet the [reserve requirement](concept-reserves.html).
For more information about the `wallet_propose` response, see [`wallet_propose`](reference-rippled.html#wallet-propose).
You use this generated key pair in one of two ways: as master keys or as regular keys.
## Master Keys
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).
* Use the master private key to [disable the master public key](reference-transaction-format.html#accountset-flags).
* Permanently give up the ability to [freeze counterparties](concept-freeze.html#no-freeze).
Master keys for an account are the keys that are generated in the same [`wallet_propose`](reference-rippled.html#wallet-propose) response as the `account_id` of an account they are authorized to sign transactions for. Because they were generated in the same response, the keys are intrinsically related to the `account_id`, which is a hash-of-a-hash of the `public_key_hex`.
Master keys for an account are the keys that are generated in the same [`wallet_propose`](reference-rippled.html#wallet-propose) response as the `account_id` of the account the keys are authorized to sign transactions for. Because they are generated in the same response, the keys are [intrinsically related](concept-accounts.html#address-encoding) to the `account_id`, which is a hash-of-a-hash of the `public_key_hex`.
This is as opposed to "regular" keys, which are also generated using the `wallet_propose` method, but which must be explicitly assigned as regular keys to a funded account. For more information, see [Regular Keys](#regular-keys).
This is as opposed to regular keys, which are also generated using the `wallet_propose` method, but which must be manually assigned as regular keys to an account. Because regular keys are manually assigned, they are not intrinsically related to the `account_id` of the account they are authorized to sign transactions for. For more information, see [Regular Keys](#regular-keys).
**Caution:** Master keys cannot be changed, but they can be disabled. This means that if your master private key is compromised, rather than change it, you must [disable it]().
**Caution:** Master keys cannot be changed, but they can be disabled. This means that if your master private key is compromised, rather than change it, you must [disable it](reference-transaction-format.html#accountset-flags).
***TODO: Toned down the alarmist language. LOL. I think I read https://ripple.com/build/issuing-operational-addresses/ and https://ripple.com/build/listing-xrp-exchange/#accounts and took it too far. So, just so I understand, in this use case we're talking about, the scenario in which the malicious actor disables the master keys before you do to take control of your account forever -- is that not applicable here? I think it would be good to be able to link to another doc location that fully describes what a compromise is about and how to recover from one -- does that exist? Is that useful?***
***TODO: Toned down the alarmist language. LOL. I think I read https://ripple.com/build/issuing-operational-addresses/ and https://ripple.com/build/listing-xrp-exchange/#accounts and took it too far? So, just so I understand, in this use case we're talking about, the scenario in which the malicious actor disables the master keys before you do to take control of your account forever -- is that not applicable here? I think it would be good to be able to link to another doc location that fully describes what a compromise means in this context and how to recover from one -- does that exist?***
This is a compelling reason to keep your master keys offline and set up regular keys to sign transactions from your account instead.
Keeping your master keys offline means not putting your master private key somewhere malicious actors can get access to it. For example, this can mean keeping it on an airgapped machine that never connects to the internet, on a piece of paper stored in a safe, or in general, not within reach of a computer program that interacts with the internet at large. Ideally, master keys are used only on the most trusted of devices and for emergencies only, such as to change regular keys in the event of a possible or actual compromise.
Keeping your master keys offline means not putting your master private key somewhere malicious actors can get access to it. For example, this can mean keeping it on an air-gapped machine that never connects to the internet, on a piece of paper stored in a safe, or in general, not within reach of a computer program that interacts with the internet at large. Ideally, master keys are used only on the most trusted of devices and for emergencies only, such as to change regular keys in the event of a possible or actual compromise.
## Regular Keys
You assign regular keys to a funded account to be able to sign most transactions with them, while keeping your master keys offline.
You assign regular keys to an account to be able to sign most transactions with them, while keeping your master keys offline.
You generate keys to use as regular keys using the [`wallet_propose`](reference-rippled.html#wallet-propose) method. However, unlike with [master keys](#master-keys), which are generated alongside and intrinsically related to the `account_id` of an account they support, you must create the relationship between the regular keys and a funded account you want them to sign transactions for. You use the [`SetRegularKey`](reference-transaction-format.html#setregularkey) method to assign regular keys to a funded account.
You generate keys to use as regular keys using the [`wallet_propose`](reference-rippled.html#wallet-propose) method. However, unlike with [master keys](#master-keys), which are generated alongside and intrinsically related to the `account_id` of an account they support, you must manually create the relationship between regular keys and the account you want them to sign transactions for. You use the [`SetRegularKey`](reference-transaction-format.html#setregularkey) method to assign regular keys to an account.
For a tutorial on assigning regular keys, see [Working with Regular Keys](tutorial-regular-keys.html).
Once you've assigned regular keys to a funded account, the account has two key pairs associated with it:
Once you assign regular keys to an account, the account has two key pairs associated with it:
* "Master" keys that are intrinsically related to their `account_id` and which you keep offline.
* "Regular" keys that you've manually assigned to sign transactions for the account.
* "Master" keys that are intrinsically related to the account's `account_id` and which you keep offline.
* "Regular" keys that you've manually assigned to the account and which you use to sign transactions for the account.
You can assign one regular key pair to a funded account and use it to sign all transactions, except for the ones reserved for [master keys](#master-keys).
You can assign one regular key pair to an account and use it to sign all transactions, except for the ones reserved for [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 account by simply removing or changing the regular key pair.
For a tutorial on changing or removing regular keys, see [Working with Regular Keys](tutorial-regular-keys.html).

66
content/concept-signatures.md Normal file
View File

@@ -0,0 +1,66 @@
# Understanding Signatures
***TODO: Question: Added this concept section based on fantastic source material from Rome -- thought we should publish it. Useful? May be good to associate it with a flow diagram - like the one for address encoding: https://ripple.com/build/accounts/#address-encoding. Address both single and multi-sign flows.***
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](concept-keys.html) associated with the transaction's sending account.
Here's an overview of some of the more common signature-related fields used in the XRP Ledger.
### `SigningPubKey` (top-level)
The public key of the sender in hex format.
To verify whether a transaction is valid, you check that all of the following are true:
1. This key hashes to an address that's authorized by the transaction's sender.
The default is that only "the address of an account" is authorized to send all transactions for that account. That address is the hash-of-a-hash-with-a-checksum of the public key from the master key pair that was generated during address creation. Regular keys add a different address (derived from a different key pair) that's authorized to send most transactions. And of course, you can also disable the [master key](concept-keys.html) or add a [multi-signing list](reference-transaction-format.html#multi-signing).
2. This key matches the signature on the transaction.
3. The signature matches the transaction instructions. Empty in the case of a multi-signed transaction.
### `Signature`
The signature of the transaction instructions, in hex format.
***TODO: Question: How is this different from `TxnSignature`?***
Used with the `SigningPubKey` to verify that the sender did in fact approve the corresponding transaction instructions.
### `Signers` (in a multi-signed transaction)
An array of signature data for a [multi-signed transaction](reference-transaction-format.html#multi-signing).
Used to verify that a quorum of signers approved a transaction.
### `Signers[*].AccountID`
The address of one signer, in base58.
Identifies which signer from the (predefined) [multi-signing list](reference-transaction-format.html#multi-signing) this portion of the multi-signature represents.
### `Signers[*].TxnSignature`
One signature, as hexadecimal.
Verifying a [multi-signed transaction](reference-transaction-format.html#multi-signing) involves making sure each such signature is valid for its `SigningPubKey` and the transaction instructions.
### `Signers[*].SigningPubKey`
The public key of one signer. Verifying a [multi-signed transaction](reference-transaction-format.html#multi-signing) involves making sure each such key is authorized to sign for the `AccountID` of the signer.
Multi-signature `AccountIDs` are a little special. If one is an address that doesn't exist in the ledger, then the `SigningPubKey` must hash to the `AccountID` value. If the address does exist in the ledger, then either:
1. The `SigningPubKey` must hash to the `AccountID` and the address must not have the master key disabled.
or
2. The `SigningPubKey` must hash to a regular key that the address has set in the ledger.
For more information about signing transactions, see [Signing and Submitting Transactions](reference-transaction-format.html#signing-and-submitting-transactions).

4
content/reference-transaction-format.md
View File

@@ -25,7 +25,9 @@ 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.
For more information about master and regular keys, see [Understanding Master and Regular Keys](concept-keys.md).
For more information about master and regular keys, see [Understanding Master and Regular Keys](concept-keys.html).
For more information about signatures, see [Understanding Signatures](concept-signatures.html).
## Signing and Submitting Transactions

21
content/rippled-api-methods/wallet_propose.md
View File

@@ -164,19 +164,24 @@ Connecting to 127.0.0.1:5005
<!-- MULTICODE_BLOCK_END -->
The response follows the [standard format](#response-formatting), with a successful result containing various important information about the new account, including the following fields:
The response follows the [standard format](#response-formatting), with a successful result containing various important information about the new (potential) account, including the following fields:
***TODO: Question: Fleshed out some of the descrs below using excellent source material from Rome. Thought it would be useful to surface.***
| `Field` | Type | Description |
|:------------------|:-------|:------------------------------------------------|
| `master_seed` | String | The master seed from which all other information about this account is derived, in Ripple's [base58][] encoded string format. This is the private key of the key pair. |
| `master_seed_hex` | String | The master seed, in hex format. |
| `master_key` | String | The master seed, in [RFC 1751](http://tools.ietf.org/html/rfc1751) format. |
| `account_id` | String | The [Address][] of the account. |
| `public_key` | String | The public key of the account, in encoded string format. |
| `public_key_hex` | String | The public key of the account, in hex format. |
| `master_seed` | String | This is the private key of the key pair. The master seed from which all other information about this account is derived, in Ripple's [base58][] encoded string format. Typically, you use the key in this format to sign transactions. |
| `master_seed_hex` | String | The master seed, in hex format. A simple, widely-supported way to represent the secret key. Can be used to sign transactions. |
| `master_key` | String | The master seed, in [RFC 1751](http://tools.ietf.org/html/rfc1751) format. An easier to remember, easier-to-write-down version of the private key. Can be used to sign transactions. |
| `account_id` | String | The [Address][] of the account in base58 format. This is not the public key, but a hash-of-a-hash of it. It also has a checksum so a typo almost certainly results in an invalid address rather than a valid, but different address. This is the primary identifier of an account in the XRP Ledger. You tell people this to get paid, and use it in transactions to indicate who you are and who you're paying, trusting, and so forth. [Multi-signing lists](tutorial-multisign.html) also use these to identify other signers. |
| `public_key` | String | The public key of the account, in Ripple's [base58][] encoded string format. |
| `public_key_hex` | String | This is the public key of the key pair. The public key of the account, in hex format. You need this to validate the signature on a transaction (or any signature). When you send a transaction, it attaches the public key so you can do so. |
| `warning` | String | (May be omitted) If the request specified a seed value, this field provides a warning that it may be insecure. [New in: rippled 0.32.0][] |
The key generated by this method can also be used as a regular key for an account if you use the [SetRegularKey transaction type](reference-transaction-format.html#setregularkey) to do so.
You can also use this method to generate a key to use as a regular key for an account. You assign regular keys to an account to be able to sign most transactions with them, while keeping your master keys offline whenever possible.
For more information about master and regular keys, see [Understanding Master and Regular Keys](concept-keys.html)
#### Possible Errors

12
content/transactions/setregularkey.md
View File

@@ -2,11 +2,11 @@
[[Source]<br>](https://github.com/ripple/rippled/blob/4239880acb5e559446d2067f00dabb31cf102a23/src/ripple/app/transactors/SetRegularKey.cpp "Source")
A SetRegularKey transaction assigns, changes, or removes the regular key associated with an account.
A `SetRegularKey` transaction assigns, changes, or removes the regular key associated with an account.
For more information about regular and master keys, see [Understanding Master and Regular Keys](reference-transaction-format.html#understanding-master-and-regular-keys).
You can protect your account by assigning regular keys to it and using them instead of the master keys to sign transactions whenever possible. If your regular keys are compromised, but your master keys are not, you can use a `SetRegularKey` transaction to regain control of your account.
You can protect your master secret by assigning regular keys to an account and using them instead of the master keys to sign transactions whenever possible. If your regular keys are compromised, but the master keys are not, you can use a SetRegularKey transaction to regain control of your account.
For more information about regular and master keys, see [Understanding Master and Regular Keys](concept-keys.html).
For a tutorial on assigning regular keys to an account, see [Working with Regular Keys](tutorial-regular-keys.html).
@@ -22,6 +22,6 @@ For even greater security, you can use [multi-signing](#multi-signing), but mult
}
```
| Field | JSON Type | [Internal Type][] | Description |
|:-----------|:----------|:------------------|:--------------------------------|
| RegularKey | String | AccountID | _(Optional)_ A base-58-encoded [Ripple address](reference-rippled.html#addresses) to use as the regular key. If omitted, removes the existing regular key. |
| Field | JSON Type | [Internal Type][] | Description |
|:-------------|:----------|:------------------|:------------------------------|
| `RegularKey` | String | AccountID | _(Optional)_ A base-58-encoded [Ripple address](reference-rippled.html#addresses) to use as the regular key. If omitted, removes the existing regular key. |

174
content/tutorial-regular-keys.md
View File

@@ -1,10 +1,10 @@
# Working with Regular Keys
Assign regular keys to your funded 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.
Assign regular keys to your account to enable you to sign most transactions with regular keys, while keeping your master keys offline and safe from malicious actors. A master key compromise 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).
For more information about master and regular keys, see [Understanding Master and Regular Keys](concept-keys.html).
This tutorial covers:
This article provides the following tutorials:
* [Assigning Regular Keys](#assigning-regular-keys)
* [Removing or Changing Regular Keys](#removing-or-changing-regular-keys)
@@ -12,113 +12,21 @@ This tutorial covers:
## Assigning Regular Keys
This tutorial walks you through the steps required to assign regular keys to an account:
This tutorial walks you through the steps required to assign regular keys to your 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)
***TODO: I removed the steps to create an account and fund an account. These are prereqs that introduce confusion when included in this flow. The overview of keys talks about the `account_id` returned by `wallet_propose` and makes the point that an actual account does not exist until it is funded by a payment that meets the reserve requirement. Do we need a tutorial on creating an account?***
1. [Generate keys](#1-generate-keys)
2. [Assign the keys to your account as regular keys](#2-assign-keys-to-your-account-as-regular-keys)
3. [Submit a test payment using regular keys](#3-submit-a-test-payment-using-regular-keys)
4. [Explore next steps](#4-explore-next-steps)
### 1. Generate Keys
### 1. Generate an `account_id` and Keys
Use the [`wallet_propose`](reference-rippled.html#wallet-propose) method to generate the keys that you'll assign to your account as regular keys.
If you already have a funded account, skip this step.
Use the [`wallet_propose`](reference-rippled.html#wallet-propose) method to generate an `account_id`, along with 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": "MAS TER PRIV ATE KEY RFC 1751 XXX XXXX XXX XXXX XXXX",
"master_seed": "MasterPrivateKeyXXXXXXXXXXXXX",
"master_seed_hex": "MasterPrivateKeyHexXXXXXXXXXXXXX",
"public_key": "aBQEK3r6hb8isnCWmortkNdv3MSMKP74o7gj3kHZQF9vDkbXo4Qs",
"public_key_hex": "032D911AE9887278110A8FE25169546D4E95A82AF5EFA25525FC3FDFFDC5A8B604"
},
"status": "success",
"type": "response"
}
```
### 2. Create and Fund an Account
If you already have a funded account, skip this step.
An `account_id`, such as the one generated in step 1, is not an actual account until it is funded. The act of sending a [`Payment`](reference-transaction-format.html#payment) transaction to the `account_id` creates the account in the XRP Ledger and funds it. After the account is created and funded, you can assign regular keys to it. ***TODO: Still working on this...***
In the `Payment` 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. ***TODO: Does not necessarily need to be the master_seed that signs. Could be whatever key the funding account uses to sign transactions.***
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.
Here's an example `wallet_propose` request and response:
#### WebSocket Request
@@ -147,18 +55,24 @@ Here's an example `wallet_propose` request and response.
}
```
In the next step, you'll use the `account_id` from this response to assign the keys as regular keys to your account.
### 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.
### 2. Assign Keys to Your Account as Regular Keys
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.
Use the [`SetRegularKey`](reference-transaction-format.html#setregularkey) method to assign the keys you generated in step 1 to your account as regular keys.
In the request, send your account's `account_ID` as the `account` value, your account's `master_key`, `master_seed`, or `master_seed_hex` (master private key) as the `secret` value, and the `account_id` generated in step 1 as the `RegularKey` value.
Here's an example `SetRegularKey` request and response.
#### WebSocket Request:
**Note:** This request format uses the `submit` command and a `tx_json` object to sign and submit this transaction all at once. This practice is recommended for **testing and development purposes only**. Transmitting your account secret is dangerous, so you should do this only from within a trusted and encrypted connection, or through a local connection, and only to a server you control.
***TODO: Question: Should this tutorial walk folks through the process of offline signing and then submission? It feels weird to say that they should keep their master keys offline and then have them send their secret in the request below. Is our approach to tutorials that they should show a user how something works for test and dev purposes? Just to show results quickly? Or is it to illustrate best practices for how a task should be performed day-to-day? If yes, then I think I need to get ripple-lib setup to do offline signing and a submit here in the tutorial. https://ripple.com/build/rippleapi/#offline-functionality -- this offline signing is not working for me right off the bat. Errors are not being returned, so I can't troubleshoot. I am sure that I'm missing a few steps -- will require research.***
```
{
"command" : "submit",
@@ -198,27 +112,35 @@ Here's an example `SetRegularKey` request and response.
}
```
This response contains a `SigningPubKey` field, which is the public key of the sending account in hex format. For more information about signatures, see [Understanding Signatures](concept-signatures.html)
### 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.
### 3. Submit a Test Payment Using 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.
To verify that the regular keys are set correctly on your account, send a test [`Payment`](reference-transaction-format.html#payment) transaction from your account, signing it with the regular keys you assigned to your account in step 2.
***TODO: Question: I keep referring to "keys" plural. Is that correct? When you sign a transaction, you send a single key value -- but in reality, multiple keys are being used, even if indirectly, to actually sign the transaction, is that right? Is that why using "keys" plural is accurate?***
In the request, send your account's `account_id` as the `Account` value and the `master_key`, `master_seed`, or `master_seed_hex` (regular private key) generated in step 1 as the `secret` value.
Here's an example `Payment` request and response.
#### WebSocket Request:
**Note:** This request format uses the `submit` command and a `tx_json` object to sign and submit this transaction all at once. This practice is recommended for **testing and development purposes only**. Transmitting your account secret is dangerous, so you should do this only from within a trusted and encrypted connection, or through a local connection, and only to a server you control.
***TODO: Question: What do we recommend here - even if we have set a regular key, do we still recommend signing offline to keep the secret/regular private key offline?***
```
{
"method":"submit",
"secret":"RegularPrivateKeyXXXXXXXXXXXX",
"tx_json": {
"Account":"rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt",
"Account":"rf9vUoqa83foreMr6CYFCEPTZUFagZv83c",
"Fee":"10",
"Amount":"10000000",
"Destination":"rPZXdWPxSXCBfnSXGnnBhXjhJ8V5K7oB5s",
"Destination":"rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt",
"TransactionType":"Payment"
}
}
@@ -227,8 +149,6 @@ Here's an example `Payment` request and response.
#### WebSocket Response:
***TODO: Per earlier comment on a concepts doc about signatures, I think it would be useful to be able to link to such a doc to call out the SigningPubKey and/or TxnSignature. I think it's relevant in that the keys topic is surfaced via a discussion of transaction authorization via signing.***
```
{
"result": {
@@ -254,7 +174,10 @@ Here's an example `Payment` request and response.
}
```
### 6. Explore Next Steps
This response contains a `SigningPubKey` field, which is the public key of the sending account in hex format. For more information about signatures, see [Understanding Signatures](concept-signatures.html)
### 4. 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:
@@ -265,16 +188,21 @@ Now that you're familiar with the benefits of assigning regular keys to an accou
## 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?***
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 your 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).
The steps to change your regular keys are the same as the steps to [assign regular keys](#assigning-regular-keys). You generate keys and assign them to your account as regular keys, overwriting any existing 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.
If you want to simply remove compromised regular keys from your account, use the [`SetRegularKey`](reference-transaction-format.html#setregularkey) method and omit the `RegularKey` value in the request.
***TODO: Is it valid to treat these as two separate flows - change vs remove? If you are doing security maintenance, it may be convenient to change them. If the keys are compromised, you may want to just quickly remove the keys, and generate and assign new keys later, or not at all. Valid?***
Here's an example `SetRegularKey` request and response that removes any existing regular keys from an account:
***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:
**Note:** This request format uses the `submit` command and a `tx_json` object to sign and submit this transaction all at once. This practice is recommended for **testing and development purposes only**. Transmitting your account secret is dangerous, so you should do this only from within a trusted and encrypted connection, or through a local connection, and only to a server you control.
```
{
"command" : "submit",
@@ -312,7 +240,7 @@ If you want to remove compromised regular keys and assign new regular keys later
}
```
Here's an example response for a `Payment` transaction signed using an invalid regular key.
Here's an example error response for a `Payment` transaction signed using an invalid regular key.
#### WebSocket Response:
@@ -339,8 +267,8 @@ Here's an example response for a `Payment` transaction signed using an invalid r
In some cases, you can even send a [key reset transaction](concept-transaction-cost.html#key-reset-transaction) without paying the [transaction cost](reference-transaction-format.html#transaction-cost).
***TODO: I don't understand how this key reset transaction mentioned above works. Is it different from sending a SetRegularKey transaction that omits or changes the RegularKey value assigned to an account? Is the difference that the transaction cost can be 0? Does this mean that I can send a SetRegularKey transaction that omits or changes the RegularKey value assigned to an account and includes `Fee : 0` - as long as the `lsfPasswordSpent` flag is disabled? When I send such a transaction for a newly funded account that has had no activity on it other than one payment to fund it and one SetRegularKeys transaction for a `Fee : 10`, I get a response that says: `Fee insufficient`.***
***TODO: I don't understand how this key reset transaction mentioned above works. Is it different from sending a SetRegularKey transaction that omits or changes the RegularKey value assigned to an account? Is the difference that the transaction cost can be 0? Does this mean that I can send a SetRegularKey transaction that omits or changes the RegularKey value assigned to an account and includes `Fee : 0` - as long as the `lsfPasswordSpent` flag is disabled? When I send such a transaction to a newly funded account that has had no activity on it other than one payment to fund it and one SetRegularKeys transaction for a `Fee : 10`, I get a response that says: `Fee insufficient`.***
***TODO: I understand that the account's `lsfPasswordSpent` flag must be disabled and that it starts out disabled. We say: "As a special case, an account can send a SetRegularKey transaction with a transaction cost of 0, as long as the account's lsfPasswordSpent flag is disabled. This transaction must be signed by the account's master key pair. Sending this transaction enables the lsfPasswordSpent flag. The lsfPasswordSpent flag starts out disabled. It gets enabled when you send a SetRegularKey transaction signed by the master key pair. It gets disabled again when the account receives a Payment of XRP." When we say that sending the transaction enables the flag - this means that it started off as disabled, fulfilled the `Fee : 0` key reset, and then enabled the flag to deny any further SetRegularKey with `Fee : 0` transaction requests? And it will continue to deny these requests until the account receives a payment? This means that if you are afraid that your account balance is close to 0, you should use your one SetRegularKey with `Fee : 0` to change your RegularKey value and not just remove it. If you remove it, then you won't be able to pay for the transaction to set a new value, correct?***
***TODO: This piece of info is important -- but until I understand the key reset transaction, it is difficult to explain when this prioritization will happen: "When the FeeEscalation amendment is enabled, rippled prioritizes key reset transactions above other transactions even though the nominal transaction cost of a key reset transaction is zero.***
***TODO: This piece of info is important -- but until I understand the key reset transaction, it is difficult to explain how/when this prioritization will happen: "When the FeeEscalation amendment is enabled, rippled prioritizes key reset transactions above other transactions even though the nominal transaction cost of a key reset transaction is zero.***