Introduction

Keywich Icon



Keywich is a password generator application built with Rust, SvelteKit, Skeleton UI and Tauri. The app does not store generated passwords. Instead, it combines parameters such as the username, domain, and master password with a bit of salt and a hashing algorithm to create reproducible passwords with the specified length and character sets.


application screen views

Installation

See GitHub release page for the all available binaries.

Linux x86_64 (.deb)

  1. Download .deb package from GitHub release page.

  2. Use dpkg to install the package.

dpkg -i keywich_0.1.0_amd64.deb

Linux x86_64 (pkgbuild)

PKGBUILD is created but not added to AUR yet.

  1. Download PKGBUILD file from GitHub release page.

  2. Use makepkg tool to install the package.

makepkg --install

Windows x86_64

Download .msi installer package and execute it.

From source

Requirements:

git clone https://github.com/SuperioOne/keywich.git
cd keywich
pnpm install -r
pnpm run build:desktop

# build output dir
cd ./tauri_app/target/release

How to Use

In this section you will learn;

Setup Profile

Profile database is not initialized when you start the application first time. It asks for your Master Password which is used for generating your passwords and creating an encryption key for the profile database.

If there is already an existing profile database in the application local data, the application will only ask for master password for unlocking the database.

It is important to ensure that your master password is long, random and unique to enhance the security of your generated passwords and profile database

Initialization screen view

Charsets

The actual generated password is a fixed-size binary blob based on target length 1, which is then converted to text within a given character range by charset. This is useful when a site or application does not allow certain characters.

By default, three character sets are created:

  • Numeric 0..9
  • Alpha Numeric a..zA..Z0..9
  • Alpha a..zA..Z

Charset pattern rules

  1. The order of range and characters do not matter. For example, _-!a..zA..Z and A..Z_-a..z! will produce the same charset.
  2. Duplicate values and ranges are ignored. For instance, __A..Z__A..Z__A..Z__ is parsed as A..Z_
  3. The left-hand side of a range should be smaller than the right-hand side. Ranges such as k..a and 9..1 are not accepted.
  4. Ranges are case-sensitive. Avoid mixing cases like A..z.

Example charset pattern with complex symbols:

A..Za..z0..9#-_'`"><)(%.,!$€£*+~:;{}[]&

Example charset pattern with German alphabet:

A..Za..z0..9ÄäÖöẞßÜü

Managing charsets

  1. Open Settings > Charsets and click the Create button to create a new charset.
  2. Enter a unique charset name.
  3. Enter the charset pattern.
  4. (Optional) Add a description for the charset.
  5. Confirm.
  6. New charset will be available when modifying or creating keys.

Deleting a charset and creating a different one with the identical name does not affect existing keys. They will continue using the prior one to prevent any unintended password changes.

Syntax definition

ALPHA_LC = ASCII lowercase characters
ALPHA_UC = ASCII uppercase characters
NUMERIC = ASCII Digits
UTF8 = Any valid UTF8 character
range = (ALPHA_LC ".." ALPHA_LC) / (ALPHA_UP ".." ALPHA_UP) / (NUMERIC ".." NUMERIC)
content = range / UTF8
charset = 1*content

1

Target length is a key parameter.

Managing Keys

At the Keys page, you can create and pin your keys or delete the existing keys.

Creating a key

  1. Open Keys page and click the Create button.
  2. Enter domain for the key which can be a non-URL text like my_server.
  3. Enter the username for the key.
  4. Select a charset. If you need a different charset see charsets.
  5. Choose a password length between 1 and 64.
  6. (Optional) Add tags for filtering.
  7. (Optional) Add notes about the key.
  8. (Optional) Set a custom revision no.
  9. (Optional) Set an icon for key. Supported formats are jpeg and png.
  10. Click to Confirm button.

Quick and Advanced Copy

Generate and copy your password to the clipboard via left-clicking the copy button on the keys page, or right-clicking the copy button to open Advanced Copy menu for additional options like base64 encoding, URI encoded, QR Code and clear text.

Advanced copy menu view

Pinning a key

Pin frequently used keys to home page by clicking star icon in the key list.

