+++
title = "Concepts"
date = 2026-11-05T00:00:00Z
description = "The three things HardenedPass is built on, in plain words: pass stores passwords as files, OpenPGP encrypts them, git syncs them."
weight = 10
draft = false
+++

HardenedPass is built on three tools. You do not need to master any of them, but
knowing what each one does makes the rest of these pages easy to follow.

## pass: one file per password

[pass](https://www.passwordstore.org/) is a password manager for Unix systems. It has
no database. Each password is a small encrypted file, and folders group them. That
folder tree is called the **store**.

```
store/
├── .gpg-id
├── example.org.gpg
├── otp/
│   └── example.com.gpg
└── work/
    └── mail.example.org.gpg
```

Once decrypted, an entry is plain text. The first line is the password, and anything
below it is extra information:

```
hunter2
username: alice
url: https://example.org
```

HardenedPass reads those lines and shows them as separate fields. Any program that
understands `pass` can open the same store, so your passwords are never locked into
this app.

## OpenPGP: the lock on each file

Every entry is encrypted with [OpenPGP](https://www.gnupg.org/), using a **key pair**:

- The **public key** locks files. It is not secret.
- The **private key** unlocks them. It never leaves your devices.
- The **passphrase** protects the private key, so a copy of the key file alone is
  useless to whoever finds it.

The `.gpg-id` file at the top of the store says which keys entries are encrypted for.

{{< callout type="danger" title="Back up your private key" >}}
If you lose the private key or forget its passphrase, nobody can decrypt your store.
There is no reset. Keep a copy somewhere safe and offline.
{{< /callout >}}

## git: sync and history

[Git](https://git-scm.com/) tracks every change to the store and copies it between
devices through a **remote**, a repository on a server. You change an entry on the
phone, the app records the change and sends it to the remote, and your other devices
fetch it from there. Old versions stay in the history, so a mistake can be undone.

The server only holds encrypted files, but it can read their **names**. Whoever runs
it can see that you have an entry called `example.org`. Use a private repository, on a
server you trust.

## How it fits together

1. On a computer you make a key pair, a store and a remote.
2. On the phone, HardenedPass clones the store from the remote.
3. You import the private key into the app.
4. The app decrypts entries when you open them, and syncs changes through git.