Manifest.h

#pragma once
 
#include <xrpl/basics/Blob.h>
#include <xrpl/basics/Slice.h>
#include <xrpl/basics/UnorderedContainers.h>
#include <xrpl/basics/base64.h>
#include <xrpl/basics/base_uint.h>
#include <xrpl/beast/utility/Journal.h>
#include <xrpl/protocol/PublicKey.h>
#include <xrpl/protocol/SecretKey.h>
 
#include <atomic>
#include <cstddef>
#include <cstdint>
#include <functional>
#include <optional>
#include <shared_mutex>
#include <string>
#include <type_traits>
#include <utility>
#include <vector>
 
namespace xrpl {
 
/*
    Validator key manifests
    -----------------------
 
    Suppose the secret keys installed on an XRPL validator are compromised. Not
    only do you have to generate and install new key pairs on each validator,
    EVERY xrpld needs to have its config updated with the new public keys, and
    is vulnerable to forged validation signatures until this is done.  The
    solution is a new layer of indirection: A master secret key under
    restrictive access control is used to sign a "manifest": essentially, a
    certificate including the master public key, an ephemeral public key for
    verifying validations (which will be signed by its secret counterpart), a
    sequence number, and a digital signature.
 
    The manifest has two serialized forms: one which includes the digital
    signature and one which doesn't.  There is an obvious causal dependency
    relationship between the (latter) form with no signature, the signature
    of that form, and the (former) form which includes that signature.  In
    other words, a message can't contain a signature of itself.  The code
    below stores a serialized manifest which includes the signature, and
    dynamically generates the signatureless form when it needs to verify
    the signature.
 
    An instance of ManifestCache stores, for each known validator, (a) its
    master public key, and (b) the most senior of all valid manifests it has
    seen for that validator, if any.  On startup, the [validator_token] config
    entry (which contains the manifest for this validator) is decoded and
    added to the manifest cache.  Other manifests are added as "gossip"
    received from xrpld peers, including ones for validators this node does not
    trust. Manifests for untrusted validators are capped (kMaxUntrustedCount)
    so peer gossip cannot grow the cache without bound; trusted validators are
    not capped. Entries are never evicted, so a stored revocation is permanent.
 
    When an ephemeral key is compromised, a new signing key pair is created,
    along with a new manifest vouching for it (with a higher sequence number),
    signed by the master key.  When an xrpld peer receives the new manifest,
    it verifies it with the master key and (assuming it's valid) discards the
    old ephemeral key and stores the new one.  If the master key itself gets
    compromised, a manifest with sequence number 0xFFFFFFFF will supersede a
    prior manifest and discard any existing ephemeral key without storing a
    new one.  These revocation manifests are loaded from the
    [validator_key_revocation] config entry as well as received as gossip from
    peers.  Since no further manifests for this master key will be accepted
    (since no higher sequence number is possible), and no signing key is on
    record, no validations will be accepted from the compromised validator.
*/
 
//------------------------------------------------------------------------------
 
struct Manifest
{
    std::string serialized;

    PublicKey masterKey;

    // A revoked manifest does not have a signingKey
    // This field is specified as "optional" in manifestFormat's
    // SOTemplate
    std::optional<PublicKey> signingKey;

    std::uint32_t sequence = 0;

    std::string domain;
 
    Manifest() = delete;
 
    Manifest(
        std::string serialized,
        PublicKey const& masterKey,
        std::optional<PublicKey> const& signingKey,
        std::uint32_t seq,
        std::string domain)
        : serialized(std::move(serialized))
        , masterKey(masterKey)
        , signingKey(signingKey)
        , sequence(seq)
        , domain(std::move(domain))
    {
    }
 
    Manifest(Manifest const& other) = delete;
    Manifest&
    operator=(Manifest const& other) = delete;
    Manifest(Manifest&& other) = default;
    Manifest&
    operator=(Manifest&& other) = default;

    [[nodiscard]] bool
    verify() const;

    [[nodiscard]] UInt256
    hash() const;

    // The maximum possible sequence number means that the master key has
    // been revoked
    static bool
    revoked(std::uint32_t sequence);

    [[nodiscard]] bool
    revoked() const;

    [[nodiscard]] std::optional<Blob>
    getSignature() const;

