|Dec 23, 2023
|Nov 16, 2023
|Nov 16, 2023
#850 in HTTP server
26 downloads per month
Blockchain Commons Depository
by Wolf McNally
Blockchain Commons Depository (
depo) is server-based software that provides
for the secure storage and retrieval of binary objects without regard to their
contents. Typical use cases would be shards of cryptographic seeds or private
keys created using Shamir's Secret Sharing (SSS) or Sharded Secret Key
Reconstruction (SSKR). Various parties can run depositories (depos) to provide a
distributed infrastructure for secure and non-custodial social key recovery.
This is an early development release. It is not yet ready for production use.
For macOS development and maintenance I recommend DBeaver as a GUI database client.
depo was developed using MariaDB, but it should work well with MySQL as well.
The following instructions are for MariaDB.
$ brew install mariadb
$ brew services start mariadb
$ sudo $(brew --prefix mariadb)/bin/mariadb-admin -u root password NEWPASSWORD
For no password (development only!):
sudo $(brew --prefix mariadb)/bin/mariadb-admin -u root password ''
To verify that the brew service is running:
brew services list | grep mariadb
To verify that the server is active and that it is listening on the default port:
lsof -i :3306
To log into the monitor:
mariadb -u root -p
After cloning this repository, switch to its directory and run:
After it compiles, the server will run. You will see welcome messages, including
the server's public key (
ur:crypto-pubkeys) which you will need to access its
API. The first time the server runs it will set up the database schema.
In this early development release, it will log into the database as
no password. Obviously this will be fixed before a production release.
[2023-11-16T03:10:21Z INFO depo::server] Starting Blockchain Commons Depository on 127.0.0.1:5332
[2023-11-16T03:10:21Z INFO depo::server] Public key: ur:crypto-pubkeys/lftanshfhdcxnnimfnjzlnwkzmrofmluglosetrteyjeonkgchmybbktcmonksbyjocsjkehjllytansgrhdcxlrrkgypmierotkgsgdntpdptntptzegabagmfxdlsgiobnveiypsstjkzoosyahyynimcwze
[2023-11-16T03:10:21Z INFO warp::server] Server::run; addr=127.0.0.1:5332
[2023-11-16T03:10:21Z INFO warp::server] listening on http://127.0.0.1:5332
To test that it is running, open a browser and navigate to http://localhost:5332
You should see the same
ur:crypto-pubkeys appear in the browser window. This
is the only HTTP GET endpoint in the server. All API access is via POST.
Learning the API
The API is Trust On First Use (TOFU), so there is no account creation. The first time a client stores a BLOB, an account is created for it. The client's public key is used to identify the account.
All requests to the API include the client's public key and must be signed using the client's private key, and encrypted using the server's public key, which can be obtained using the HTTP GET endpoint. The server will validate that the public key in the request matches the key used to sign the request.
All responses from the server are encrypted using the client's public key, and signed using the server's private key. In addition to decrypting the response with the client's private key, the client should verify the signature using the server's public key.
We currently recommend that you examine the integration tests to learn about the API.
There are nine supported functions:
Storing, Retrieving, and Deleting BLOBs
storeShare- stores a single BLOB associated with the client's public key, returns a Receipt.
getShares- takes a list of
Receipts and returns the BLOBs associated with the client's public key and those receipts. If the list of receipts is empty, it returns all BLOBs associated with the client's public key.
deleteShares- takes a list of
Receipts and deletes the BLOBs associated with the client's public key and those receipts. If the list of receipts is empty, it deletes all BLOBs associated with the client's public key.
updateKey- Updates the client's public key. This is used to change the client's public key when necessary.
updateRecovery- Updates or removes the client's recovery method. This is a second-factor authentication method that is used to authorize assigning a new public key.
getRecovery- Returns the client's recovery method, if any.
startRecovery- Starts the recovery process. This includes a new public key. To finish the process, the client must use the second-factor authentication method to retrieve a continuation.
finishRecovery- Finishes the recovery process by taking the continuation retrieved using the second-factor authentication method. If the continuation has not expired, the client's public key is updated to the new public key.
deleteAccount- Deletes the client's account, including all BLOBs and recovery method.
depo-api crate provides a Rust API
depo server. It is intended to be used by clients that want to store
and retrieve BLOBs from a
depo server. It primarily includes structures and
methods to marshal and unmarshal the API requests and responses.