mirror of
https://github.com/XRPLF/rippled.git
synced 2025-11-19 18:45:52 +00:00
1b4e0f5f48
* Do not forward manifests to peers that already know that manifest * Do not forward historical manifests to peers * Save/Load ValidatorManifests from a database * Python test for setting ephmeral keys * Cleanup manifest interface
111 lines
3.5 KiB
Markdown
111 lines
3.5 KiB
Markdown
# Manifest Tool Guide
|
|
|
|
This guide explains how to setup a validator so the key pairs used to sign and
|
|
verify validations may safely change. This procedure does not require manual
|
|
reconfiguration of servers that trust this validator.
|
|
|
|
Validators use two types of key pairs: *master keys* and *ephemeral
|
|
keys*. Ephemeral keys are used to sign and verify validations. Master keys are
|
|
used to sign and verify manifests that change ephemeral keys. The master secret
|
|
key should be tightly controlled. The ephemeral secret key needs to be present
|
|
in the config file.
|
|
|
|
## Validator Keys
|
|
|
|
When first setting up a validator, use the `manifest` script to generate a
|
|
master key pair:
|
|
|
|
```
|
|
$ bin/manifest create
|
|
```
|
|
|
|
Sample output:
|
|
```
|
|
[validator_keys]
|
|
nHUSSzGw4A9zEmFtK2Q2NcWDH9xmGdXMHc1MsVej3QkLTgvDNeBr
|
|
|
|
[master_secret]
|
|
pnxayCakmZRQE2qhEVRbFjiWCunReSbN1z64vPL36qwyLgogyYc
|
|
```
|
|
|
|
The first value is the master public key. Add the public key to the config
|
|
for this validator. A one-word comment must be added after the key (for example
|
|
*ThisServersName*). Any other rippled trusting the validator needs to add the
|
|
master public key to its config. Only add keys received from trusted sources.
|
|
|
|
The second value is the corresponding master secret key. **DO NOT INSTALL THIS
|
|
IN THE CONFIG**. The master secret key will be used to sign manifests that
|
|
change validation keys. Put the master secret key in a secure but recoverable
|
|
location.
|
|
|
|
## Validation Keys
|
|
|
|
When first setting up a validator, or when changing the ephemeral keys, use the
|
|
`rippled` program to create a new ephemeral key pair:
|
|
|
|
```
|
|
$ rippled validation_create
|
|
```
|
|
|
|
Sample output:
|
|
|
|
```
|
|
Loading: "/Users/alice/.config/ripple/rippled.cfg"
|
|
Securely connecting to 127.0.0.1:5005
|
|
{
|
|
"result" : {
|
|
"status" : "success",
|
|
"validation_key" : "TOO EDNA SHUN FEUD STAB JOAN BIAS FLEA WISE BOHR LOSS WEEK",
|
|
"validation_public_key" : "n9JzKV3ZrcZ3DW5pwjakj4hpijJ9oMiyrPDGJc3mpsndL6Gf3zwd",
|
|
"validation_seed" : "sahzkAajS2dyhjXg2yovjdZhXmjsx"
|
|
}
|
|
}
|
|
```
|
|
|
|
Add the `validation_seed` value (the ephemeral secret key) to this validator's
|
|
config. It is recommended to add the ephemeral public key and the sequence
|
|
number as a comment as well (sequence numbers are be explained below):
|
|
|
|
```
|
|
[validation_seed]
|
|
sahzkAajS2dyhjXg2yovjdZhXmjsx
|
|
# validation_public_key: n9JzKV3ZrcZ3DW5pwjakj4hpijJ9oMiyrPDGJc3mpsndL6Gf3zwd
|
|
# sequence number: 1
|
|
```
|
|
|
|
A manifest is a signed message used to inform other servers of this validator's
|
|
ephemeral public key. A manifest contains a sequence number, the new ephemeral
|
|
public key, and it is signed with the master secret key. The sequence number
|
|
should be higher than the previous sequence number (if it is not, the manifest
|
|
will be ignored). Usually the previous sequence number will be incremented by
|
|
one. Use the `manifest` script to create a manifest. It has the form:
|
|
|
|
```
|
|
$ bin/manifest sign sequence_number validation_public_key master_secret
|
|
```
|
|
|
|
For example:
|
|
|
|
```
|
|
$ bin/manifest sign 1 n9JzKV3Z...L6Gf3zwd pnxayCak...yLgogyYc
|
|
```
|
|
|
|
Sample output:
|
|
|
|
```
|
|
[validation_manifest]
|
|
JAAAAAFxIe2PEzNhe996gykB1PJQNoDxvr/Y0XhDELw8d/i
|
|
Fcgz3A3MhAjqhKsgZTmK/3BPEI+kzjV1p9ip7pl/AtF7CKd
|
|
NSfAH9dkCxezV6apS4FLYzAcQilONx315HvebwAB/pLPaM4
|
|
2sWCEppSuLNKN/JJjTABOo9tmAiNnnstF83yvecKMJzniwN
|
|
```
|
|
|
|
Copy this to the config for this validator. Don't forget to update the comment
|
|
noting the sequence number.
|
|
|
|
## Revoking a key
|
|
|
|
If a master key is compromised, the key may be revoked permanently. To revoke a
|
|
master key, sign a manifest with the highest possible sequence number:
|
|
`4,294,967,295`
|