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 read other network activity. All transactions, balances, and data in the XRP Ledger are 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:

Insecure Configurations

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 (and anything else your XRP Ledger address has). Examples of such configurations include ones where you use the sign method of someone else's rippled server over the internet, or you send 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.

Run rippled Locally

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.

    Be sure that your local machine meets the minimum system requirements for rippled.

  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 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 for signatures is less secure than using the Websocket or JSON-RPC APIs through non-commandline clients. 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 plain text.

  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

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.

To use this configuration, set the rippled server to accept wss and https connections within your LAN. You can use a self-signed certificate if you use certificate pinning , or you can use a certificate signed by an in-house or well-known Certificate Authority. Some certificate authorities, such as Let's Encrypt issue certificates automatically for free.

As always, follow industry-standard practices for securing your machines, such as using a firewall, anti-virus, appropriate user permissions, and so on.

Use a Client Library with Local Signing

This configuration uses a client library with built-in signing, in the programming language you use. For a list of libraries that can perform local signing, see Client Libraries.

Security Best Practices for Signing Libraries

To optimize the security of your signing library:

  • Make sure the signing library you use has properly and securely implemented its signing algorithm(s). For example, if the library uses the default ECDSA algorithm, it should also use deterministic nonces as described in RFC-6979 .

    All of the published libraries listed above follow industry best practices.

  • Keep your client library updated to the latest stable version.

  • For enhanced security, you can load your secret keys from a management tool such as Vault .

Local Signing Example

Here are examples of how to sign transaction instructions locally using the following languages and libraries:

// Sample code demonstrating secure offline signing using xrpl.js library.
const xrpl = require('xrpl')

// Load seed value from an environment variable:
const my_wallet = xrpl.Wallet.fromSeed(process.env['MY_SEED'])

// For offline signing, you need to know your address's next Sequence number.
// Alternatively, you could use a Ticket in place of the Sequence number.
// This is useful when you need multiple signatures and may want to process transactions out-of-order.
// For details, see: https://xrpl.org/tickets.html
let my_seq = 21404872

// Provide *all* required fields before signing a transaction
const txJSON = {
  "Account": my_wallet.address,
  "TransactionType":"Payment",
  "Destination":"rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
  "Amount":"13000000",
  "Flags":2147483648,
  "LastLedgerSequence":7835923, // Optional, but recommended.
  "Fee":"13",
  "Sequence": my_seq
}

const signed = my_wallet.sign(txJSON)

console.log("tx_blob is:", signed.tx_blob)
console.log("tx hash is:", signed.hash)

# Define signer address
import os  
my_secret = os.getenv("MYSECRET")
from xrpl.wallet import Wallet
wallet = Wallet(seed=my_secret, sequence=16237283)
print(wallet.classic_address) # "raaFKKmgf6CRZttTVABeTcsqzRQ51bNR6Q"

from xrpl.models.transactions import Payment
from xrpl.utils import xrp_to_drops
my_payment = Payment(
    account=wallet.classic_address,
    amount=xrp_to_drops(22),
    fee="10",
    destination="rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe",
    sequence=wallet.sequence, # this needs to be incremented upon every successful transaction
)
print("Payment object:", my_payment)

# Sign transaction -------------------------------------------------------------
import xrpl.transaction 
signed = xrpl.transaction.safe_sign_transaction(my_payment, wallet)
print("Signed transaction blob:", signed)

////////////////////////////////////////////////////////////////////////////
// Sign using a SingleKeySignatureService:
// This implementation of SignatureService simply holds a PrivateKey in
// memory and signs Transactions using that PrivateKey. This may be
// suitable for some applications, but is likely not secure enough for
// server side applications, as keys must be stored and kept in memory.
////////////////////////////////////////////////////////////////////////////

// Create a random wallet
WalletFactory walletFactory = DefaultWalletFactory.getInstance();
Wallet wallet = walletFactory.randomWallet(true).wallet();

// Construct a SingleKeySignatureService from the Wallet private key
PrivateKey privateKey = PrivateKey.fromBase16EncodedPrivateKey(
  wallet.privateKey().get()
);
SingleKeySignatureService signatureService =
  new SingleKeySignatureService(privateKey);

// Construct and sign the Payment
Payment payment = Payment.builder()
  .account(wallet.classicAddress())
  .destination(Address.of("rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe"))
  .amount(XrpCurrencyAmount.ofDrops(1000))
  .fee(XrpCurrencyAmount.ofDrops(10))
  .sequence(UnsignedInteger.valueOf(16126889))
  .signingPublicKey(signatureService.getPublicKey(KeyMetadata.EMPTY))
  .build();
SignedTransaction<Payment> signedPayment = signatureService.sign(
  KeyMetadata.EMPTY,
  payment
);
System.out.println("Signed Payment: " + signedPayment.signedTransaction());


////////////////////////////////////////////////////////////////////////////
// Sign using a DerivedKeysSignatureService:
// This implementation of SignatureService deterministically derives
// Private Keys from a secret value (likely a server secret) and a wallet
// identifier. That PrivateKey can then be used to sign transactions.
// The wallet identifier can be anything, but would likely be an existing ID
// tracked by a server side system.
//
// Though this implementation is more secure than SingleKeySignatureService
// and better suited for server-side applications, keys are still held
// in memory. For the best security, we suggest using a HSM-based
// implementation.
////////////////////////////////////////////////////////////////////////////

// Construct a DerivedKeysSignatureService with a server secret
// (in this case "shh")
DerivedKeysSignatureService signatureService =
  new DerivedKeysSignatureService("shh"::getBytes, VersionType.ED25519);

// Choose a walletId. This can be anything as long as it is unique to your system.
String walletId = "sample-wallet";
KeyMetadata keyMetadata = KeyMetadata.builder()
  .platformIdentifier("jks")
  .keyringIdentifier("n/a")
  .keyIdentifier(walletId)
  .keyVersion("1")
  .keyPassword("password")
  .build();

// Get the public key and classic address for the given walletId
PublicKey publicKey = signatureService.getPublicKey(keyMetadata);
Address classicAddress = DefaultKeyPairService.getInstance()
  .deriveAddress(publicKey.value());

// Construct and sign the Payment
Payment payment = Payment.builder()
  .account(classicAddress)
  .destination(Address.of("rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe"))
  .amount(XrpCurrencyAmount.ofDrops(1000))
  .fee(XrpCurrencyAmount.ofDrops(10))
  .sequence(UnsignedInteger.valueOf(16126889))
  .signingPublicKey(publicKey.base16Encoded())
  .build();

SignedTransaction<Payment> signedPayment = signatureService
  .sign(keyMetadata, payment);
System.out.println("Signed Payment: " + signedPayment.signedTransaction());

Use a Dedicated Signing Device

Some companies sell dedicated signing devices, such as the Ledger Nano S , which are capable of signing XRP Ledger transactions using a secret key that never leaves the device. Some devices may not support all types of transactions.

Setting up this configuration depends on the specific device. You may need to run a "manager" application on your machine to interact with the signing device. See the manufacturer's instructions for how to set up and use such a device.

Use a Secure VPN with a Remote rippled Server

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, 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.

See Also