password-manager

Cross platform offline gui and tui password manager. Crypto stuff done with pycryptodome. GUI done with pyside6. TUI done with textualize.

Warning

This is a personal project that intends to manage sensitive data. Just because its open source it doesn't mean its safe. Read trough the source code and build from source. I will provide binaries, these binaries will only ever be found in this repo.

Goal

I was using Bitwarden for some time, but my anxiety came over me and i made my own password manager. Bitwarden might be open source, but its a lot of code to read trough. Even if you read trough all of it, whos to say that they dont run a backdoored fork?

Features

Its very limited in its nature to keep the codebase as compact as possible in case you want to fully read trough it. However it does have some nice features:

• Cross Platform (linux, windows, mac)
• GUI and CLI
• Generate random passwords
• what can it store?:
  • name (website, service, etc...)
  • username
  • email
  • password
  • extra info (like a notes field)
  • creation date
  • last edit date
  • uuid (internal putposes only)

Usage

The simplest way is to just download the binaries. However downloading and running binaries is always risky, i encourage to clone/fork the repo and build from source:

Prerequisites:

• astral uv

Just run without making binaries

• clone repo:

  git clone https://github.com/p1geondove/password-manager

• cd into repo:

  cd password-manager

• create venv and add packages:

  uv sync

• run the software:

  uv run main.py

Build binaries from source

1. clone repo:

   git clone https://github.com/p1geondove/password-manager

2. cd into repo:

   cd password-manager

3. create venv and add packages:

   uv sync

4. make binary:
   • Linux:

     ./build.sh

   • Windows:
     1. read through this
     2. open PowerShell as admin
     3. run:

        Set-ExecutionPolicy unrestricted

     4. return to the shell with the password-manager
     5. run:

        ./build.ps1

Technical details

File layout

General encrypted file

Every file has 5 segments that can be split up like this:

• Bytes 0-32: salt
• Bytes 32-48: nonce
• Bytes 48-64: mac tag for verification
• Byte 64: content type -> 0=bytes 1=string 2=json
• Bytes 65-: ciphertext

Password manager file

A password data containing file is in essence just json. The python type actually used is a dict[UUID, PWField]. A UUID in this case is just a python builtin uuid.uuid4() like e18d1093-fcdb-468b-9e5a-6b4a4b9aff22 for example. A PWField is a dataclass containting the uuid again as well as username, email, password, extra info, creation date and last edit date. The uuids are internally used as UUID types, but get saved as string, in python parsing uuids like this is as simple as using uuid.UUID(xyz) while converting to string is done via str(xyz). Times are format %Y-%m-%d %H:%M:%S.%f which should be normal iso format, ex: 2026-06-18 23:31:29.104373, to parse the you can use datetime.fromisoformat(xyz), string conversion is done via str(xyz).

en-/decryption

Click to expand

The files get encrypted using AES, 256 bits. All of the crypto stuff is done via pycryptodome. For that a key is derived from a password and a random 256 bit salt using PBKDF2 using 1 million iterations on SHA512. 1 million iterations of SHA512 somewhat time consuming, but thats a good thing since it makes brute force extremely time consuming. Ill test the speed of that on a very low power machine as well, but as long as the login takes less then a second i think its fine and doesnt break user experience. This is only really done once tho, since after that the key and salt are stored in ram. This has the benefit of instantly updating changes to the password file while also preventing malicious actors to steal your actual password. (Altho i guess if someone has that level of access to your machine they could just install a keylogger) This program also creates a pepper that is locally saved, where exactly is dependant on the operating system. The pepper file itself is not encrypted and can technically be easily read and stolen by malicious actors. However it does add another layer of security to the whole project. The pepper is important for accessing your password file, if you loose it you wont be able to recover your passwords or encrypted files There are multiple abstraction layers in crypt.py, such as basic methods for en-/decryption, file interfacing and password-file interface.

AI

Of course i use AI to help me out. That does not mean that this is vibe-coded. Since im using this as my daily (well techincally monthly, since cookies and so forth) driver i want this to be as secure as possible. My stance on LLMs is not all to controversial i think, but i know what they can and cant do. There is not a single line of code in this project that has been vibe-coded or copy pasted from any LLM. So how do i use LLMs then? They are useful for telling me about what libraries there are, for example in this project a LLM told me about the existance of the external appdirs library. LLMs are helpful for formatting .md files, they helped me find out about the existence of the > Warning block that you see at the top. Also im not all too familiar with textualize, so LLMs really can help out on the frontend