Resources

Documentation READ THE FEATHERS

Everything you need to hatch, configure and fly Hummingbird in production.

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:

  1. Install the hb command-line tool.
  2. Hatch a key pair on an elliptic curve of your choice.
  3. Seal a file, send it to a friend, and watch them unseal it.
  4. 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.

# Node.js
npm install @hummingbird/1024

# Python
pip install hummingbird-sea

# macOS / Linux
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

# ./keys/public.hbk   share this with the world
# ./keys/private.hbk  share this with nobody, not even your cat

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
# → ./diary.txt.hb

hb unseal ./diary.txt.hb --key ./keys/private.hbk
# → ./diary.txt (with all of its secrets intact)

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_.

OptionDefaultDescription
curvenectar-1024Elliptic curve used for new keys.
rounds1024Number of mixing rounds. More rounds, more dizziness.
feather_modefalseEnables the low-power cipher profile.
audittrueWrites a signed entry for every operation.
log_levelchirpOne of silent, chirp, sing, screech.

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.