9 releases

0.4.2 Aug 29, 2022
0.4.1 Aug 28, 2022
0.4.0 Sep 8, 2021
0.3.4 Jul 1, 2020
0.2.0 May 31, 2020

#253 in Cryptography

29 downloads per month

MIT and GPL-3.0-only

445 lines

Hide in plain sight


hips is a small, self-contained utility that enables users to store their secrets encrypted alongside their code. It can be used as a binary or a library depending on your needs. What are you interested in knowing?

  1. Why do this?
  2. Let's try it out
  3. Tutorial
  4. Is this even safe



For all the small shops out there, the low profile targets with a limited amount of individual developers involved, we suggest tracking your secrets alongside your code, in a file or folder database.

This will reduce sources of truth in your distributed system by 1 and help with "infrastructure as code" by making access to the secrets a local affair. You will not have to depend on any kind of remote infrastructure for your secrets.

This solution will not work well for you if you:

  • Have many developers (master-password strategy does not scale well)
  • High scale/complexity infra (a need for secrets as a service)
  • High profile shops (compliance reasons, need insurances)

In this database, you could store your AWS credentials or the ssh key you use to connect to your production. You could store secrets needed by your serving layer to authenticate with your database and push those using a tool like ansible or ssh.


You will need cargo to install hips. Once you have it, do the following:

export PATH=$PATH:$HOME/.cargo/bin
cargo install hips
hips --help


In this tutorial you will learn about all the different commands and database formats that hips supports.

Database and password configuration

We use environment variables to pass the database and password to hips:

$ export HIPS_DATABASE=secrets.yaml
$ export HIPS_PASSWORD=pw

Store, Load, List, Remove, Rename

store takes a name and a secret and stores them in the database.

$ hips store aws_access_key_id BUIO1IXUAK3OQ9ACAHSX
$ hips store aws_secret_access_key UwioixhaklufhhWbaXoSLwbxb2dj7/AJs92bdsXh
$ cat secrets.yaml
- name: aws_access_key_id
  secret: c58C04qkTDQhg86piVlmg7EXcz66i3C3GSdHjmZW5v2Pa6Froo69gbuDNSICXh4w
  salt: OH3/mX3e/3ODwSLBYzFiK92PztSgLLmIf5S8mqenwXo=
- name: aws_secret_access_key
  secret: asrhBl8bMTPGj8Cua6LzyseRBLmhmNrivaCjW53NcNRUyKSYOkoLdq9PHSPHKdgosO6/acOn3hv+vnkciwLj0tio0ac=
  salt: 4GP2GtoRhaf6NKtanBm9aLjUefuNH+otFDFfHF1Utns=%

load takes a name and prints out the matching secret.

$ hips load aws_access_key_id
$ hips load aws_secret_access_key

list prints the names of the secrets stored in the db sorted alphabetically.

$ hips ls

remove (rm) takes a name and removes that secret from the database.

$ hips store remove_me_soon unimportant-secret
$ hips ls
$ hips remove remove_me_soon
$ hips ls

rename renames a secret based on a (orig, dest) name pair

$ hips store move_me_please unimportant-secret
$ hips ls
$ hips rename move_me_please thats_better
$ hips ls


You can rotate (rot) the secrets database in one command, re-encrypting everything using a different password.

$ cat secrets.yaml | grep secret:
  secret: c58C04qkTDQhg86piVlmg7EXcz66i3C3GSdHjmZW5v2Pa6Froo69gbuDNSICXh4w
  secret: asrhBl8bMTPGj8Cua6LzyseRBLmhmNrivaCjW53NcNRUyKSYOkoLdq9PHSPHKdgosO6/acOn3hv+vnkciwLj0tio0ac=
$ hips rotate new-pw
$ cat secrets.yaml | grep secret:
  secret: Sb8BznQqjYr+q+lis2uVKPZ/j+qmNIMuXbjr/MElIAYkupyUCGHPbY+N/NTpTxKr
  secret: FlWQvkzidFa8mStgoEbQXt4MobHPQFT7NFnImKIjgfNZ7xFhPGjj3kD0z3x4YNzLTjBMJykk57JooYCojhOH/GlqeEk=
$ export HIPS_PASSWORD=new-pw
$ hips load aws_access_key_id

You can see here that the encrypted secrets and salt are different from the previous secrets.yaml database. We can now read all the secrets using the new password.


Many times when exporting secrets to production, they need to be displayed in a specific manner, as part of a configuration file and such. We use the tiny template library for this purpose. See their neat syntax page for more information. We will cover our templating capabilities in the following two examples.

AWS credentials file

Let's generate the .aws/credentials, where amazon secrets are conventionally stored. We'll use the "map" feature of the templating framework, which allows us to print out specific secrets by name.

$ hips template '[default]\naws_access_key_id={map.aws_access_key_id}\naws_secret_access_key={map.aws_secret_access_key}'

Shell script loading all secrets

This time, since our template is a bit more complex, we'll store it in a file:

$ cat shell-template
{{ for secret in list -}}
{{- if not @first }}\n{{ endif -}}
export {secret.name|capitalize}={secret.secret};
{{- endfor -}}

You can find more information about this syntax here. This will yield the following shell script:

$ hips template shell-template
export AWS_SECRET_ACCESS_KEY=UwioixhaklufhhWbaXoSLwbxb2dj7/AJs92bdsXh;

Database formats

Up until now, we have been using a yaml file as database. We support multiple formats however:

  • As a directory hierarchy (no extension)
  • As a single yaml file (.yaml extension)

If we were to repeat the experiment above with a directory hierarchy under secrets/, our database would look like this:

$ tree secrets/
├── aws_access_key_id/
   ├── salt
   └── secret
└── aws_secret_access_key/
    ├── salt
    └── secret
$ cat secrets/aws_access_key_id/secret


This project is using ring's pbkdf2 function to derive a proper key from a password and its aes256 implementation to encrypt/decrypt the secrets. In theory at least, those ciphers should not be brute-forceable. You can find an audit of the ring library by Cure53 here.

With this being said, it is still important to protect the encrypted version of our secrets from being public. If you store your secrets alongside your code, that responsibility then befalls your code provider (github for example.)

Ultimately, consider the following three characteristics:

  • Your profile (low-profile target, high-profile?)
  • Your threat-model (who do you accept to trust?)
  • Your compliance requirements (do you have PII data?)

You need to consider all those questions (and more) before deciding on a solution for your secrets management. It is advised that you consult with a security engineer as well.


~268K SLoC