From e439b2286dfa22dd69f177a2d1f1463afe35b690 Mon Sep 17 00:00:00 2001 From: Le Chiffre Date: Sun, 21 Jan 2024 17:52:24 -0500 Subject: [PATCH 1/2] Enhance documentation --- .env.sample | 5 ++++- README.md | 41 ++++++++++++++++++++++++++++++++++++++--- src/routes.rs | 2 ++ 3 files changed, 44 insertions(+), 4 deletions(-) diff --git a/.env.sample b/.env.sample index a250ac1..3726279 100644 --- a/.env.sample +++ b/.env.sample @@ -1,2 +1,5 @@ DATABASE_URL=postgres://localhost/vss -AUTH_KEY= +#VSS_PORT=8080 +#AUTH_KEY= +#SELF_HOST=true +#ADMIN_KEY= \ No newline at end of file diff --git a/README.md b/README.md index e888c7f..c18fb85 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,47 @@ # vss-rs -A rust implementation of a VSS server. Based on [LDK's `vss-server` reference implementation](https://github.com/lightningdevkit/vss-server). +A rust implementation of a VSS server. Based on [LDK's `vss-server` reference implementation](https://github.com/lightningdevkit/vss-server). See the [API Contract](https://github.com/lightningdevkit/vss-server/blob/main/app/src/main/proto/vss.proto). ## Usage You need a postgres database and an authentication key. These can be set in the environment variables `DATABASE_URL` -and `AUTH_KEY` respectively. This can be set in a `.env` file in the root of the project. If you do not have an -authentication key, you can set `SELF_HOST=true` in the `.env` file and the server will skip authentication. +and `AUTH_KEY` respectively. These can be set in a `.env` file in the root of the project. If you do not have an +authentication key, leave this unset and the server will skip authentication. To run the server, run `cargo run --release` in the root of the project. +## Configuration + +vss-rs is configured via environment variables, which may be set in an `.env` file in the working directory, or injected dynamically (command-line prefix, container orchestration, etc.) See `.env.sample`. + + - `DATABASE_URL`: a postgres connection string of the format `postgres://u:p@host[:port]/dbname` + - `VSS_PORT`: (optional; default 8080) host port to bind + - `AUTH_KEY`: (optional; default none) hex-encoded ES256K public key + - `SELF_HOST`: (optional; default false) + - `ADMIN_KEY`: (optional; default none) key to use as bearer token to trigger admin actions like migration + +## Database + +Scheme migrations can be run manually via `diesel-cli`, or automatically on startup when `SELF_HOST` is true. + +They can also be triggered _ad hoc_ by passing a bearer token corresponding to `ADMIN_KEY` to the `/migrations` endpoint. + +## CORS + +CORS headers are supplied with responses, and Origin headers are validated against the list when handling requests. This behavior is disabled when `SELF_HOST` is true. + +If you intend to host this in a public-facing way (_i.e._, not just on `localhost`), you'll need to add your domain to the `ALLOWED_ORIGINS` in `main.rs`. + +## Authentication + +In production usage, the VSS clients (lightning wallets) should authenticate with a [JSON Web Token(JWT)](https://datatracker.ietf.org/doc/html/rfc7519) issued by an identity provider (not included in VSS-RS). + +### Authentication Key + +The authentication key, set with `AUTH_KEY`, is a hex-encoded ECDSA _public_ key on the p256k1 curve and is used to validate the signature on a client-supplied JWT. The VSS client may have obtained the JWT from any issuing party as long as you set the appropriate public key here. The JWT should have set the `alg` parameter to `ES256K`. (see below) + +### Aside on ES256K + +JWT RFAs define algorithms `ES256` and `ES256K` as ECDSA assymetric cryptography with `secp256r1` and `secp256k1`, respectively. `sep256k1` is much less common in general, but is famously used in Bitcoin and Tor. Unfortunately, many identity providers (JWT issuers) (a) may not support `ES256K` and (b) don't clearly differentiate between the two algorithms and state P256 when they really mean `secp256r1`. + +VSS-RS uses `ES256K` because we expect VSS clients (lightning wallets) to obtain JWT from an identity provider using a [LNURL-auth](https://github.com/lnurl/luds/blob/legacy/lnurl-auth.md) / [Login with Lightning!](https://lightninglogin.live/) service. diff --git a/src/routes.rs b/src/routes.rs index 7003a73..9d09a51 100644 --- a/src/routes.rs +++ b/src/routes.rs @@ -60,6 +60,7 @@ pub async fn get_object_impl( Ok(item.and_then(|i| i.into_kv())) } +/// Returns value as base64-encoded string pub async fn get_object( origin: Option>, auth: Option>>, @@ -85,6 +86,7 @@ pub async fn get_object( } } +/// Returns value as a byte array pub async fn get_object_v2( origin: Option>, auth: Option>>, From b035bdb4781d99421f6622849b6ec6fddcb923c9 Mon Sep 17 00:00:00 2001 From: Le Chiffre Date: Wed, 24 Jan 2024 22:53:28 -0500 Subject: [PATCH 2/2] Remove text on ES256K --- README.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/README.md b/README.md index c18fb85..f5bd1c3 100644 --- a/README.md +++ b/README.md @@ -38,10 +38,4 @@ In production usage, the VSS clients (lightning wallets) should authenticate wit ### Authentication Key -The authentication key, set with `AUTH_KEY`, is a hex-encoded ECDSA _public_ key on the p256k1 curve and is used to validate the signature on a client-supplied JWT. The VSS client may have obtained the JWT from any issuing party as long as you set the appropriate public key here. The JWT should have set the `alg` parameter to `ES256K`. (see below) - -### Aside on ES256K - -JWT RFAs define algorithms `ES256` and `ES256K` as ECDSA assymetric cryptography with `secp256r1` and `secp256k1`, respectively. `sep256k1` is much less common in general, but is famously used in Bitcoin and Tor. Unfortunately, many identity providers (JWT issuers) (a) may not support `ES256K` and (b) don't clearly differentiate between the two algorithms and state P256 when they really mean `secp256r1`. - -VSS-RS uses `ES256K` because we expect VSS clients (lightning wallets) to obtain JWT from an identity provider using a [LNURL-auth](https://github.com/lnurl/luds/blob/legacy/lnurl-auth.md) / [Login with Lightning!](https://lightninglogin.live/) service. +The authentication key, set with `AUTH_KEY`, is a hex-encoded ECDSA _public_ key on the p256k1 curve and is used to validate the signature on a client-supplied JWT. The VSS client may have obtained the JWT from any issuing party as long as you set the appropriate public key here. The JWT should have set the `alg` parameter to `ES256K`. This is uncommon and should not be confused with `ES256`. \ No newline at end of file