From f7905ab4b1d961000453f4883ed0ea7dfba55568 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Thu, 30 Aug 2018 16:21:18 -0700 Subject: [PATCH] Update signing command documentation Per https://github.com/ripple/rippled/pull/2657, the signing commands should not be used as public methods and this usage is disabled in rippled v1.1.0 and later. --- content/_snippets/public-signing-note.md | 1 + .../transaction-methods/sign.md | 3 ++ .../transaction-methods/sign_for.md | 18 ++++++---- .../transaction-methods/submit.md | 2 ++ .../enable-public-signing.md | 35 +++++++++++++++++++ dactyl-config.yml | 8 +++++ 6 files changed, 61 insertions(+), 6 deletions(-) create mode 100644 content/_snippets/public-signing-note.md create mode 100644 content/tutorials/manage-the-rippled-server/enable-public-signing.md diff --git a/content/_snippets/public-signing-note.md b/content/_snippets/public-signing-note.md new file mode 100644 index 0000000000..833f568aa4 --- /dev/null +++ b/content/_snippets/public-signing-note.md @@ -0,0 +1 @@ +_By default, this method is [admin-only](admin-rippled-methods.html). It can be used as a public method if the server has [enabled public signing](enable-public-signing.html)._ diff --git a/content/references/rippled-api/public-rippled-methods/transaction-methods/sign.md b/content/references/rippled-api/public-rippled-methods/transaction-methods/sign.md index 49bd85096a..d4a12e61ce 100644 --- a/content/references/rippled-api/public-rippled-methods/transaction-methods/sign.md +++ b/content/references/rippled-api/public-rippled-methods/transaction-methods/sign.md @@ -3,6 +3,9 @@ The `sign` method takes a [transaction in JSON format](transaction-formats.html) and a secret key, and returns a signed binary representation of the transaction. The result is always different, even when you provide the same transaction JSON and secret key. To contribute one signature to a multi-signed transaction, use the [sign_for method][] instead. +{% include '_snippets/public-signing-note.md' %} + + **Caution:** Unless you run the `rippled` server yourself, you should do [local signing with RippleAPI](rippleapi-reference.html#sign) instead of using this command. An untrustworthy server could change the transaction before signing it, or use your secret key to sign additional arbitrary transactions as if they came from you. ## Request Format diff --git a/content/references/rippled-api/public-rippled-methods/transaction-methods/sign_for.md b/content/references/rippled-api/public-rippled-methods/transaction-methods/sign_for.md index a07a5398b5..34279ed58c 100644 --- a/content/references/rippled-api/public-rippled-methods/transaction-methods/sign_for.md +++ b/content/references/rippled-api/public-rippled-methods/transaction-methods/sign_for.md @@ -3,6 +3,9 @@ The `sign_for` command provides one signature for a [multi-signed transaction](multi-signing.html). +{% include '_snippets/public-signing-note.md' %} + + This command requires the [MultiSign amendment](known-amendments.html#multisign) to be enabled. [New in: rippled 0.31.0][] ## Request Format @@ -89,13 +92,16 @@ The request includes the following parameters: |:-------------|:---------------------|:---------------------------------------| | `account` | String - [Address][] | The address which is providing the signature. | | `tx_json` | Object | The [Transaction](transaction-formats.html) to sign. Unlike using the [sign method][], all fields of the transaction must be provided, including `Fee` and `Sequence`. The transaction must include the field `SigningPubKey` with an empty string as the value. The object may optionally contain a `Signers` array with previously-collected signatures. | -| `secret` | String | _(Optional)_ The secret key to sign with. (Cannot be used with `key_type`.) | -| `passphrase` | String | _(Optional)_ A passphrase to use as the secret key to sign with. | -| `seed` | String | _(Optional)_ A [base58][]-encoded secret key to sign with. | -| `seed_hex` | String | _(Optional)_ A hexadecimal secret key to sign with. | -| `key_type` | String | _(Optional)_ The type of key to use for signing. This can be `secp256k1` or `ed25519`. (Ed25519 support is experimental.) | +| `secret` | String | _(Optional)_ Secret key of the account supplying the transaction, used to sign it. Do not send your secret to untrusted servers or through unsecured network connections. Cannot be used with `key_type`, `seed`, `seed_hex`, or `passphrase`. | +| `seed` | String | _(Optional)_ Secret key of the account supplying the transaction, used to sign it. Must be in [base58][] format. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed_hex`, or `passphrase`. | +| `seed_hex` | String | _(Optional)_ Secret key of the account supplying the transaction, used to sign it. Must be in hexadecimal format. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed`, or `passphrase`. | +| `passphrase` | String | _(Optional)_ Secret key of the account supplying the transaction, used to sign it, as a string passphrase. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed`, or `seed_hex`. | +| `key_type` | String | _(Optional)_ Type of cryptographic key provided in this request. Valid types are `secp256k1` or `ed25519`. Defaults to `secp256k1`. Cannot be used with `secret`. **Caution:** Ed25519 support is experimental. | -You must provide exactly 1 field with the secret key. You can use any of the following fields: `secret`, `passphrase`, `seed`, or `seed_hex`. +You must provide **exactly 1 field** with the secret key, which can be either of the following: + +* Provide a `secret` value and omit the `key_type` field. This value can be formatted as [base58][] seed, RFC-1751, hexadecimal, or as a string passphrase. (secp256k1 keys only) +* Provide a `key_type` value and exactly one of `seed`, `seed_hex`, or `passphrase`. Omit the `secret` field. (Not supported by the commandline syntax.) ## Response Format diff --git a/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md b/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md index 84e5aa3dc6..c676ca3f83 100644 --- a/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md +++ b/content/references/rippled-api/public-rippled-methods/transaction-methods/submit.md @@ -62,6 +62,8 @@ submit 1200002280000000240000000361D4838D7EA4C6800000000000000000000000000055534 This mode signs a transaction and immediately submits it. This mode is intended to be used for testing. You cannot use this mode for [multi-signed transactions](multi-signing.html). +_By default, sign-and-submit mode is [admin-only](admin-rippled-methods.html)._ It can be used as a public method if the server has [enabled public signing](enable-public-signing.html). + You can provide the secret key used to sign the transaction in the following ways: * Provide a `secret` value and omit the `key_type` field. This value can be formatted as [base58][] seed, RFC-1751, hexadecimal, or as a string passphrase. (secp256k1 keys only) diff --git a/content/tutorials/manage-the-rippled-server/enable-public-signing.md b/content/tutorials/manage-the-rippled-server/enable-public-signing.md new file mode 100644 index 0000000000..c2adca3b55 --- /dev/null +++ b/content/tutorials/manage-the-rippled-server/enable-public-signing.md @@ -0,0 +1,35 @@ +# Enable Public Signing + +[New in: rippled 1.1.0][] By default, the signing methods for `rippled` are limited to administrative connections. If you want to allow signing methods to be used as public API methods (like with versions of `rippled` before v1.1.0), you can enable it with a configuration change. + +This enables the following methods to be used on "public" [JSON-RPC and WebSocket connections](get-started-with-the-rippled-api.html), if your server accepts them: + +- [sign][sign method] +- [sign_for][sign_for method] +- [submit][submit method] (in "sign-and-submit" mode) + +You **do not** need to enable public signing to use these methods from an admin connection. + +**Caution:** Ripple does not recommend enabling public signing. Like the [wallet_propose method][], the signing commands do not perform any actions that would require administrative-level permissions, but restricting them to admin connections protects users from irresponsibly sending or receiving secret keys over unsecured communications, or to servers they do not control. + +To enable public signing, perform the following steps: + +1. Edit your `rippled`'s config file. + + vim /etc/opt/ripple/rippled.cfg + + The [recommended installation](install-rippled.html) uses the config file `/etc/opt/ripple/rippled.cfg` by default. Other places you can put a config file include `$HOME/.config/ripple/rippled.cfg` (where `$HOME` is the home directory of the user running `rippled`) or + +2. Add the following stanza to your config file, and save the changes: + + [signing_support] + true + +3. Restart your `rippled` server: + + systemctl restart rippled + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/dactyl-config.yml b/dactyl-config.yml index 395a5b6d04..a1f5168cf3 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -887,6 +887,14 @@ pages: targets: - local + - md: tutorials/manage-the-rippled-server/enable-public-signing.md + html: enable-public-signing.html + funnel: Docs + doc_type: Tutorials + category: Manage the rippled Server + targets: + - local + - md: tutorials/manage-the-rippled-server/run-rippled-as-a-validator.md html: run-rippled-as-a-validator.html funnel: Docs