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

Offline acct setup: finished draft

Browse Source
This commit is contained in:
mDuo13
2019-12-10 17:47:25 -08:00
parent bdcf1e5a47
commit 8425caf357
2 changed files with 219 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
content/concepts/payment-system-basics/accounts/cryptographic-keys.md
View File

@@ -75,7 +75,7 @@ This is as opposed to a regular key pair, which is also generated using the `wal
**Caution:** A master key pair cannot be changed, but it can be disabled. This means that if your master seed or secret key is compromised, rather than change it, you must [disable it](accountset.html). **Caution:** A master key pair cannot be changed, but it can be disabled. This means that if your master seed or secret key is compromised, rather than change it, you must [disable it](accountset.html).
Because a master key pair cannot be changed and can only disabled in the event of a compromise, this is a compelling reason to keep your master key pair offline and set up a regular key pair to sign transactions from your account instead. Because a master key pair cannot be changed and can only disabled in the event of a compromise, this is a compelling reason to [keep your master key pair offline](offline-account-setup.html) and set up a regular key pair to sign transactions from your account instead.
Keeping your master key pair offline means not putting your master secret key anywhere that 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 pair is used only on the most trusted of devices and for emergencies only, such as to change a regular key pair in the event of a possible or actual compromise. Keeping your master key pair offline means not putting your master secret key anywhere that 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 pair is used only on the most trusted of devices and for emergencies only, such as to change a regular key pair in the event of a possible or actual compromise.

233
content/tutorials/manage-account-settings/offline-account-setup.md
View File

@@ -12,10 +12,11 @@ To use offline signing, you must have the following
- The offline machine needs secure persistent storage (for example, an encrypted disk drive) and a way to [sign transactions](set-up-secure-signing.html) such as [`rippled` running in stand-alone mode](rippled-server-modes.html) or [ripple-lib](rippleapi-reference.html). - The offline machine needs secure persistent storage (for example, an encrypted disk drive) and a way to [sign transactions](set-up-secure-signing.html) such as [`rippled` running in stand-alone mode](rippled-server-modes.html) or [ripple-lib](rippleapi-reference.html).
- You must have a separate computer to use as an online machine. This machine does not need to run `rippled` but it must be able to connect to the XRP Ledger network and receive accurate information about the state of the shared ledger. For example, you can use a [WebSocket connection to a public server](get-started-with-the-rippled-api.html). - You must have a separate computer to use as an online machine. This machine does not need to run `rippled` but it must be able to connect to the XRP Ledger network and receive accurate information about the state of the shared ledger. For example, you can use a [WebSocket connection to a public server](get-started-with-the-rippled-api.html).
- You must have a secure way to transfer signed transaction binary data from the offline machine to the online machine. - You must have a secure way to transfer signed transaction binary data from the offline machine to the online machine.
- One way to do this is with a QR code generator on the offline machine, and a QR code scanner on the online machine. - One way to do this is with a QR code generator on the offline machine, and a QR code scanner on the online machine. (In this case, your "online machine" could be a handheld device such as a smartphone.)
- Another way is to copy files from the offline machine to an online machine using physical media. If you use this method, be sure not to use physical media that could infect your offline machine with malicious software. (For example, do not reuse the same USB drive on both online and offline machines.) - Another way is to copy files from the offline machine to an online machine using physical media. If you use this method, be sure not to use physical media that could infect your offline machine with malicious software. (For example, do not reuse the same USB drive on both online and offline machines.)
- You _could_ manually type the data onto the online machine, but doing so would be tedious and error-prone. - You _could_ manually type the data onto the online machine, but doing so would be tedious and error-prone.
## Steps ## Steps
{% set n = cycler(* range(1,99)) %} {% set n = cycler(* range(1,99)) %}
@@ -24,6 +25,10 @@ To use offline signing, you must have the following
On the **offline machine**, generate a pair of [cryptographic keys](cryptographic-keys.html) to be used with your account. Be sure to generate the keys with a securely random procedure, not from a simple passphrase or some other source that does not have enough entropy. For example, you can use the [wallet_propose method][] of `rippled`: On the **offline machine**, generate a pair of [cryptographic keys](cryptographic-keys.html) to be used with your account. Be sure to generate the keys with a securely random procedure, not from a simple passphrase or some other source that does not have enough entropy. For example, you can use the [wallet_propose method][] of `rippled`:
<!-- MULTICODE_BLOCK_START -->
_rippled Commandline_
```sh ```sh
$ ./rippled wallet_propose $ ./rippled wallet_propose
Loading: "/etc/opt/ripple/rippled.cfg" Loading: "/etc/opt/ripple/rippled.cfg"
@@ -43,6 +48,8 @@ Loading: "/etc/opt/ripple/rippled.cfg"
} }
``` ```
<!-- MULTICODE_BLOCK_END -->
Take note of the following values: Take note of the following values:
- **`account_id`**. This is the address associated with the key pair, which will become your **[account](accounts.html) address** in the XRP Ledger after you fund it with XRP (later in this process). It is safe to share your `account_id` publicly. - **`account_id`**. This is the address associated with the key pair, which will become your **[account](accounts.html) address** in the XRP Ledger after you fund it with XRP (later in this process). It is safe to share your `account_id` publicly.
@@ -69,6 +76,34 @@ Take note of the sequence number of the account, in the `Sequence` field of the
If the [DeletableAccounts amendment](known-amendments.html#deletableaccounts) :not_enabled: is enabled, the `Sequence` number of a newly-funded account matches the [ledger index][] when it was funded. Otherwise, a newly funded account's `Sequence` number is always 1. If the [DeletableAccounts amendment](known-amendments.html#deletableaccounts) :not_enabled: is enabled, the `Sequence` number of a newly-funded account matches the [ledger index][] when it was funded. Otherwise, a newly funded account's `Sequence` number is always 1.
<!-- MULTICODE_BLOCK_START -->
_rippled Commandline_
```sh
$ ./rippled account_info rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn
Loading: "/etc/opt/ripple/rippled.cfg"
2019-Dec-11 01:06:21.728637950 HTTPClient:NFO Connecting to 127.0.0.1:5005
{
"result" : {
"account_data" : {
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Balance" : "5000000000000",
"Flags" : 0,
"LedgerEntryType" : "AccountRoot",
"OwnerCount" : 0,
"PreviousTxnID" : "00C5B713B11DA775C6F932D38CE162C16FA88B7269BAFC6FDF4C6ADB74419670",
"PreviousTxnLgrSeq" : 3,
"Sequence" : 1,
"index" : "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8"
},
"ledger_current_index" : 4,
"status" : "success",
"validated" : false
}
}
```
### {{n.next()}}. Enter the sequence number on the offline machine. ### {{n.next()}}. Enter the sequence number on the offline machine.
@@ -77,6 +112,8 @@ Save the account's starting sequence number on the offline machine as its curren
You can prepare several transactions in advance this way, then transfer the signed transactions to the online machine all at once and submit them. As long as each transaction is validly formed and pays a sufficient [transaction cost](transaction-cost.html), the XRP Ledger network should eventually include those transactions in validated ledgers, keeping the account's sequence number in the shared XRP Ledger in sync with the "current" sequence number you are tracking on the offline machine. You can prepare several transactions in advance this way, then transfer the signed transactions to the online machine all at once and submit them. As long as each transaction is validly formed and pays a sufficient [transaction cost](transaction-cost.html), the XRP Ledger network should eventually include those transactions in validated ledgers, keeping the account's sequence number in the shared XRP Ledger in sync with the "current" sequence number you are tracking on the offline machine.
### {{n.next()}}. Sign initial setup transactions, if any. ### {{n.next()}}. Sign initial setup transactions, if any.
On the offline machine, prepare and sign transactions for configuring your account. The details depend on how you intend to you use your account. Some examples of things you might want to do include: On the offline machine, prepare and sign transactions for configuring your account. The details depend on how you intend to you use your account. Some examples of things you might want to do include:
@@ -84,33 +121,199 @@ On the offline machine, prepare and sign transactions for configuring your accou
- [Assign a regular key pair](assign-a-regular-key-pair.html) that you can rotate regularly. - [Assign a regular key pair](assign-a-regular-key-pair.html) that you can rotate regularly.
- [Require destination tags](require-destination-tags.html) so that users can't send you payments without tagging the reason they sent it or the customer it's intended for. - [Require destination tags](require-destination-tags.html) so that users can't send you payments without tagging the reason they sent it or the customer it's intended for.
- [Set Up Multi-Signing](set-up-multi-signing.html) for a higher bar of account security. - [Set Up Multi-Signing](set-up-multi-signing.html) for a higher bar of account security.
- [Enabling DepositAuth](depositauth.html) so you can only receive payments you've explicitly accepted or from parties you've pre-approved. - [Enable DepositAuth](depositauth.html) so you can only receive payments you've explicitly accepted or from parties you've pre-approved.
- [Enabling RequireAuth](become-an-xrp-ledger-gateway.html#enabling-requireauth) so that users can't open [trust lines](trust-lines-and-issuing.html) to you without your permission. If you don't plan to use the XRP Ledger's decentralized exchange or issued currency features, you may want to do this as a precaution. - [Enable RequireAuth](become-an-xrp-ledger-gateway.html#enabling-requireauth) so that users can't open [trust lines](trust-lines-and-issuing.html) to you without your permission. If you don't plan to use the XRP Ledger's decentralized exchange or issued currency features, you may want to do this as a precaution.
- Issued currency [Gateways](become-an-xrp-ledger-gateway.html) may have additional setup, such as: - Issued currency [Gateways](become-an-xrp-ledger-gateway.html) may have additional setup, such as:
- [Setting a TransferRate](become-an-xrp-ledger-gateway.html#transferrate) for users transferring your issued currencies. - [Set a TransferRate](become-an-xrp-ledger-gateway.html#transferrate) for users transferring your issued currencies.
- [Disallowing XRP payments](become-an-xrp-ledger-gateway.html#disallowxrp) if you plan to use this address for issued currencies only. - [Disallow XRP payments](become-an-xrp-ledger-gateway.html#disallowxrp) if you plan to use this address for issued currencies only.
At this stage, you are only signing the transactions, not submitting them. For each transaction, you must provide all fields, including fields that are normally auto-fillable such as the `Fee` ([transaction cost](transaction-cost.html)) and `Sequence` ([sequence number][]). If you prepare multiple transactions at the same time, you must use sequentially increasing `Sequence` numbers in the order you want the transactions to execute. At this stage, you are only signing the transactions, not submitting them. For each transaction, you must provide all fields, including fields that are normally auto-fillable such as the `Fee` ([transaction cost](transaction-cost.html)) and `Sequence` ([sequence number][]). If you prepare multiple transactions at the same time, you must use sequentially increasing `Sequence` numbers in the order you want the transactions to execute.
Example (enable RequireAuth):
<!-- MULTICODE_BLOCK_START -->
_rippled Commandline_
```sh
$ rippled sign sn3nxiW7v8KXzPzAqzyHXbSSKNuN9 '{"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", "Fee": "12", "Sequence": 1, "TransactionType": "AccountSet", "SetFlag": 2}' offline
Loading: "/etc/opt/ripple/rippled.cfg"
2019-Dec-11 00:18:31.865955978 HTTPClient:NFO Connecting to 127.0.0.1:5005
{
"result" : {
"deprecated" : "This command has been deprecated and will be removed in a future version of the server. Please migrate to a standalone signing tool.",
"status" : "success",
"tx_blob" : "1200032280000000240000000120210000000268400000000000000C7321039543A0D3004CDA0904A09FB3710251C652D69EA338589279BC849D47A7B019A174473045022100D5C92D7705036CD7EBB601C8DFCD90927FA591A62AF832C489E9C898EC8E2FA0022052F1819340EB73E9749B8930A6935727362B8E141D1B2E246B49F912223FFD4381144B4E9C06F24296074F7BC48F92A97916C6DC5EA9",
"tx_json" : {
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee" : "12",
"Flags" : 2147483648,
"Sequence" : 1,
"SetFlag" : 2,
"SigningPubKey" : "039543A0D3004CDA0904A09FB3710251C652D69EA338589279BC849D47A7B019A1",
"TransactionType" : "AccountSet",
"TxnSignature" : "3045022100D5C92D7705036CD7EBB601C8DFCD90927FA591A62AF832C489E9C898EC8E2FA0022052F1819340EB73E9749B8930A6935727362B8E141D1B2E246B49F912223FFD43",
"hash" : "F81C34E7F05423DC1C973CB5008CA41AE984DE142EAA3975A749FABF0D08FA63"
}
}
}
```
<!-- MULTICODE_BLOCK_END -->
### {{n.next()}}. Transfer setup transactions to online machine. ### {{n.next()}}. Copy transactions to online machine.
***TODO*** After you have signed the transactions, the next step is to get the signed transaction data to your online machine. See [Prerequisites](#prerequisites) for some examples of how to do this.
### {{n.next()}}. (online) Submit setup transactions.
***TODO***
### {{n.next()}}. (online) confirm success/validation of online transactions, note final sequence number
***TODO*** ### {{n.next()}}. Submit setup transactions.
The next step is to submit the transactions. Most transactions should have a final outcome in the next validated ledger after submission (about 4 seconds later), or possibly the ledger after that if they get queued (less than 10 seconds). For detailed steps to track the final outcome of a transaction, see [Reliable Transaction Submission](reliable-transaction-submission.html).
Example of simple transaction submission:
<!-- MULTICODE_BLOCK_START -->
_rippled Commandline_
```sh
$ rippled submit 1200032280000000240000000120210000000268400000000000000C7321039543A0D3004CDA0904A09FB3710251C652D69EA338589279BC849D47A7B019A174473045022100D5C92D7705036CD7EBB601C8DFCD90927FA591A62AF832C489E9C898EC8E2FA0022052F1819340EB73E9749B8930A6935727362B8E141D1B2E246B49F912223FFD4381144B4E9C06F24296074F7BC48F92A97916C6DC5EA9
Loading: "/etc/opt/ripple/rippled.cfg"
2019-Dec-11 01:14:25.988839227 HTTPClient:NFO Connecting to 127.0.0.1:5005
{
"result" : {
"deprecated" : "Signing support in the 'submit' command has been deprecated and will be removed in a future version of the server. Please migrate to a standalone signing tool.",
"engine_result" : "tesSUCCESS",
"engine_result_code" : 0,
"engine_result_message" : "The transaction was applied. Only final in a validated ledger.",
"status" : "success",
"tx_blob" : "1200032280000000240000000120210000000268400000000000000C7321039543A0D3004CDA0904A09FB3710251C652D69EA338589279BC849D47A7B019A174473045022100D5C92D7705036CD7EBB601C8DFCD90927FA591A62AF832C489E9C898EC8E2FA0022052F1819340EB73E9749B8930A6935727362B8E141D1B2E246B49F912223FFD4381144B4E9C06F24296074F7BC48F92A97916C6DC5EA9",
"tx_json" : {
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee" : "12",
"Flags" : 2147483648,
"Sequence" : 1,
"SetFlag" : 2,
"SigningPubKey" : "039543A0D3004CDA0904A09FB3710251C652D69EA338589279BC849D47A7B019A1",
"TransactionType" : "AccountSet",
"TxnSignature" : "3045022100D5C92D7705036CD7EBB601C8DFCD90927FA591A62AF832C489E9C898EC8E2FA0022052F1819340EB73E9749B8930A6935727362B8E141D1B2E246B49F912223FFD43",
"hash" : "F81C34E7F05423DC1C973CB5008CA41AE984DE142EAA3975A749FABF0D08FA63"
}
}
}
```
<!-- MULTICODE_BLOCK_END -->
**Tip:** If you are submitting more than 10 transactions at a time, you may have more success if you submit them in groups of 10 or less at a time, because the [transaction queue](transaction-queue.html) is limited to 10 transactions from the same sender at a time. After each group of 10 transactions, wait for all the transactions to leave the queue before submitting the next group.
Retry submitting any transactions that failed with a [non-final outcome](finality-of-results.html). There is no chance of the same transaction being processed more than once.
### {{n.next()}}. Confirm the final status of the transactions.
For each transaction you submitted, note the transaction's [final outcome](finality-of-results.html), for example using the [tx method][]. For example:
<!-- MULTICODE_BLOCK_START -->
_rippled Commandline_
```sh
$ ./rippled tx F81C34E7F05423DC1C973CB5008CA41AE984DE142EAA3975A749FABF0D08FA63
Loading: "/etc/opt/ripple/rippled.cfg"
2019-Dec-11 01:38:30.124771464 HTTPClient:NFO Connecting to 127.0.0.1:5005
{
"result" : {
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee" : "12",
"Flags" : 2147483648,
"Sequence" : 1,
"SetFlag" : 2,
"SigningPubKey" : "039543A0D3004CDA0904A09FB3710251C652D69EA338589279BC849D47A7B019A1",
"TransactionType" : "AccountSet",
"TxnSignature" : "3045022100D5C92D7705036CD7EBB601C8DFCD90927FA591A62AF832C489E9C898EC8E2FA0022052F1819340EB73E9749B8930A6935727362B8E141D1B2E246B49F912223FFD43",
"date" : 629343510,
"hash" : "F81C34E7F05423DC1C973CB5008CA41AE984DE142EAA3975A749FABF0D08FA63",
"inLedger" : 4,
"ledger_index" : 4,
"meta" : {
"AffectedNodes" : [
{
"ModifiedNode" : {
"FinalFields" : {
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Balance" : "4999999999988",
"Flags" : 262144,
"OwnerCount" : 0,
"Sequence" : 2
},
"LedgerEntryType" : "AccountRoot",
"LedgerIndex" : "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8",
"PreviousFields" : {
"Balance" : "5000000000000",
"Flags" : 0,
"Sequence" : 1
},
"PreviousTxnID" : "00C5B713B11DA775C6F932D38CE162C16FA88B7269BAFC6FDF4C6ADB74419670",
"PreviousTxnLgrSeq" : 3
}
}
],
"TransactionIndex" : 0,
"TransactionResult" : "tesSUCCESS"
},
"status" : "success",
"validated" : true
}
}
```
<!-- MULTICODE_BLOCK_END -->
You may also find it useful to check the [account_info][account_info method] of the sending account after all transactions have processed. Note the account's current sequence number (`Sequence` field) and, optionally, XRP balance.
For any transactions that failed, you should decide what to do:
- If the transaction failed with a `tefMAX_LEDGER` code, you may need to specify a higher [transaction cost](transaction-cost.html) to get the transaction processed. (This likely indicates that the XRP Ledger network is under load.) You may decide to replace the transaction with a new version that pays a higher cost and has a higher `LastLedgerSequence` parameter (if any).
- If the transaction failed with any [`tem`-class code](tem-codes.html), you probably made a typo or another error in constructing the transaction. Double-check the transaction so that you can replace it with a validly-formed one.
- If the transaction failed with a [`tec`-class code](tec-codes.html), you should address it on a case-by-case basis depending on the exact reason it failed.
For any transactions you decide to adjust or replace, note the details for when you return to the offline machine.
### {{n.next()}}. (offline) confirm that offline sequence number tracking matches up, adjust if necessary
***TODO*** ### {{n.next()}}. Reconcile offline machine status.
Return to the offline machine and input any changes to its internal tracking, such as:
- Updating the account's current `Sequence` number, if necessary. If all transactions were included in validated ledgers (successfully or with `tec` codes), then the offline machine's tracking should already be accurate. Otherwise, you may need to change the offline machine's stored sequence number to match the value you noted in the previous step.
- _(Optional)_ Updating your actual amount of XRP available, if you are tracking it in the offline machine.
Then adjust and sign any replacement transactions for transactions that failed in the previous step. Repeat the previous steps for constructing transactions on the offline machine, transferring them, and submitting them from the online machine.
## See Also
- **Concepts:**
- [Accounts](accounts.html)
- [Cryptographic Keys](cryptographic-keys.html)
- **Tutorials:**
- [Set Up Secure Signing](set-up-secure-signing.html)
- [Assign a Regular Key Pair](assign-a-regular-key-pair.html)
- [Set Up Multi-Signing](set-up-multi-signing.html)
- **References:**
- [Basic Data Types: Account Sequence](basic-data-types.html#account-sequence)
- [account_info method][]
- [sign method][]
- [submit method][]
- [tx method][]
- [AccountSet transaction][]
<!--{# common link defs #}--> <!--{# common link defs #}-->