    [[nodiscard]] Blob
    getMasterSignature() const;
};

std::string
to_string(Manifest const& m);

constexpr std::size_t kMaxManifestBytes = 358;

constexpr std::size_t kMaxManifestBase64 = base64::encodedSize(kMaxManifestBytes);

constexpr std::size_t kMaxUntrustedCount = 300;

constexpr std::size_t kMaxTrustedCount = 300;

constexpr std::size_t
untrustedManifestCount(std::optional<std::size_t> const& configured)
{
    return configured.value_or(kMaxUntrustedCount);
}

constexpr std::size_t
trustedManifestCount(std::optional<std::size_t> const& configured)
{
    return configured.value_or(kMaxTrustedCount);
}

std::optional<Manifest>
deserializeManifest(Slice s, beast::Journal journal);
 
inline std::optional<Manifest>
deserializeManifest(
    std::string const& s,
    beast::Journal journal = beast::Journal(beast::Journal::getNullSink()))
{
    return deserializeManifest(makeSlice(s), journal);
}
 
template <class T>
std::optional<Manifest>
deserializeManifest(
    std::vector<T> const& v,
    beast::Journal journal = beast::Journal(beast::Journal::getNullSink()))
    requires(std::is_same_v<T, char> || std::is_same_v<T, unsigned char>)
{
    return deserializeManifest(makeSlice(v), journal);
}

 
inline bool
operator==(Manifest const& lhs, Manifest const& rhs)
{
    // In theory, comparing the two serialized strings should be
    // sufficient.
    return lhs.sequence == rhs.sequence && lhs.masterKey == rhs.masterKey &&
        lhs.signingKey == rhs.signingKey && lhs.domain == rhs.domain &&
        lhs.serialized == rhs.serialized;
}
 
struct ValidatorToken
{
    std::string manifest;
    SecretKey validationSecret;
};
 
std::optional<ValidatorToken>
loadValidatorToken(
    std::vector<std::string> const& blob,
    beast::Journal journal = beast::Journal(beast::Journal::getNullSink()));
 
enum class ManifestDisposition {
    Accepted = 0,  
 
    Stale,  
 
    BadMasterKey,  
 
    BadEphemeralKey,  
 
    Invalid,  
 
    UntrustedCapacity  
};
 
inline std::string
to_string(ManifestDisposition m)
{
    switch (m)
    {
        case ManifestDisposition::Accepted:
            return "accepted";
        case ManifestDisposition::Stale:
            return "stale";
        case ManifestDisposition::BadMasterKey:
            return "badMasterKey";
        case ManifestDisposition::BadEphemeralKey:
            return "badEphemeralKey";
        case ManifestDisposition::Invalid:
            return "invalid";
        case ManifestDisposition::UntrustedCapacity:
            return "untrustedCapacity";
        default:
            return "unknown";
    }
}

enum class ManifestRateLimitCapPolicy : std::uint8_t {
    Capped,   
    Uncapped  
};
 
class DatabaseCon;

class ManifestCache
{
private:
    beast::Journal j_;
    std::shared_mutex mutable mutex_;

    HashMap<PublicKey, Manifest> map_;

    HashMap<PublicKey, PublicKey> signingToMasterKeys_;
 
    std::atomic<std::uint32_t> seq_{0};

    HashSet<PublicKey> untrustedKeys_;

    std::size_t const maxUntrustedCount_;

    std::atomic<std::uint64_t> untrustedRejectCount_{0};

    static constexpr std::uint64_t kUntrustedRejectCount = 10000;
 
public:
    explicit ManifestCache(
        beast::Journal j = beast::Journal(beast::Journal::getNullSink()),
        std::size_t maxUntrustedCount = kMaxUntrustedCount)
        : j_(j), maxUntrustedCount_(maxUntrustedCount)
    {
    }

    std::uint32_t
    sequence() const
    {
        return seq_.load();
    }

    std::optional<PublicKey>
    getSigningKey(PublicKey const& pk) const;

    PublicKey
    getMasterKey(PublicKey const& pk) const;

    std::optional<std::uint32_t>
    getSequence(PublicKey const& pk) const;

    std::optional<std::string>
    getDomain(PublicKey const& pk) const;

    std::optional<std::string>
    getManifest(PublicKey const& pk) const;

    bool
    revoked(PublicKey const& pk) const;

    ManifestDisposition
    applyManifest(Manifest m, ManifestRateLimitCapPolicy cap);

    void
    promoteToTrusted(PublicKey const& pk);

    bool
    load(
        DatabaseCon& dbCon,
        std::string const& dbTable,
        std::string const& configManifest,
        std::vector<std::string> const& configRevocation);

    void
    load(DatabaseCon& dbCon, std::string const& dbTable);

    void
    save(
        DatabaseCon& dbCon,
        std::string const& dbTable,
        std::function<bool(PublicKey const&)> const& isTrusted);

    template <class Function>
    void
    forEachManifest(Function&& f) const
    {
        std::shared_lock const lock{mutex_};
        for (auto const& [_, manifest] : map_)
        {
            (void)_;
            f(manifest);
        }
    }

    template <class PreFun, class EachFun>
    void
    forEachManifest(PreFun&& pf, EachFun&& f) const
    {
        std::shared_lock const lock{mutex_};
        pf(map_.size());
        for (auto const& [_, manifest] : map_)
        {
            (void)_;
            f(manifest);
        }
    }
};
 
}  // namespace xrpl