Skip to content
Merged
9 changes: 9 additions & 0 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
repos:
- repo: local
hooks:
- id: cargo-fmt
name: cargo fmt --check
entry: cargo fmt --check
language: system
types: [rust]
pass_filenames: false
70 changes: 59 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,9 @@ and encrypts them with ChaCha20-Poly1305 before Git stores them.

Keys are stored locally under `.git/git-zcrypt/`. Raw 32-byte keys can be
generated or imported directly, and password-derived keys can be created with
Argon2id. Encrypted blobs store a hash-prefixed key id such as `sha256:...`;
local aliases map to those ids through `.git/git-zcrypt/index.json`.
Argon2id. Encrypted blobs store a hash-prefixed key id such as `sha256:...`.
Committed `git-zcrypt-keys.json` manifests map those key ids to local aliases
without storing raw key material.

## Install

Expand Down Expand Up @@ -59,7 +60,8 @@ a8a3cfd8a3833578e4d66ca0acc596fc0aa90df5656d354b3cf91fbd740d4f6c -
```

After `derive-key`, the key lives under `.git/git-zcrypt/keys/` in the versioned
local key format, and the key id is recorded in `.git/git-zcrypt/index.json`:
local key format. The key id is recorded in a committed manifest when filtered
content is cleaned:

```console
$ hexdump -C .git/git-zcrypt/keys/test.key
Expand All @@ -68,12 +70,46 @@ $ hexdump -C .git/git-zcrypt/keys/test.key
00000020 44 69 a4 62 0b fc 83 90 9e 0c f4 83 |Di.b........|
$ tail -c 32 .git/git-zcrypt/keys/test.key | shasum -a 256
a8a3cfd8a3833578e4d66ca0acc596fc0aa90df5656d354b3cf91fbd740d4f6c -
$ cat .git/git-zcrypt/index.json
$ cat git-zcrypt-keys.json
{
"sha256:a8a3cfd8a3833578e4d66ca0acc596fc0aa90df5656d354b3cf91fbd740d4f6c": "test"
}
```

Create a root manifest explicitly when setting up a repository, or let the first
clean create it automatically at the repository root:

```sh
git-zcrypt init-manifest
```

To create a narrower manifest boundary for a subdirectory, initialize one there:

```sh
git-zcrypt init-manifest --path secrets/team-a
```

To migrate existing encrypted worktree files into a manifest, run `register`
with one or more paths relative to your current directory. By default it creates
or updates `git-zcrypt-keys.json` in the current directory:

```sh
cd secrets
git-zcrypt register team-a/secret.txt team-b/secret.txt
```

Use `--manifest-dir <dir>` to select another manifest directory relative to the
current directory:

```sh
git-zcrypt register --manifest-dir .. secret.txt
```

`register` reads encrypted blob metadata, adds a manifest entry only when the
matching local key is available, and never rewrites the encrypted files. If a
matching local key is missing, it creates the selected manifest file and warns
without adding an entry.

Install the local Git filter config:

```sh
Expand Down Expand Up @@ -112,11 +148,11 @@ original bytes:
```console
$ </dev/zero head -c 500000 | wc
0 1 500000
$ </dev/zero head -c 500000 | git-zcrypt clean --key test | wc
$ </dev/zero head -c 500000 | git-zcrypt clean --key test --path secrets/zero.bin | wc
2 14 617
$ </dev/zero head -c 500000 | sha384sum
478a159989441dac6279a2dd45b32a62ecc42f3ffccc976a1652da63e3e7ca4708d43b0f28fd147c5b4072f938cab913 -
$ </dev/zero head -c 500000 | git-zcrypt clean --key test | git-zcrypt smudge | sha384sum
$ </dev/zero head -c 500000 | git-zcrypt clean --key test --path secrets/zero.bin | git-zcrypt smudge --path secrets/zero.bin | sha384sum
478a159989441dac6279a2dd45b32a62ecc42f3ffccc976a1652da63e3e7ca4708d43b0f28fd147c5b4072f938cab913 -
```

