From 6ce641c6323c412b2b9383169ee70fef22c13c60 Mon Sep 17 00:00:00 2001 From: Madhur Shrimal Date: Wed, 23 Oct 2024 12:38:18 -0400 Subject: [PATCH] docs: update readme (#6) --- README.md | 121 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 101 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index f19a117..d423e4e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,20 @@ # Remote Signer Implementation of cerberus-api -This is a remote signer for BLS signatures on the BN254 curve. - +This is a remote signer which supports BLS signatures on the BN254 curve. + + +* [Remote Signer Implementation of cerberus-api](#remote-signer-implementation-of-cerberus-api) + * [Installation](#installation) + * [Quick start](#quick-start) + * [Manual](#manual) + * [Usage options](#usage-options) + * [Monitoring](#monitoring) + * [Configuring Server-side TLS (optional)](#configuring-server-side-tls-optional) + * [Generating TLS certificates](#generating-tls-certificates) + * [Starting the server with TLS support](#starting-the-server-with-tls-support) + * [Connecting a GO client with the server using TLS](#connecting-a-go-client-with-the-server-using-tls) + * [Migrating keys from eigenlayer-cli to cerberus](#migrating-keys-from-eigenlayer-cli-to-cerberus) + * [Security Bugs](#security-bugs) + ### Installation #### Quick start @@ -19,15 +33,17 @@ go build -o bin/cerberus cmd/cerberus/main.go ``` ### Usage options -| Options | Description | Default | -|--------------|---------------------------------------------|-----------------| -| keystore-dir | Directory to store encrypted keystore files | ./data/keystore | -| grpc-port | gRPC port for starting signer server | 50051 | -| log-format | format of the logs (text, json) | text | -| log-level | debug, info, warn, error | info | -| metrics-port | port to expose prometheus metrics | 9091 | -| help | show help | | -| version | show version | | +| Options | Description | Default | +|----------------|---------------------------------------------|-----------------| +| keystore-dir | Directory to store encrypted keystore files | ./data/keystore | +| grpc-port | gRPC port for starting signer server | 50051 | +| log-format | format of the logs (text, json) | text | +| log-level | debug, info, warn, error | info | +| metrics-port | port to expose prometheus metrics | 9091 | +| tls-ca-cert | certificate to enable TLS connection | | +| tls-server-key | server key to enable TLS connection | | +| help | show help | | +| version | show version | | ### Monitoring @@ -38,15 +54,6 @@ There is a grafana dashboard available in the `monitoring` directory. You can im Server-side TLS support is provided to encrypt traffic between the client and server. This can be enabled by starting the service with `tls-ca-cert` and `tls-server-key` parameters set: -``` -cerberus -tls-ca-cert server.crt -tls-server-key server.key -``` - -The server can then be queried over a secure connection using a gRPC client that supports TLS. For example, using `grpcurl`: - -``` -grpcurl -cacert ../cerberus/server.crt -d '{"password": "test"}' -import-path . -proto proto/keymanager.proto localhost:50051 keymanager.v1.KeyManager/GenerateKeyPair -``` #### Generating TLS certificates For local testing purposes, the following commands can be used to generate a server certificate and key. @@ -93,5 +100,79 @@ openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt - server.crt and server.key files can then be used to start the server with TLS support. +#### Starting the server with TLS support + +``` +cerberus -tls-ca-cert server.crt -tls-server-key server.key +``` + +The server can then be queried over a secure connection using a gRPC client that supports TLS. For example, using `grpcurl`: + +``` +grpcurl -cacert server.crt -d '{"password": "test"}' -import-path . -proto proto/keymanager.proto localhost:50051 keymanager.v1.KeyManager/GenerateKeyPair +``` + +#### Connecting a GO client with the server using TLS + +```go +package main + +import ( + "context" + "fmt" + "log" + "time" + + "github.com/Layr-Labs/cerberus-api/pkg/api/v1" + + "google.golang.org/grpc" + "google.golang.org/grpc/credentials" +) + +func main() { + creds, err := credentials.NewClientTLSFromFile("server.crt", "") + if err != nil { + log.Fatalf("could not load tls cert: %s", err) + } + + conn, err := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(creds)) + if err != nil { + log.Fatalf("did not connect: %v", err) + } + defer conn.Close() + + c := v1.NewSignerClient(conn) + + ctx, cancel := context.WithTimeout(context.Background(), time.Second) + defer cancel() + + req := &v1.SignGenericRequest{ + PublicKey: "0xabcd", + Password: "p@$$w0rd", + Data: []byte{0x01, 0x02, 0x03}, + } + resp, err := c.SignGeneric(ctx, req) + if err != nil { + log.Fatalf("could not sign: %v", err) + } + fmt.Printf("Signature: %v\n", resp.Signature) +} +``` + +### Migrating keys from eigenlayer-cli to cerberus +If you created your keys using the eigenlayer-cli, +you won't be able to directly copy the encrypted json file as this keystore uses ERC2335 format (eigenlayer-cli will add support for this soon). + +You can migrate them to cerberus using the following steps: +1. Export your keys from eigenlayer-cli + ```bash + eigenlayer keys export --key-type bls + ``` +2. Copy the private key from the output. +3. Import the key into cerberus + ```bash + grpcurl -plaintext -d '{"privateKey": "", "password": "p@$$w0rd"}' : keymanager.v1.KeyManager/ImportKey + ``` + ## Security Bugs Please report security vulnerabilities to security@eigenlabs.org. Do NOT report security bugs via Github Issues.