Skip to content

Commit

Permalink
docs: update readme (#6)
Browse files Browse the repository at this point in the history
  • Loading branch information
shrimalmadhur authored Oct 23, 2024
1 parent 7320f9e commit 6ce641c
Showing 1 changed file with 101 additions and 20 deletions.
121 changes: 101 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
@@ -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.

<!-- TOC -->
* [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)
<!-- TOC -->

### Installation
#### Quick start
Expand All @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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 <key-name>
```
2. Copy the private key from the output.
3. Import the key into cerberus
```bash
grpcurl -plaintext -d '{"privateKey": "<pk>", "password": "p@$$w0rd"}' <ip>:<port> keymanager.v1.KeyManager/ImportKey
```

## Security Bugs
Please report security vulnerabilities to [email protected]. Do NOT report security bugs via Github Issues.

0 comments on commit 6ce641c

Please sign in to comment.