From f2e890e3e0385661d85abd8a941ce9855cd1e7ef Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa Date: Tue, 30 Jan 2018 17:43:17 -0800 Subject: [PATCH] added links, some tweaks --- content/reference-transaction-format.md | 10 +++++----- content/transactions/setregularkey.md | 18 +++++++++--------- content/tutorial-regular-keys.md | 11 +++++++++-- 3 files changed, 23 insertions(+), 16 deletions(-) diff --git a/content/reference-transaction-format.md b/content/reference-transaction-format.md index 07846b3eac..58f755b2bf 100644 --- a/content/reference-transaction-format.md +++ b/content/reference-transaction-format.md @@ -34,7 +34,7 @@ In the XRP Ledger, a digital signature proves that a transaction is authorized t ### Master Keys -When you create an account using the [`wallet_propose`](reference-rippled.html#wallet-propose) method, the `master_seed` (private key) and `public_key` returned in the response are the master keys for the account. These keys are an intrinsic part of the account's identity as the `account_id` (account address), also returned in the `wallet_propose` response, is derived from the `public_key` value. +When you create an account using the [`wallet_propose`](reference-rippled.html#wallet-propose) method, the `master_seed` (private key) and `public_key` returned in the response are the master keys for the account. These keys are an intrinsic part of the account's identity as the `account_id` (account address), also returned in the `wallet_propose` response, and the `public_key` value are mathematically related. Here's a sample `wallet_propose` response, including the `master_seed` (private key), `public_key`, and `account_id` (account address) values: @@ -61,20 +61,20 @@ Master keys have more powerful signing authority than regular keys. In addition * Use the master private key to [disable the master public key](#accountset-flags). * Permanently give up the ability to [freeze counterparties](concept-freeze.html#no-freeze). -**Important:** Master keys cannot be changed. This means that if your master private key is [compromised](concept-issuing-and-operational-addresses.html), you cannot change it to stop the compromise. +**Important:** Master keys can be disabled, but cannot be changed. This means that if your master private key is [compromised](concept-issuing-and-operational-addresses.html), you cannot change it to stop the compromise. -This is a compelling reason to keep your master keys offline and set up regular keys to sign transactions from your master account instead. +This is a compelling reason to keep your master keys offline whenever possible and set up regular keys to sign transactions from your master account instead. ### Regular Keys -When you create an account using the [`wallet_propose`](reference-rippled.html#wallet-propose) method, the `master_seed` (private key) and `public_key` returned in the response are the master keys for the account. For the purposes of this discussion, let's call this account the master account. Ripple recommends that you keep the master account's master keys offline and assign regular keys to the master account to sign your transactions instead. +When you create an account using the [`wallet_propose`](reference-rippled.html#wallet-propose) method, the `master_seed` (private key) and `public_key` returned in the response are the master keys for the account. For the purposes of this discussion, let's call this account the master account. Ripple recommends that you keep the master account's master keys offline whenever possible and assign regular keys to the master account to sign your transactions instead. You generate regular keys using the same `wallet_propose` method used to generate a master account and master keys. However, you use this second account and key pair specifically with the `SetRegularKey` method to assign **regular keys** to the master account. Once you've assigned the regular keys, the master account has two key pairs associated with it: -* Master keys that are intrinsically related to its address and which you keep offline. +* Master keys that are intrinsically related to its address and which you keep offline whenever possible. * Regular keys that you've assigned to sign transactions. You can assign one regular key pair to a master account and use it to sign all transactions, except for the ones reserved for the [master keys](#master-keys). diff --git a/content/transactions/setregularkey.md b/content/transactions/setregularkey.md index 53b091a847..1ac810677f 100644 --- a/content/transactions/setregularkey.md +++ b/content/transactions/setregularkey.md @@ -2,7 +2,15 @@ [[Source]
](https://github.com/ripple/rippled/blob/4239880acb5e559446d2067f00dabb31cf102a23/src/ripple/app/transactors/SetRegularKey.cpp "Source") -A SetRegularKey transaction changes the regular key associated with an address. +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 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 a tutorial on assigning regular keys 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). ``` { @@ -17,11 +25,3 @@ A SetRegularKey transaction changes the regular key associated with an address. | 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. | - -In addition to the master key, which is mathematically-related to an address, you can associate **at most 1 additional key pair** with an address using this type of transaction. The additional key pair is called a _regular key_. If your address has a regular key pair defined, you can use the secret key of the regular key pair to [authorize transactions](#authorizing-transactions). - -A regular key pair is generated in the same way as any other Ripple keys (for example, with [wallet_propose](reference-rippled.html#wallet-propose)), but it can be changed. A master key pair is an intrinsic part of an address's identity (the address is derived from the master public key). You can [disable](#accountset-flags) a master key but you cannot change it. - -You can protect your master secret by using a regular key instead of the master key to sign transactions whenever possible. If your regular key is compromised, but the master key is not, you can use a SetRegularKey transaction to regain control of your address. In some cases, you can even send a [key reset transaction](concept-transaction-cost.html#key-reset-transaction) without paying the [transaction cost](#transaction-cost). - -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). diff --git a/content/tutorial-regular-keys.md b/content/tutorial-regular-keys.md index bdd0f834f0..3e0d830e40 100644 --- a/content/tutorial-regular-keys.md +++ b/content/tutorial-regular-keys.md @@ -1,6 +1,6 @@ # Working with Regular Keys -Assign regular keys to your account to enable you to sign most transactions with regular keys, while keeping your master keys offline. A master key [compromise](concept-issuing-and-operational-addresses.html) can be difficult to recover from, while removing or changing compromised regular keys is a simpler task. +Assign regular keys to your account to enable you to sign most transactions with regular keys, while keeping your master keys offline whenever possible. A master key [compromise](concept-issuing-and-operational-addresses.html) can be difficult to recover from, while removing or changing compromised regular keys is a simpler task. For an overview of master and regular keys, see [Understanding Master and Regular Keys](reference-transaction-format.html#understanding-master-and-regular-keys). @@ -155,7 +155,6 @@ In the request, send the master account's `account_ID` as the `account` value, t Here's an example `SetRegularKey` request and response. -***TODO: We tell the user to keep the master private key offline - but we are sending it in few transactions in this tutorial. I'm being too literal - but I think we should acknowledge that what we really mean is to strictly limit online use of the master private key. What do you think?*** #### WebSocket Request: @@ -336,3 +335,11 @@ Here's an example response for a `Payment` transaction signed using an invalid r "type": "response" } ``` + +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 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.***