Expand All @@ -140,15 +176,27 @@ Delete a local key when it should no longer be available in this clone:
git-zcrypt delete-key --key default
```

Key files and `index.json` are not committed by `git-zcrypt`; they live under
Key files are not committed by `git-zcrypt`; they live under
`.git/git-zcrypt/`. Stored key files are versioned, while exported keys are raw
32-byte keys. Password-derived keys do not store KDF metadata; the fixed
Argon2id parameters make the same password produce the same key id. Back keys up
and transfer them securely. Losing or deleting the only copy of a key makes
encrypted blobs that use it unrecoverable.
Argon2id parameters make the same password produce the same key id.

`git-zcrypt-keys.json` is committed and contains only key ids and local alias
names. Smudge uses the nearest manifest found by walking from the filtered file's
directory upward to the repository root. If a clone has the manifest but lacks
the matching local key, smudge leaves the encrypted blob bytes in the worktree
and exits successfully with a warning so clone and checkout can finish. After
importing or deriving the missing key, re-smudge a file with:

```sh
git restore --source=HEAD --worktree -- secrets/secret.txt
```

Back keys up and transfer them securely. Losing or deleting the only copy of a
key makes encrypted blobs that use it unrecoverable.

See [docs/data-formats.md](docs/data-formats.md) for the committed encrypted
blob format and local key/index formats.
blob format, committed manifest format, and local key format.

## Safety Notes

Expand Down
45 changes: 28 additions & 17 deletions docs/data-formats.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# Data Formats

`git-zcrypt` handles two persistent data structures: committed encrypted blobs
and local repository keys. Encrypted blobs are part of Git history. Local keys
and the key index live under `.git/git-zcrypt/` and are not committed by
`git-zcrypt`.
`git-zcrypt` handles three persistent data structures: committed encrypted
blobs, committed key manifests, and local repository keys. Encrypted blobs and
`git-zcrypt-keys.json` manifests are part of Git history. Local keys live under
`.git/git-zcrypt/` and are not committed by `git-zcrypt`.

## Encrypted Blob Format

Expand Down Expand Up @@ -33,6 +33,30 @@ Key ids are currently `sha256:` followed by 64 lowercase hex characters. The
hash is SHA-256 over the raw 32-byte key material, not over a key alias or file
name.

## Committed Key Manifest Format

`git-zcrypt-keys.json` is a constrained JSON object mapping hash-prefixed key ids
to key names:

```json
{
"sha256:<64 lowercase hex chars>": "<key-name>"
}
```

The file contains no raw key material and is safe to commit. Entries are written
in lexicographic key-id order. Duplicate JSON keys are rejected by the parser as
far as they can be observed, and both key ids and key names are validated when a
manifest is read. Key names may contain only ASCII letters, digits, `_`, and
`-`.

For a filtered path, `git-zcrypt` uses the nearest `git-zcrypt-keys.json` found
by walking from the file's directory upward toward the repository root. A root
manifest can be created with `git-zcrypt init-manifest`; subdirectory manifests
can be created with `git-zcrypt init-manifest --path <dir>`. Existing encrypted
blobs carry the key-id metadata needed for `git-zcrypt register <file>...` to
populate the selected manifest when the matching local key alias is available.

## Local Key File Format

Each local key file is a versioned binary wrapper around raw key material:
Expand All @@ -52,16 +76,3 @@ imported, and password-derived keys all persist in this same versioned format.
Password-derived keys do not persist Argon2id parameters, salt, or other KDF
metadata. `export-key` writes only the raw 32-byte key payload for backup or
transfer.

The local key index maps committed blob key ids back to local aliases:

```json
{
"sha256:<64 lowercase hex chars>": "<key-name>"
}
```

The index file is `.git/git-zcrypt/index.json`. It is a constrained JSON object
whose keys are hash-prefixed key ids and whose values are key names. Entries are
written in lexicographic key order, duplicate JSON keys are rejected, and both
key ids and key names are validated when the index is read.
Loading
Loading