Overview

Piggy Bank was born from a desire to easily store accessible secrets anywhere and not needing to expose HTTP ports for things like Vault. This project is no where near as robust as Vault (hence the name Piggy Bank) but it is desirable to be able to store secrets in the NATS KV store and have secrets be accessible to services using the bus.

Authentication

Authentication and authorization is done by using normal NATS auth. The fact that NATS has robust options for deciding which services can access which subjects allowed the rest of the application to be fairly simple.

All that’s needed is for Piggy Bank to be able to listen on the piggybank.> subject. It should be the only service listening on this subject. Services that need to send requests to Piggy Bank need to be able to publish to their corresponding subject name in some kind of service layout. For example if the service is named Foo it would publish to piggybank.applications.foo. Now any secret stored under that subject can be requested by Foo. If you have a global secret, it would be beneficial to have a subject called piggybank.applications.global and let all applications request secrets from that subjet.

To secure responses from Piggy Bank, applications should have defined inbox names. To keep it simple a name like foo.secrets.> could be used. Piggy Bank then needs the ability to publish to that subject. This way apps can only see the responses they are supposed to see instead of the default of _INBOX.>.

Initialization

  1. To initialize Piggy Bank an empty request needs to be sent to piggybank.database.initialize (nats req piggybank.database.initialize "" from the cli). Piggy Bank will then return an ecryption key. Waring: if this key is lost, all data is unrecoverable.

  2. The database can be unlocked with that key. Send a request to piggybank.database.unlock with the payload '{"database_key": "key_contents"}' (nats req piggybank.database.unlock '{"database_key": "foobar"}' with the cli).

Usage

  1. Piggy Bank leverages the headers in the NATS message to determine the operation, similar to HTTP requests. To create a secret send a payload with the secret contents and the header method:post to piggybank.myapplication.registrySecret (nats req -H method:post piggybank.myapplication.registrySecret "somesecrettext" with the cli).

  2. To retrieve the secret, use the header method:get on the subject piggybank.myapplication.registrySecret (nats req -H method:get piggybank.myapplication.registrySecret with the cli).

Locking the Database

The database can be locked at any time by sending an empty request to piggybank.database.lock (nats req piggybank.database.lock "" with the cli).

It is very important to limit publishing permissions to only those who should be able to lock and unlock the database.