img2key

Have you ever wanted your memes to ALSO be your password? No? shit... Well, anyway, I made a thingy that does that!

Warning

If you are on pre-2.0.0x, all passwords can no longer be regenerated, and i will not provide support for pre 2.0.0x versions of img2key.

If you see x at the end of a version, like v2.0.0x, that means a breaking change was made to the algorithm that changed how passwords are generated.

Once upgrading to v2.0.0x or later, you can use `--algo-ver / -av`` to continue using the previous algorithm

How Do I Use This?

Quickstart

1. install from either the Releases Tab, or use the provided flake.nix if you're on NixOS with flakes enabled.
2. find an image you want to use as a password
3. img2key <path/to/file.png> [options]

By default, no data is written to disk. The generated password is always written into stdout so you can pipe into something like wl-copy.

Tip

If you already have age encryption set up, you can use the following commands to get that integrated before we continue. If you want to use encrypt, you will need to install age

Obtaining a key-pair img2key getkey <path> [name]

Registering a public key img2key setkey [<path> | <age1...>]

Standard Usage

img2key <path/to/file.png> --salt "phrase" | wl-copy

this pipes your generated password into your clipboard

Post Update

Lets say i just updated img2key to v2.1.5x. That means i have changed the algorithm. If you try and generate an old password, it will not work. img2key <path/to/file.png> --salt "phrase" -av v1 | wl-copy

this uses the v1 algorithm (v2.0.0x) instead of the latest version

Integration(s)

img2key <path/to/file.png> --salt "phrase" -bw github | wl-copy

this pushes the generated password to the "github" item in bitwarden, while also piping into clipboard.

Note

This program has optional integration for the following programs:

• bitwarden-cli Invoked with --bitwarden <item> / -bw
• secret-service Invoked with --keyring <item> / -kr
• age-encryption Invoked with img2key <image> encrypt <path> [name]

All require their respective CLI tools to be installed.

Algorithm

• Image bytes are fed into HKDF-SHA512
• The derivation is keyed with a fixed label and parameterized with the user's salt, password length, and an algorithm version
• Output bytes are mapped to characters with rejection sampling for uniformity
• Fisher-Yates shuffle randomizes positions deterministically

Flags and Arguments

Flag	Description	Example
--length / -l <len>	Length of generated password.	--length 12
--salt / -s <string>	Add user specified strings to the image bit data	--salt "phrase"
--bitwarden / -bw <item>	Pipe output to bitwarden-cli	--bitwarden github
--keyring / -kr <item>	Pipe output to secret-service	--keyring github
--algo-ver / -av <ver>	Allows you to roll the algorithm back to a previous version on update	--algo-ver v1
--version / -v	Show img2key version (not algorithm) and exit	--version

Argument	Description	Position/Example
setkey [<file> ,or, "age1..."]	Set the public key for img2key	img2key setkey /path/to/public/key.txt
getkey <path> [name]	Generate an age keypair	img2key getkey ~/secrets img2key-helios
encrypt <path> [name]	Pipe output into age before writing to disk	img2key image.png encrypt ~/secrets github

How Do I Install This?

Nix Flakes

Adding this to your flake.nix

# flake.nix
inputs = {
  img2key = {
    url = "github:khitboksy/img2key";
    inputs.nixpkgs.follows = "nixpkgs";
  };
};

will expose

inputs.img2key.packages.<system>.default

that you can invoke anywhere.

Run with: img2key <image> [options]

Non-Nix Linux/MacOS

Navigate to Releases/v*/

Linux/MacOS

download the archive for linux/mac, img2key-Linux.tar.gz or img2key-macOS.tar.gz.
navigate to the downloaded archive and run

# Linux
tar xzf img2key-Linux.tar.gz          # Extract the `img2key` binary
sudo install img2key /usr/local/bin/  # Put `img2key` in $PATH and ensure executability

# MacOS
tar xzf img2key-macOS.tar.gz
sudo install img2key /usr/local/bin/

Run with: img2key <image> [options]

Windows

download the archive for windows, img2key-Windows.zip.
navigate to the downloaded file, extract it.
Run with: ./img2key.exe <image> [options] from the extracted file location.

How do I contribute?

This project is written in typescript, using bun for development. This program is fully portable under just node. bun is NOT required.

Tip

Nix users can use the provided flake.nix to skip straight to here!

Pick your runtime:

Runtime	Install
Bun	bun.sh/docs/installation
Node	nodejs.org or your package manager

How do I actually do dev work?

Installing node deps, and running the dev script:

# Bun
bun install
bun run img2key

# Node
npm install
npm run img2key

Bumping the version number so the workflow triggers:

# Bun
bun run bump v2.x.x

# Node
npm run bump v2.x.x

git push origin main && git push origin --tags