Updating a key

To update keys, use the pen icon on the keys page. The Update procedure is identical to creating a new key.

Changing any of the following parameters: username, domain, revision no, charset or target length will change the output password. Only change these values if your intention is to update the password.

You can always generate your old password by using your previous parameters.

Deleting a key

To delete a key, simply left-click delete button and confirm on the keys page.

Key Parameters

Domain

The service name. The domain is used for generating password and is case-insensitive.

Username

Identification for who is accessing the service. The username is used for generating password and is case-sensitive.

Revision no

Password seed number. Changing this value will result in a new password being generated.

If you ever need to update your password for same username, simply increment or change this value.

Target length

The desired password length. Currently supports maximum 64 characters. Changing this value will result in a new password being generated.

Charset

Defines the range of characters used in generating the output password. For more information, see the charsets page.

Tags

Used for filtering keys.

Notes

Additional descriptive text for the key.

Icon

An icon representing the key that will be displayed in the Pinned Keys and Key List.

Settings

You can change the application theme and language via Settings page.

Currently, there are 11 color theme mainly from SkeletonUI and 2 language option (EN, TR).

All configurations are stored in config.json, located at:

  • /home/${USER}/.local/share/com.superiorone.keywich/config.json for Linux.
  • C:\Users\${USER}\AppData\Local\com.superiorone.keywich\config.json for Windows.

Here's an example of a config.json file:

{
  "color_theme": "default",
  "locale": "en",
  "is_light_theme": false
}

app themes

Example themes

Shortcuts

General:

  • Ctrl + 1 : Open home page.
  • Ctrl + 2 : Open keys list.
  • Ctrl + 3 : Open settings.
  • Ctrl + L : Lock/Logout.
  • Ctrl + I : Log panel.

Keys page:

  • Ctrl + S : Open/Close key filter.
  • Ctrl + N : Create new key.

Current version does not have configurable shortcuts.

Backup/Restore

The application's profile database can be exported into a backup file, which contains the following:

  • Keys
  • Charsets
  • Custom key icons

Backing Up Your Keys

  1. Open Settings > Backup/Restore menu.
  2. Click on the Backup button and save the file.

Restoring Your Keys

Please note that restoring from a backup will OVERRIDE all of your profile database. Due to the possibility of a gap between the time of the backup and the restore, any modifications made after the backup file was created may be lost. Therefore, it's best practice to create a backup before performing a restore operation.

For restoring from a backup:

  1. Open Settings > Backup/Restore menu.
  2. Click on the Restore button.
  3. Select your backup (.kb) file and confirm the restore.

All backup files are signed with your master password. If your current master password does not match the backup's signature, the application will display a warning. You can still restore from a backup with a different signature, but the generated passwords will not be the same as the backup source.

Changelogs

v0.3.0

April 05, 2024

Added

  • Profile database backup and restore support.
  • Visible log panel button at the footer section. In previous versions, It was only accessible with Ctrl + I shortcut.
  • Version information at the footer section.

Changed

  • --log_level flag name changed to --verbose. App can now be started as keywich --verbose debug.

Fixes

  • Profile databases cannot be initialized with certain master passwords.

Deleted

  • CLI password generator sub-command deleted.

v0.2.0

March 14, 2024

Added

  • Persisted log files and stdout logging.
  • GUI can now be started with different log levels (default is WARN) via keywich gui --log-level <LOG_LEVEL>.

Fixes

  • BREAKING Some master passwords generate invalid database encryption keys. All app databases will be automatically upgraded to the new passphrase generator. Note that downgrade will not possible after the upgrade.
  • A zero-byte app.db file no longer breaks profile initialization.

Known issues

  • On Windows, the console is detached from GUI window, making the CLI unusable.
  • On Linux, webkit2gtk >= 2.42.x when used with Nvidia proprietary drivers, may display an empty window with the error message KMS: DRM_IOCTL_MODE_CREATE_DUMB failed: Permission denied. Current known solutions are:
    • Set WEBKIT_DISABLE_DMABUF_RENDERER=1 environment variable.
    • Enable nvidia.drm_modeset=1 kernel parameters.