Juuso Hakala | Last updated 4 Jan 2025

Introduction

This article talks about hakjpass, an open source secure CLI based password manager that I recently built. I developed it mainly for myself as a useful tool but anybody is free to use it! It is free and open source software. The tool is programmed in the Go language.

About the tool

The tool is a CLI (Command Line Interface) program. This means that it is used by typing commands in the user’s terminal and executing them. There is no graphical user interface involved. All the output is shown in the terminal. No internet connection is required to use the tool as it works locally on the user’s machine.

The tool’s core idea is to manage passwords. Passwords are stored using password entries. A password entry contains an ID, the password itself, and optional username, password group and description. It is possible to save these entries as well as list, edit and delete them. When listing passwords, they are hidden by default but can be shown by using a command line flag. The tool also has a feature to generate random secure passwords with different lengths.

Below is an example password entry output where the password is hidden

{
  ID: 01942d69-266f-73ae-b803-df522c444a43
  Group: group1
  Username: testuser1
  Password: *****************
  Description:
}

Password groups can be used for example as website names. It is possible to list all the password entries, entries of a specific group or a specific entry using its ID. It is also possible to list all the password groups so the user can then list the password entries of those groups.

How it works

The passwords are stored in a password storage file. The tool saves the entries to this file. To make things more secure, the file is encrypted. This is to prevent storing the passwords in plain text to make it harder for the passwords to get compromised. The tool encrypts the file using AES-256 symmetric encryption algorithm. This involves using a cryptographically random 32 byte key to both encrypt and decrypt the data. It generates a random IV (initialization vector) to make the process more secure so the ciphertexts are always cryptographically random every time the file is encrypted.

The symmetric key is also encrypted and protected by a password using PBKDF2. It works by deriving a random key using a random salt and the password. The derived key is used to encrypt the symmetric key. With this, the password is also needed to decrypt the password storage file making it even more secure. The only down side of this is that if the user loses/forgets the password, they cannot access their passwords anymore. The encrypted key and the salt are Base64 encoded and combined into one key. This combination is the format in which it is stored in the key file. The tool reads this key file to decrypt the key and then uses it to decrypt the password storage file.

The data serialization format used in the program is Protobuf. It is used as the data format to read/write the password storage file. The data structures for the password entries and the password storage are defined in a file with .proto extension. Source codes for Golang can then be generated from this file with the Protobuf compiler. The generated source codes contain Golang data structures that can be used to marshal the password storage into binary format. The binary format is then encrypted and stored in the password storage file.

Backing up the data

The password storage file and the key file can be safely backed up to external devices and to the cloud because they are encrypted. If someone manages to get access to them, they won’t be able to do anything with them. If backed up to the cloud, it is best to save them in separate locations or services. The key can be stored for example in HashiCorp Vault and the password storage file somewhere else. The password storage file should be backed up regularly when new password entries are stored. 3-2-1 backup rule can be useful here. The symmetric key’s password should be safely stored as well. Do not lose or forget it or you cannot access your passwords anymore!

Rotating the key

It may be useful to rotate the symmetric key once in a while to mitigate the impact if someone has managed to get the key or the password storage. In hakjpass, this means that we generate a new symmetric key and encrypt the password storage file with it. The old key is needed to decrypt the file first. After this has been done, the old key’s backups can be safely deleted. The old password storage file should be deleted as well if it is backed up somewhere and be replaced with the new one. The tool has commands to generate new keys and rotate them.

Summary

This tool is designed for techincal people. I think it can be useful for the people who know how to use it and who like to use this kind of tools. The tool is designed to be secure by default. However, it is the user’s responsibility to back up the data and keep it safe.

Check the source code, documentation and how to install or build from source here.

Thank you for reading. Have a nice day and remember to keep your passwords safe!