Getting started
Hummingbird is a toolkit of two encryption engines – Hummingbird.1024 for data in
transit and SEA 1024 for data at rest – controlled by a single command-line tool called
hb. You will need about ten minutes, a terminal and a healthy distrust of plaintext.
The typical flight looks like this:
- Install the
hb command-line tool.
- Hatch a key pair on an elliptic curve of your choice.
- Seal a file, send it to a friend, and watch them unseal it.
- Configure automatic key rotation and forget about it forever.
Note: This is a sketch website. None of the commands below will
actually encrypt anything – but they look fantastic in a terminal.
Installation
Pick the package manager you already trust. All packages are signed with our release key, which is
itself signed by a key that lives in a safe in a basement in Vienna.
npm install @hummingbird/1024
pip install hummingbird-sea
brew install hummingbird
Verify the installation with hb --version. If it prints a tiny ASCII bird, you are good to
go.
Generating keys
Keys are hatched, not generated – it is a small distinction, but the birds insist on it. The default
curve nectar-1024 is a good choice for nearly everybody.
hb keys hatch --curve nectar-1024 --out ./keys
Choosing a curve
Hummingbird supports seven curves. Larger curves are stronger and slightly slower; smaller curves are
faster and slightly smug about it. When in doubt, stay with the default.
Encrypting files
Sealing a file turns it into ciphertext with the .hb extension. Unsealing reverses the
process for anyone holding the matching private key.
hb seal ./diary.txt --key ./keys/public.hbk
hb unseal ./diary.txt.hb --key ./keys/private.hbk
For data at rest, add --engine sea and SEA 1024 will wrap the file in five envelope
layers instead of one.
Key rotation
Rotation replaces your working keys on a schedule, while older keys stay available for unsealing old
files. Put the following into hummingbird.yaml:
rotation:
interval: 7d
strategy: nectar
keep_previous: 3
notify: "security@your-company.example"
Configuration reference
All options can be set in hummingbird.yaml or overridden with an environment variable
prefixed with HB_.
Troubleshooting
Error HB-404: Bird not found
The key file could not be located. Check the path, then check that nobody renamed
private.hbk to private_FINAL_v2.hbk.
The ciphertext looks like plaintext
It should not. Make sure the legacy --rot13-compat flag is switched off – it exists only
for a museum exhibit and should never be used in production.
Still stuck?
Browse the FAQ, follow one of the
tutorials or contact
us. A real human answers, usually within one business day.