mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-20 19:55:54 +00:00
Set Up Secure Signing (1st draft)
This commit is contained in:
mDuo13
134
content/tutorials/get-started/set-up-secure-signing.md
Normal file
134
content/tutorials/get-started/set-up-secure-signing.md
Normal file
@@ -0,0 +1,134 @@
|
||||
# Set Up Secure Signing
|
||||
|
||||
To submit transactions to the XRP Ledger, you need a way to digitally sign them without compromising the security of your secret keys. (If others gain access to your secret keys, they have as much control over your accounts as you do, and can steal or destroy all your money.) This page summarizes how to set up such an environment so you can sign transactions securely.
|
||||
|
||||
**Tip:** If you are not submitting transactions to the network, you can safely use a trustworthy public server, such as the ones run by Ripple, to monitor for incoming transactions or just to read other network activity. All transactions, balances, and data in the XRP Ledger itself is public.
|
||||
|
||||
There are several configurations with varying levels of security that may be acceptable for your situation. Choose one of the following that best fits your needs:
|
||||
|
||||
- [Run `rippled` locally](#run-rippled-locally), or [in the same LAN](#run-rippled-on-the-same-lan).
|
||||
- [Use a client library](#use-a-client-library-with-local-signing) that can do local signing.
|
||||
- [Use a secure VPN to connect to a remote `rippled` machine](#use-a-secure-vpn-with-a-remote-rippled-server) you trust.
|
||||
|
||||
<!-- Source for all diagrams in this article: https://docs.google.com/presentation/d/1BfGyWgC0njoPiKUZz3gXHMVSUINE3Q-_lHqY_D0TGwg/ -->
|
||||
|
||||
## Insecure Configurations
|
||||
|
||||
[](img/insecure-signing-options.png)
|
||||
|
||||
Any configuration in which outside sources may gain access to your secret key is dangerous, and is likely to result in a malicious user stealing all your XRP. Examples of such configurations include ones where you use the [sign method][] of someone else's `rippled` server over the internet, or you transmit your secret key in plain text over the internet to your own server.
|
||||
|
||||
You should maintain the secrecy of your secret keys at all times, which includes things like not emailing them to yourself, not typing them visibly in public, and saving them encrypted—never in plain text—when you are not using them. The balance between security and convenience depends in part on the value of your addresses' holdings, so you may want to use multiple addresses with different security configurations for different purposes.
|
||||
|
||||
<!-- Note: I'd link "issuing and operational addresses" for an explanation of hot/cold wallet security, but it's particularly gateway/issued-currency centric, which is not appropriate for this context. -->
|
||||
|
||||
|
||||
## Run rippled Locally
|
||||
|
||||
[](img/secure-signing-local-rippled.png)
|
||||
|
||||
In this configuration, you run `rippled` on the machine that generates the transactions. Since the secret key never leaves your machine, no one without access to your machine can get access to the secret key. You should, of course, follow industry-standard practices for securing your machine. To use this configuration:
|
||||
|
||||
1. [Install `rippled`](install-rippled.html).
|
||||
|
||||
Be sure that your local machine meets the minimum [system requirements for `rippled`](system-requirements.html).
|
||||
|
||||
2. When you need to sign transactions, connect to your server on `localhost` or `127.0.0.1`. Use the [sign method][] (for single signatures) or [sign_for method][] (for multi-signatures).
|
||||
|
||||
The [example config file](https://github.com/ripple/rippled/blob/8429dd67e60ba360da591bfa905b58a35638fda1/cfg/rippled-example.cfg#L1050-L1073) listens for connections on the local loopback network (127.0.0.1), with JSON-RPC (HTTP) on port 5005 and WebSocket (WS) on port 6006, and treats all connected clients as admin.
|
||||
|
||||
**Caution:** Using the [commandline API](request-formatting.html#commandline-format) for signatures is less secure than [using the Websocket or JSON-RPC APIs](get-started-with-the-rippled-api.html) through non-commandline client. When using the commandline syntax, your secret key may be visible to other users in the system's process listing, and your shell history may save the key in plaintext.
|
||||
|
||||
3. Maintain the server to keep it running, updated, and in sync with the network while you're using it.
|
||||
|
||||
**Note:** You _can_ turn off your `rippled` server when you're not sending transactions, but it can take up to 15 minutes to sync with the network when you start it up again.
|
||||
|
||||
|
||||
## Run rippled on the same LAN
|
||||
|
||||
[](img/secure-signing-lan-rippled.png)
|
||||
|
||||
In this configuration, you run a `rippled` server on a dedicated machine in the same private local area network (LAN) as the machine that generates the transactions to be signed. This configuration lets you assemble transaction instructions on one or more machines with very modest system specs, while using a single dedicated machine for running `rippled`. This may appeal to you if you run your own datacenter or server room.
|
||||
|
||||
As always, follow industry-standard practices for securing your machines, such as using a firewall, anti-virus, appropriate user permissions, and so on.
|
||||
|
||||
**Warning:** This configuration comes with the additional downside that anyone on the LAN can sniff traffic between your machines, potentially gaining access to your secret keys. Do not use this configuration on a network that may have strangers on it. For example, on the LAN at a colocation facility or cloud hosting, other customers may be able to get access to the traffic between your machines. If you employ several developers sending test transactions, you could run one `rippled` machine for your whole office, while the developers use cheaper hardware, but any user on your office network could potentially use a packet sniffer to get access to developers' secret keys.
|
||||
|
||||
To use this configuration:
|
||||
|
||||
1. [Install `rippled`](install-rippled.html) on the chosen machine.
|
||||
|
||||
Be sure that this machine meets the minimum [system requirements for `rippled`](system-requirements.html).
|
||||
|
||||
2. Configure the `rippled` machine to have a static IP address in the local private LAN, or use a private DNS server to give the server a consistent name.
|
||||
|
||||
With IPv4, private LAN addresses commonly start with `10.`, `192.168.`, or `172.(16 to 31).`. With IPv6, private LAN addresses typically start with `fc` or `fd`.
|
||||
|
||||
3. Configure the `rippled` machine to accept connections from your local private network.
|
||||
|
||||
In the `rippled`'s config file, modify the `[port_rpc_admin_local]` and `[port_ws_admin_local]` stanzas to use your server's private-LAN address:
|
||||
|
||||
[port_rpc_admin_local]
|
||||
port = 5005
|
||||
ip = 10.1.0.0 # Changed from 127.0.0.1
|
||||
admin = 10.1.1.2 # Only the client with this IP is treated as admin
|
||||
protocol = http
|
||||
|
||||
[port_ws_admin_local]
|
||||
port = 6006
|
||||
ip = 10.1.0.0 # Changed from 127.0.0.1
|
||||
admin = 10.1.1.2 # Only the client with this IP is treated as admin
|
||||
protocol = ws
|
||||
|
||||
4. If your `rippled` machine runs a software firewall, configure the firewall to accept connections on your local private network at the JSON-RPC and Websocket ports you configured in the previous step. (Ports `5005` and `6006` in the previous example.)
|
||||
|
||||
The exact configuration depends on your firewall software.
|
||||
|
||||
5. On the machine(s) that will submit transactions, connect to your server using your `rippled` server's private IP address and the configured ports. Use the [sign method][] (for single signatures) or [sign_for method][] (for multi-signatures).
|
||||
|
||||
The example configuration from the previous steps uses port `5005` for JSON-RPC connections and port `6006` for Websocket connections.
|
||||
|
||||
6. Keep the `rippled` server running, updated, and in sync with the network while you're using it.
|
||||
|
||||
**Note:** You _can_ turn off your `rippled` server when you're not sending transactions, but it can take up to 15 minutes to sync with the network when you start it up again.
|
||||
|
||||
|
||||
## Use a Client Library with Local Signing
|
||||
|
||||
[](img/secure-signing-client-library.png)
|
||||
|
||||
This configuration uses a client library in the programming language you are using to sign transactions locally. You need a client library for the programming language you use. Ripple publishes the following client libraries that can sign transactions for the XRP Ledger locally:
|
||||
|
||||
- **RippleAPI (ripple-lib) for JavaScript**
|
||||
- [Setup](get-started-with-rippleapi-for-javascript.html)
|
||||
- [API Reference](rippleapi-reference.html)
|
||||
- **ripple-libpp for C++**
|
||||
- [Source and Documentation](https://github.com/ripple/ripple-libpp/)
|
||||
|
||||
If you use a client library not published by Ripple, make sure it uses proper, secure implementations of the signing algorithm(s) it implements. (For example, if it uses the default ECDSA algorithm, it should also use deterministic nonces as described in [RFC6979](https://tools.ietf.org/html/rfc6979).) All of Ripple's published libraries listed above follow industry best practices.
|
||||
|
||||
For best security, be sure to keep your client library updated to the latest stable version.
|
||||
|
||||
### Example Local Signing with RippleAPI
|
||||
|
||||
The following code sample shows how to sign transaction instructions locally with RippleAPI for JavaScript:
|
||||
|
||||
```js
|
||||
{% include '_code-samples/secure-signing/js/signPayment.js' %}
|
||||
```
|
||||
|
||||
## Use a Secure VPN with a Remote rippled Server
|
||||
|
||||
[](img/secure-signing-over-vpn.png)
|
||||
|
||||
This configuration uses a `rippled` server hosted remotely, such as in a colocation facility or a distant datacenter, but connects to it securely using an encrypted VPN.
|
||||
|
||||
To use this configuration, follow the steps for [running `rippled` on a private LAN](#run-rippled-on-the-same-lan), but use a VPN to connect to the LAN of the remote `rippled` server. Instructions for setting up the VPN are specific to your environment and are not described in this guide.
|
||||
|
||||
|
||||
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
Reference in New Issue
Block a user