ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-12-06 17:27:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

addressed feedback

Browse Source
This commit is contained in:
Jennifer Hasegawa
2018-02-08 18:02:46 -08:00
parent f240e11459
commit 2c2450d7de
6 changed files with 192 additions and 167 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
content/concept-keys.md
View File

@@ -7,13 +7,13 @@ You generate a key pair using the `wallet_propose` method. Here's a sample `wall
```
{
"result": {
"account_id": "rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt",
"account_id": "rDGnaDqJczDAjrKHKdhGRJh2G7zJfZhj5q",
"key_type": "secp256k1",
"master_key": "PRIV ATE KEY RFC 1751 XXX XXXX XXX XXXX XXX XXX XXXX",
"master_seed": "PrivateKeyXXXXXXXXXXXXXXXXXXX",
"master_seed_hex": "PrivateKeyHexXXXXXXXXXXXXXXXXXXX",
"public_key": "aBQEK3r6hb8isnCWmortkNdv3MSMKP74o7gj3kHZQF9vDkbXo4Qs",
"public_key_hex": "032D911AE9887278110A8FE25169546D4E95A82AF5EFA25525FC3FDFFDC5A8B604"
"master_key": "COON WARN AWE LUCK TILE WIRE ELI SNUG TO COVE SHAM NAT",
"master_seed": "sstV9YX8k7yTRzxkRFAHmX7EVqMfX",
"master_seed_hex": "559EDD35041D3C11F9BBCED912F4DE6A",
"public_key": "aBQXEw1vZD3guCX3rHL8qy8ooDomdFuxZcWrbRZKZjdDkUoUjGVS",
"public_key_hex": "0351BDFB30E7924993C625687AE6127034C4A5EBA78A01E9C58B0C46E04E3A4948"
},
"status": "success",
"type": "response"
@@ -22,63 +22,63 @@ You generate a key pair using the `wallet_propose` method. Here's a sample `wall
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
**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**
#### 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 corresponding to the private key that signed the transaction.
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.
**account_id**
***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?)***
The `account_id` is [derived from 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. In addition, the `account_id` can't send any transactions until after it's received a transaction that funds and creates the account.
The `account_id` (without a funded account) can, however, be used as a regular key or a member of a signer list to authorize transactions for another account that does exist.
#### `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).
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.
You use this generated key pair in one of three ways: as master keys, regular keys, or [signer list members](tutorial-multisign.html).
## 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:
The master key pair, called a "master key," is composed of a private key and a public key. In addition to being able to sign all transactions that a regular key can, the master key's private key is the only key that can be used to perform the following actions:
* 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).
* [Disable the master public key](reference-transaction-format.html#accountset-flags).
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`.
* Permanently give up the ability to [freeze](concept-freeze.html#no-freeze).
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).
* Send a cost-0 [key reset transaction](concept-transaction-cost.html#key-reset-transaction).
**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).
The master key for an account is generated in the same [`wallet_propose`](reference-rippled.html#wallet-propose) response as the `account_id` of the account the master key is authorized to sign transactions for. Because the master key is generated in the same response, it is [intrinsically related](concept-accounts.html#address-encoding) to the `account_id`, which is derived from the `public_key_hex`.
***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 as opposed to a regular key, which is also generated using the `wallet_propose` method, but which must be explicitly assigned as a regular key to an account. Because a regular key is explicitly assigned, it are not intrinsically related to the `account_id` of the account is are authorized to sign transactions for. For more information, see [Regular Keys](#regular-keys).
This is a compelling reason to keep your master keys offline and set up regular keys to sign transactions from your account instead.
**Caution:** A master key cannot be changed, but it 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).
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.
This is a compelling reason to keep your master key offline and set up a regular key to sign transactions from your account instead.
Keeping your master key 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, a master key is used only on the most trusted of devices and for emergencies only, such as to change a regular key in the event of a possible or actual compromise.
## Regular Keys
You assign regular keys to an account to be able to sign most transactions with them, while keeping your master keys offline.
The XRP Ledger allows an account to authorize a secondary key pair, called a "regular key," to sign future transactions, while keeping your master keys offline. If the private key of a regular key is compromised, you can remove or replace it without changing the rest of your account and re-establishing its relationships to other accounts. You can also rotate a regular key proactively. (Neither of those things is possible for the master key pair of an account, which is intrinsically linked to the account's address.)
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.
You generate a key to use as a regular key 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 explicitly create the relationship between a regular key and the account you want them to sign transactions for. You use the [`SetRegularKey`](reference-transaction-format.html#setregularkey) method to assign a regular key to an account.
For a tutorial on assigning regular keys, see [Working with Regular Keys](tutorial-regular-keys.html).
For a tutorial on assigning a regular key, see [Working with Regular Keys](tutorial-regular-keys.html).
Once you assign regular keys to an account, the account has two key pairs associated with it:
Once you assign a regular key to an account, the account has two keys associated with it:
* "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.
* A "master" key that is intrinsically related to the account's `account_id` and which you keep offline.
* A "regular" key that you've explicitly assigned to the account and which you use to sign transactions for the account.
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 assign one regular key 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.
You can remove or change a regular key 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.
For a tutorial on changing or removing regular keys, see [Working with Regular Keys](tutorial-regular-keys.html).
For a tutorial on changing or removing a regular key, see [Working with Regular Keys](tutorial-regular-keys.html).

26
content/concept-signatures.md
View File

@@ -1,36 +1,41 @@
# Understanding Signatures
***TODO: DRAFT***
***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)
***TODO: JHA fix the IA here. Also need to more clearly express the single-signer flow vs multi-signer flow. Provide a flow diagram. Also need to move some conceptual content out of "Authorizing Transactions" and "Signing and Submitting Transactions" and put it in this doc.***
The public key of the sender in hex format.
## `SigningPubKey` (top-level)
To verify whether a transaction is valid, you check that all of the following are true:
The public key of the sender in hex format. Empty in the case of a multi-signed transaction.
To verify whether a single-signed transaction is valid, a `rippled` server checks 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).
The default is that only "the address of an account" is authorized to send all transactions for that account. That address is [derived from](concept-accounts.html#address-encoding) 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.
3. The signature matches the transaction instructions.
The validation process for multi-signed transactions is slightly different. For more information, see [`Signers[*].SigningPubKey`](#signerssigningpubkey).
### `Signature`
## `TxnSignature` (top-level)
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.
***TODO: Ensure that this doc reflects this: In transactions, we have two TxnSignature fields—one at the top level for single-signed transactions, and one in each member of the Signers array for multi-signed transactions. (Any given transaction has either the top level TxnSignature or the members in the Signers array but not both.)***
### `Signers` (in a multi-signed transaction)
## `Signers` (in a multi-signed transaction)
An array of signature data for a [multi-signed transaction](reference-transaction-format.html#multi-signing).
@@ -40,6 +45,7 @@ Used to verify that a quorum of signers approved a transaction.
### `Signers[*].AccountID`
The address of one signer, in base58.
***TODO: JHA: Slightly nitpicky note (relevant to all the fields, but it especially attracted my notice here): the base58 is how it's generally represented in JSON. In the canonical binary format, I believe this is the AccountID as a 160-bit number, so it's not base58-encoded and doesn't have the checksum in the binary format. Similarly, hexadecimal is just a way of representing a 160-bit number in formats like JSON. In the native binary format, the various fields are just numbers/data in various low-level computer formats. That's only relevant for people who are trying to implement offline signing, though. Everyone else will probably see the JSON representation, where they'll want to know what the conventional way to represent the fields is.***
Identifies which signer from the (predefined) [multi-signing list](reference-transaction-format.html#multi-signing) this portion of the multi-signature represents.
@@ -55,7 +61,7 @@ Verifying a [multi-signed transaction](reference-transaction-format.html#multi-s
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:
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 using the standard rules for [deriving an AccountID](concept-accounts.html#address-encoding) from a public key. 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.

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

@@ -166,22 +166,24 @@ Connecting to 127.0.0.1:5005
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 | 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. |
| `public_key` | String | The public key of the key pair, in Ripple's [base58][] encoded string format. |
| `public_key_hex` | String | This is the public key of the key pair, in hexadecimal. To validate the signature on a transaction, `rippled` needs this public key. That's why the format for a signed transaction includes the public key in the `SigningPubKey` field. |
| `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][] |
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.
You can also use this method to generate a key to use as a regular key for an account. You assign a regular key to an account to be able to sign most transactions with it, while keeping your master key offline whenever possible.
In addition to using it as a regular key, you can also use it as a member of a multi-signing list (SignerList).
For more information about master and regular keys, see [Understanding Master and Regular Keys](concept-keys.html)
For more information about multi-signing and signer lists, see [Multi-Signing](reference-transaction-format.html#multi-signing).
#### Possible Errors

4
content/transactions/setregularkey.md
View File

@@ -4,11 +4,11 @@
A `SetRegularKey` transaction assigns, changes, or removes the regular key associated with an account.
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 account by assigning a regular key to it and using it instead of the master key to sign transactions whenever possible. If your regular key is compromised, but your master key is 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).
For a tutorial on assigning a regular key to an account, see [Working with Regular Keys](tutorial-regular-keys.html).
For even greater security, you can use [multi-signing](#multi-signing), but multi-signing requires additional XRP for the [transaction cost](concept-transaction-cost.html) and [reserve](concept-reserves.html).

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

@@ -1,30 +1,28 @@
# 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 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.
The XRP Ledger allows an account to authorize a secondary key pair, called a "regular key," to sign future transactions. If the private key of a regular key is compromised, you can remove or replace it without changing the rest of your account and re-establishing its relationships to other accounts. You can also rotate a regular key proactively. (Neither of those things is possible for the master key pair of an account, which is intrinsically linked to the account's address.)
For more information about master and regular keys, see [Understanding Master and Regular Keys](concept-keys.html).
This article provides the following tutorials:
* [Assigning Regular Keys](#assigning-regular-keys)
* [Removing or Changing Regular Keys](#removing-or-changing-regular-keys)
* [Assigning a regular key](#assigning-a-regular-key)
* [Removing or changing a regular key](#removing-or-changing-a-regular-key)
## Assigning Regular Keys
## Assigning a Regular Key
This tutorial walks you through the steps required to assign regular keys to your account:
This tutorial walks you through the steps required to assign a regular key to your account:
***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)
1. [Generate a key](#1-generate-a-key)
2. [Assign the key to your account as a regular key](#2-assign-the-key-to-your-account-as-a-regular-key)
3. [Submit an `AccountSet` transaction using the regular key](#3-submit-an-accountset-transaction-using-the-regular-key)
4. [Explore next steps](#4-explore-next-steps)
### 1. Generate Keys
### 1. Generate a Key
Use the [`wallet_propose`](reference-rippled.html#wallet-propose) method to generate the keys that you'll assign to your account as regular keys.
Use the [`wallet_propose`](reference-rippled.html#wallet-propose) method to generate the key that you'll assign to your account as a regular key.
Here's an example `wallet_propose` request and response:
@@ -42,46 +40,147 @@ Here's an example `wallet_propose` request and response:
```
{
"result": {
"account_id": "rf9vUoqa83foreMr6CYFCEPTZUFagZv83c",
"account_id": "rsprUqu6BHAffAeG4HpSdjBNvnA6gdnZV7",
"key_type": "secp256k1",
"master_key": "REG ULAR PRIV ATE KEY RFC 1751 XXX XXXX XXX XXXX XXX",
"master_seed": "RegularPrivateKeyXXXXXXXXXXXX",
"master_seed_hex": "RegularPrivateKeyHexXXXXXXXXXXXX",
"public_key": "aBR9dmoHfrfU24q1cbjdehNsFiuV9k5PrrQTLiH42qxhWr5ybc1K",
"public_key_hex": "03A45E8E4BFECA7473F932839B982C33CD2FB7B788932A21DCDD8536AE63A1614C"
"master_key": "KNEW BENT LYNN LED GAD BEN KENT SHAM HOBO RINK WALT ALLY",
"master_seed": "sh8i92YRnEjJy3fpFkL8txQSCVo79",
"master_seed_hex": "966C0F68643EFBA50D58D191D4CA8AA7",
"public_key": "aBRNH5wUurfhZcoyR6nRwDSa95gMBkovBJ8V4cp1C1pM28H7EPL1",
"public_key_hex": "03AEEFE1E8ED4BBC009DE996AC03A8C6B5713B1554794056C66E5B8D1753C7DD0E"
},
"status": "success",
"type": "response"
}
```
In the next step, you'll use the `account_id` from this response to assign the keys as regular keys to your account.
In the next step, you'll use the `account_id` from this response to assign the key as a regular key to your account.
### 2. Assign Keys to Your Account as Regular Keys
### 2. Assign the Key to Your Account as a Regular Key
Use the [`SetRegularKey`](reference-transaction-format.html#setregularkey) method to assign the keys you generated in step 1 to your account as regular keys.
Use the [`SetRegularKey`](reference-transaction-format.html#setregularkey) method to assign the key you generated in step 1 to your account as a regular key.
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.
When assigning a regular key to your account for the first time, the `SetRegularKey` method requires signing by your account's master private key (secret). Transmitting your master private key is dangerous, so we'll complete this transaction in two steps to keep transaction signing separate from transaction submission to the network.
Here's an example `SetRegularKey` request and response.
When you make subsequent `SetRegularKey` requests, you can sign using the existing regular key to replace or [remove itself](#removing-or-changing-a-regular-key).
#### Sign Your Transaction
The most secure way to sign a transaction is to do it offline with a signing library, such as [RippleAPI](reference-rippleapi.html#offline-functionality). Alternatively, you can sign the transaction using the [`sign`](reference-rippled.html#sign) command, but this must be done through a trusted and encrypted connection, or through a local connection, and only to a server you control.
In the transaction JSON, use 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 `sign` request and response for a `SetRegularKey` type transaction:
##### WebSocket Request:
```
{
"command": "sign",
"tx_json" : {
"TransactionType" : "SetRegularKey",
"Account" : "rUAi7pipxGpYfPNg3LtPcf2ApiS8aw9A93",
"RegularKey" : "rsprUqu6BHAffAeG4HpSdjBNvnA6gdnZV7"
},
"secret" : "ssCATR7CBvn4GLd1UuU2bqqQffHki"
}
```
##### WebSocket Response:
```
{
"result": {
"tx_blob": "1200052280000000240000000468400000000000000A73210384CA3C528F10C75F26E0917F001338BD3C9AA1A39B9FBD583DFFFD96CF2E2D7A7446304402204BCD5663F3A2BA02D2CE374439096EC6D27273522CD6E6E0BDBFB518730EAAE402200ECD02D8D2525D6FA4642613E71E395ECCEA01C42C35A668BF092A00EB649C268114830923439D307E642CED308FD91EF701A7BAA74788141620D685FB08D81A70D0B668749CF2E130EA7540",
"tx_json": {
"Account": "rUAi7pipxGpYfPNg3LtPcf2ApiS8aw9A93",
"Fee": "10",
"Flags": 2147483648,
"RegularKey": "rsprUqu6BHAffAeG4HpSdjBNvnA6gdnZV7",
"Sequence": 4,
"SigningPubKey": "0384CA3C528F10C75F26E0917F001338BD3C9AA1A39B9FBD583DFFFD96CF2E2D7A",
"TransactionType": "SetRegularKey",
"TxnSignature": "304402204BCD5663F3A2BA02D2CE374439096EC6D27273522CD6E6E0BDBFB518730EAAE402200ECD02D8D2525D6FA4642613E71E395ECCEA01C42C35A668BF092A00EB649C26",
"hash": "AB73BBF7C99061678B59FB48D72CA0F5FC6DD2815B6736C6E9EB94439EC236CE"
}
},
"status": "success",
"type": "response"
}
```
The `sign` command response contains a `tx_blob` value, as shown above. The offline signing response contains a `signedTransaction` value. Both are signed binary representations (blobs) of the transaction.
Next, use the `submit` command to transmit the transaction blob (`tx_blob` or `signedTransaction`) to the network.
#### Submit Your Transaction
Take the `signedTransaction` value from the offline signing response or the `tx_blob` value from the `sign` command response and submit it as the `tx_blob` value using the [`submit`](reference-rippled.html#submit) command.
Here's an example `submit` request and response for a `SetRegularKey` type transaction.
##### WebSocket Request:
```
{
"command": "submit",
"tx_blob": "1200052280000000240000000468400000000000000A73210384CA3C528F10C75F26E0917F001338BD3C9AA1A39B9FBD583DFFFD96CF2E2D7A7446304402204BCD5663F3A2BA02D2CE374439096EC6D27273522CD6E6E0BDBFB518730EAAE402200ECD02D8D2525D6FA4642613E71E395ECCEA01C42C35A668BF092A00EB649C268114830923439D307E642CED308FD91EF701A7BAA74788141620D685FB08D81A70D0B668749CF2E130EA7540"
}
```
##### 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": "1200052280000000240000000468400000000000000A73210384CA3C528F10C75F26E0917F001338BD3C9AA1A39B9FBD583DFFFD96CF2E2D7A7446304402204BCD5663F3A2BA02D2CE374439096EC6D27273522CD6E6E0BDBFB518730EAAE402200ECD02D8D2525D6FA4642613E71E395ECCEA01C42C35A668BF092A00EB649C268114830923439D307E642CED308FD91EF701A7BAA74788141620D685FB08D81A70D0B668749CF2E130EA7540",
"tx_json": {
"Account": "rUAi7pipxGpYfPNg3LtPcf2ApiS8aw9A93",
"Fee": "10",
"Flags": 2147483648,
"RegularKey": "rsprUqu6BHAffAeG4HpSdjBNvnA6gdnZV7",
"Sequence": 4,
"SigningPubKey": "0384CA3C528F10C75F26E0917F001338BD3C9AA1A39B9FBD583DFFFD96CF2E2D7A",
"TransactionType": "SetRegularKey",
"TxnSignature": "304402204BCD5663F3A2BA02D2CE374439096EC6D27273522CD6E6E0BDBFB518730EAAE402200ECD02D8D2525D6FA4642613E71E395ECCEA01C42C35A668BF092A00EB649C26",
"hash": "AB73BBF7C99061678B59FB48D72CA0F5FC6DD2815B6736C6E9EB94439EC236CE"
}
},
"status": "success",
"type": "response"
}
```
Note that the response contains a `hash` of the transaction, which you can use to [look up the transaction's final outcome](reference-rippled.html#tx).
### 3. Submit an `AccountSet` Transaction Using the Regular Key
To verify that your account has the regular key set correctly, send an [`AccountSet`](reference-transaction-format.html#accountset) transaction from your account, signing it with the regular key you assigned to your account in step 2.
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 `AccountSet` request and response. Note that the request does not include any `AccountSet` options. This means that a successful transaction has no effect other than to confirm that the regular key is set correctly for your account (and to destroy the transaction cost).
#### 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",
"tx_json" : {
"TransactionType" : "SetRegularKey",
"Account" : "rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt",
"RegularKey" : "rf9vUoqa83foreMr6CYFCEPTZUFagZv83c"
"TransactionType": "AccountSet",
"Account" : "rUAi7pipxGpYfPNg3LtPcf2ApiS8aw9A93"
},
"secret" : "MasterPrivateKeyXXXXXXXXXXXXX"
"secret" : "sh8i92YRnEjJy3fpFkL8txQSCVo79"
}
```
@@ -94,79 +193,16 @@ Here's an example `SetRegularKey` request and response.
"engine_result": "tesSUCCESS",
"engine_result_code": 0,
"engine_result_message": "The transaction was applied. Only final in a validated ledger.",
"tx_blob": "1200052280000000240000000168400000000000000A7321032D911AE9887278110A8FE25169546D4E95A82AF5EFA25525FC3FDFFDC5A8B604744730450221008EBFA6ABE01BB31A772816FF8560DA78273FA4DC982D0C85A6A516A9188AD70A02205CE1E9E3A685D4D29C62C9DA334BC8BB16468AAA11B572320AD2E98AE1B551BB8114E40BE141DFE3544627F98879C9A600974C4C37B3881443807E97EA8BCB97F4032DEFB4AC9208A359493E",
"tx_blob": "1200032280000000240000000368400000000000000A732103AEEFE1E8ED4BBC009DE996AC03A8C6B5713B1554794056C66E5B8D1753C7DD0E744730450221008F44064A901C3A170A046673EFC8091F2C409E1DB7D78A5EF0D18E9D868AE21002207F594F3BF3821E6DF64CD283F590F6578F809DFD1CAAF654F187645A7CAB91C48114830923439D307E642CED308FD91EF701A7BAA747",
"tx_json": {
"Account": "rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt",
"Fee": "10",
"Flags": 2147483648,
"RegularKey": "rf9vUoqa83foreMr6CYFCEPTZUFagZv83c",
"Sequence": 1,
"SigningPubKey": "032D911AE9887278110A8FE25169546D4E95A82AF5EFA25525FC3FDFFDC5A8B604",
"TransactionType": "SetRegularKey",
"TxnSignature": "30450221008EBFA6ABE01BB31A772816FF8560DA78273FA4DC982D0C85A6A516A9188AD70A02205CE1E9E3A685D4D29C62C9DA334BC8BB16468AAA11B572320AD2E98AE1B551BB",
"hash": "A9EE659DC08E6589F3454186C1D846763E55DEEF5525A8AE1F3D87B53EF5B86A"
}
},
"status": "success",
"type": "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)
### 3. Submit a Test Payment Using Regular Keys
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":"rf9vUoqa83foreMr6CYFCEPTZUFagZv83c",
"Fee":"10",
"Amount":"10000000",
"Destination":"rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt",
"TransactionType":"Payment"
}
}
```
#### 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": "1200002280000000240000000361400000000098968068400000000000000A732103A45E8E4BFECA7473F932839B982C33CD2FB7B788932A21DCDD8536AE63A1614C74463044022037DC86BEE1D0E1F394273B80E4072A35B2E221880879CC2C47FE0AD152B3E2120220511A6555B8A524321E962164EC830A83267AF97E9FDF24CCEC7B38944E2CC95C8114E40BE141DFE3544627F98879C9A600974C4C37B38314F779A56C00EF101471C8ADED9343532063E73AFE",
"tx_json": {
"Account": "rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt",
"Amount": "10000000",
"Destination": "rPZXdWPxSXCBfnSXGnnBhXjhJ8V5K7oB5s",
"Account": "rUAi7pipxGpYfPNg3LtPcf2ApiS8aw9A93",
"Fee": "10",
"Flags": 2147483648,
"Sequence": 3,
"SigningPubKey": "03A45E8E4BFECA7473F932839B982C33CD2FB7B788932A21DCDD8536AE63A1614C",
"TransactionType": "Payment",
"TxnSignature": "3044022037DC86BEE1D0E1F394273B80E4072A35B2E221880879CC2C47FE0AD152B3E2120220511A6555B8A524321E962164EC830A83267AF97E9FDF24CCEC7B38944E2CC95C",
"hash": "A8C3D091245794A664A5C1F0D275D1DB9A9349F1F873AABAD7AD1E43E8A117FB"
"SigningPubKey": "03AEEFE1E8ED4BBC009DE996AC03A8C6B5713B1554794056C66E5B8D1753C7DD0E",
"TransactionType": "AccountSet",
"TxnSignature": "30450221008F44064A901C3A170A046673EFC8091F2C409E1DB7D78A5EF0D18E9D868AE21002207F594F3BF3821E6DF64CD283F590F6578F809DFD1CAAF654F187645A7CAB91C4",
"hash": "BED704F2A6A80DA4060446C95802F205EE41977A2F63F10B1F8952FC6D01B35B"
}
},
"status": "success",
@@ -174,43 +210,39 @@ Here's an example `Payment` 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)
### 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:
Now that you're familiar with the benefits of assigning a regular key 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
## Removing or Changing a Regular Key
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?***
If your account's regular key is compromised, or if you just want to periodically change the regular key as a security measure, use the [`SetRegularKey`](reference-transaction-format.html#setregularkey) method to remove or change the regular key for your account.
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.
The steps to change your existing regular key are almost the same as the steps to [assign a regular key](#assigning-a-regular-key) for the first time. You generate the key and assign it to your account as a regular key, overwriting the existing regular key. However, the main difference is that when changing the existing regular key, you can use the existing regular key to replace itself, whereas when assigning a regular key to an account for the first time, you have to use the account's master key to do it.
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.
For more information about master and regular keys, see [Understanding Master and Regular Keys](concept-keys.html).
***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?***
If you want to simply remove a compromised regular key from your account, you don't need to generate a key pair first and just use the [`SetRegularKey`](reference-transaction-format.html#setregularkey) method, omitting the `RegularKey` value in the request. Note that the method fails if you don't have another way of signing for your account currently enabled (either the master key or a signer list).
Here's an example `SetRegularKey` request and response that removes any existing regular keys from an account:
Here's an example `SetRegularKey` request and response that removes an existing regular key from an account:
#### 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",
"tx_json" : {
"TransactionType" : "SetRegularKey",
"Account" : "rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt"
"Account" : "rUAi7pipxGpYfPNg3LtPcf2ApiS8aw9A93"
},
"secret" : "MasterPrivateKeyXXXXXXXXXXXXX"
"secret" : "sh8i92YRnEjJy3fpFkL8txQSCVo79"
}
```
@@ -223,16 +255,16 @@ Here's an example `SetRegularKey` request and response that removes any existing
"engine_result": "tesSUCCESS",
"engine_result_code": 0,
"engine_result_message": "The transaction was applied. Only final in a validated ledger.",
"tx_blob": "1200052280000000240000000468400000000000000A7321032D911AE9887278110A8FE25169546D4E95A82AF5EFA25525FC3FDFFDC5A8B60474463044022035B3076FED158D1CBFE2898521BDB068C6A2BE5C1BEA111D7F8611B1A35A10C302204CD5F547A7538C70404A5A157F5C1D4607B1F739C6C70D33895012E5B83E301E8114E40BE141DFE3544627F98879C9A600974C4C37B3",
"tx_blob": "1200052280000000240000000668400000000000000A732103AEEFE1E8ED4BBC009DE996AC03A8C6B5713B1554794056C66E5B8D1753C7DD0E744630440220703F4EB4D1DF90632DDEB0F3B72B41B7E85C739933C9AF55472BB154637645B202202689C22A10965DA0F0EA1D745EBB8E94E242572490FED69A059D724172E9DCFC8114830923439D307E642CED308FD91EF701A7BAA747",
"tx_json": {
"Account": "rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt",
"Account": "rUAi7pipxGpYfPNg3LtPcf2ApiS8aw9A93",
"Fee": "10",
"Flags": 2147483648,
"Sequence": 4,
"SigningPubKey": "032D911AE9887278110A8FE25169546D4E95A82AF5EFA25525FC3FDFFDC5A8B604",
"Sequence": 6,
"SigningPubKey": "03AEEFE1E8ED4BBC009DE996AC03A8C6B5713B1554794056C66E5B8D1753C7DD0E",
"TransactionType": "SetRegularKey",
"TxnSignature": "3044022035B3076FED158D1CBFE2898521BDB068C6A2BE5C1BEA111D7F8611B1A35A10C302204CD5F547A7538C70404A5A157F5C1D4607B1F739C6C70D33895012E5B83E301E",
"hash": "81F8D1D892D2A18814337470B02DD7AFA123CDDF85150DCE333674435254D046"
"TxnSignature": "30440220703F4EB4D1DF90632DDEB0F3B72B41B7E85C739933C9AF55472BB154637645B202202689C22A10965DA0F0EA1D745EBB8E94E242572490FED69A059D724172E9DCFC",
"hash": "15234F29930BFB8A87EB604D4E657CDEE277BAF9D670A90CDE2453A608A9A81C"
}
},
"status": "success",
@@ -240,7 +272,10 @@ Here's an example `SetRegularKey` request and response that removes any existing
}
```
Here's an example error response for a `Payment` transaction signed using an invalid regular key.
The way to verify that regular key removal succeeded is to confirm that you can't send a transaction using the removed regular key.
Here's an example error response for an `AccountSet` transaction signed using the regular key removed by the `SetRegularKey` transaction above.
#### WebSocket Response:
@@ -250,14 +285,11 @@ Here's an example error response for a `Payment` transaction signed using an inv
"error_code": 41,
"error_message": "Secret does not match account.",
"request": {
"method": "submit",
"secret": "RegularPrivateKeyXXXXXXXXXXXX",
"command": "submit",
"secret": "sh8i92YRnEjJy3fpFkL8txQSCVo79",
"tx_json": {
"Account": "rM8oJwkKtgEU2HZkCHsJScLHqegWpgBRxt",
"Amount": "10000000",
"Destination": "rPZXdWPxSXCBfnSXGnnBhXjhJ8V5K7oB5s",
"Fee": "10",
"TransactionType": "Payment"
"Account": "rUAi7pipxGpYfPNg3LtPcf2ApiS8aw9A93",
"TransactionType": "AccountSet"
}
},
"status": "error",
@@ -265,10 +297,4 @@ Here's an example error response for a `Payment` transaction signed using an inv
}
```
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 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 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.***
In some cases, you can even use the `SetRegularKey` method to send a [key reset transaction](concept-transaction-cost.html#key-reset-transaction) without paying the [transaction cost](reference-transaction-format.html#transaction-cost). With the enablement of the FeeEscalation amendment, `rippled` prioritizes key reset transactions above other transactions even though the nominal transaction cost of a key reset transaction is zero.

9
dactyl-config.yml
View File

@@ -371,15 +371,6 @@ pages:
- local
- ripple.com
- name: Signatures
category: Features
html: concept-signatures.html
md: concept-signatures.md
targets:
- local
- ripple.com
- name: Stand-Alone Mode
category: Features
html: concept-stand-alone-mode.html