mavseal

README

A Mavryk Remote Signer

What is MavSeal?

MavSeal is a remote signing daemon that allows Mavryk bakers and Mavryk Application teams to protect their private keys.

The goal of the MavSeal service is to make key management as secure as possible in a Cloud and on-premise HSM context.

Why Use MavSeal?

Security and convenience are typically at odds with each other. MavSeal makes it easier for Mavryk teams to manage their keys securely by offering several well-tested & supported signing options for cloud-based or hardware-based HSMs.

Quick Start

See docs

---

GitHub Docs

Explore detailed documentation for various components of MavSeal:

Introduction

• Getting Started
• Authorized Keys
• Command-Line Interface (CLI)
• Bakers

Vault Backends

• Azure KMS
• AWS KMS
• Google Cloud KMS
• Hashicorp Vault
• Ledger Integration
• Local Secret Storage
• PKCS#11 (AWS CloudHSM compatible)
• YubiHSM

Watermark backends

• AWS (DynamoDB)

Other

• JWT Authentication
• Remote Policy Configuration
• MavSeal Architecture

Features

Remote Signing

MavSeal receives requests to sign Mavryk operations. These operations may be consensus operations when used in a Baking context, or they may be transactions or any other Mavryk operation type.

MavSeal will inspect the operations and assert that the operation request is in line with MavSeal's policy. If the operation passes the policy rules, MavSeal will then have a signature produced using the appropriate backend system.

MavSeal operators can choose from AWS, Azure or Google Cloud KMS systems, or self-hosted solutions such as the YubiHSM2, Hashicorp Vault or Ledger Hardware wallet.

Observability

MavSeal is also focused on observability, exposing metrics about its performance, volume and possible errors. Metrics allow operators to see historical trends, signing volumes, errors and latencies, enabling rich reporting and alerting capabilities.

Private-Key Import

Private-key import is an important security consideration when choosing a Cloud KMS offering. Some KMS's allow you to generate the secret key internally so that no one can extract the private key from the HSM. Others allow for private-key import with different levels of security. The trade-offs in this context are essential to understand.

---

How it Works

• A Mavryk operation is sent to the MavSeal API
• MavSeal decodes and checks that the operation is permitted based on the defined policy
• MavSeal sends the operation to the configured vault backend for signing
• Upon receiving the signature produced by backend, MavSeal validates the signature
• MavSeal returns the signature to MavSeal client

Why

Our goal in supporting multiple Cloud KMS/HSM services is to help prevent centralization on the network or infrastructure level. A goal of Mavryk is to have a highly decentralized network of bakers. That goal is not fully realized if, of those bakers, a large majority operate on a single infrastructure provider.

In the first year of the Mavryk network operation, there was anecdotal evidence that many bakers ran on AWS. AWS is a superb provider, but having a concentration of nodes on one cloud vendor centralizes the underlying infrastructure of the network, which is not desirable. By supporting multiple Cloud KMS/HSM systems, we hope to prevent the network from centralization on a particular Cloud offering.

Supported Signing Backends

Backend KMS/HSM Support Status

	Status
YubiHSM2	✅
Azure KMS	✅
Google Cloud KMS	✅
AWS KMS	✅
Ledger Nano S/S+ (Baking only)	✅
Hashicorp Vault	✅
PKCS#11	✅

Mavryk Address Types

In Mavryk, you can infer the signing algorithm from the first three characters of an address. For example, an address beginning with mv3 uses the P-256 algorithm. HSMs and Cloud-based HSMs have support for a subset of the three algorithms supported by Mavryk.

• mv1 - Ed25519
• mv2 - Secp256k1 aka: P256K
• mv3 - P-256
• mv4 - BLS12-381

Signing Algorithm Support From Various Backends

	mv1	mv2	mv3
Hashicorp Vault	✅	❌	❌
Google Cloud KMS	❌	❌	✅
AWS KMS	❌	✅	✅
Azure KMS	❌	✅	✅
YubiHSM2	✅	✅	✅
PKCS#11	✅	✅	✅

---

Reporting Issues

Security Issues

To report a security issue, please contact info@mavryk.io

Other Issues & Feature Requests

Please use the GitHub issue tracker to report bugs or request features.

Contributions

To contribute, please check the issue tracker to see if an issue exists for your planned contribution. If there's no issue, please create one first, and then submit a pull request with your contribution.

For a contribution to be merged, it is required to have complete documentation and come with unit tests and integration tests where appropriate. Submitting a "work in progress" pull request is welcome!

---

Disclaimer

THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.