From 0e32920531b54d64a073864f1070f30343ed5690 Mon Sep 17 00:00:00 2001 From: Anton Date: Fri, 19 Apr 2024 20:27:43 +0200 Subject: [PATCH] Re-write wiki pages Changes include: - Re-styled headings - Simplified usage page - Removed `update` heading from Getting-Started - Correct Mac OS -> macOS - Update Configuring to the changes made in: fb23f93 --- .github/WIKI/BashPass-Remote.md | 2 +- .github/WIKI/Configuring.md | 98 +++++++------------- .github/WIKI/Getting-Started.md | 159 ++++++++++---------------------- .github/WIKI/Home.md | 2 +- .github/WIKI/Usage.md | 136 +++++++++++---------------- 5 files changed, 140 insertions(+), 257 deletions(-) diff --git a/.github/WIKI/BashPass-Remote.md b/.github/WIKI/BashPass-Remote.md index a0faece..3b2a58e 100644 --- a/.github/WIKI/BashPass-Remote.md +++ b/.github/WIKI/BashPass-Remote.md @@ -2,5 +2,5 @@ For those who want to host their passwords on a remote server, such as a NAS, yo Please note that this project is still in development. BashPass-Remote allows you to use BashPass as if it were installed on your machine while storing the passwords on a remote server. The tool is essentially a simple wrapper around SSH and BashPass, which enables you to securely connect to your remote server and use BashPass as if it were installed locally. -Like BashPass, BashPass-Remote is written in (pure) Bash and is compatible with most Linux distributions, BSDs, and Mac OS X (with Bash installed). +Like BashPass, BashPass-Remote is written in (pure) Bash and is compatible with most Linux distributions, BSDs, and macOS X (with Bash installed). For further details, please refer to the BashPass-Remote [documentation](https://github.com/AntonVanAssche/BashPass-Remote/wiki) diff --git a/.github/WIKI/Configuring.md b/.github/WIKI/Configuring.md index 4f20286..5173fe3 100644 --- a/.github/WIKI/Configuring.md +++ b/.github/WIKI/Configuring.md @@ -1,97 +1,69 @@ -The BashPass configuration file can be found at `~/.config/bashpass/bashpass.conf`. -In this file, you can make several changes such as the email address, default location where passwords are stored, and other settings. -The default configuration file is shown below. +This page provides instructions on how to configure BashPass using its configuration file. -``` -location: .local/share/bashpass -timer: 10 -length: 14 -``` - -## Configuring the Location where Passwords are Stored +# 1. Configuration File -By default, BashPass stores passwords in the directory `~/.local/share/bashpass/`. -If you want to change the location, you need to modify the following line in the config file: +By default, BashPass will look for a configuration file in `~/.config/bashpass/bashpass.conf`. +If the file is not found, BashPass will use the default settings. ``` location: .local/share/bashpass +timer: 10 +length: 14 ``` -**Example**: To store passwords in `.bashpass/passwords/`, update the line to: - -**Note**: The new location must be within **your home** (`~`) directory. - -``` -location: .bashpass/passwords/ -``` - -## Configuring the Email Address +# 2. Configuring BashPass -It is not recommended to change the email address. -However, if you need to, update the following line in the config file: +You can configure BashPass by editing the configuration file. +The configuration file is a simple text file that contains the following settings: -``` -email: email@gmail.com -``` +## 2.1. GnuPG Key ID -**Example**: To update the email address to `newemail@gmail.com`, update the line to: +Upon first use, BashPass will ask you to provide your GnuPG key ID and will store it in the configuration file. +In order to make BashPass work, you need to provide your GnuPG key ID. +This can be done by adding an entry to the configuration, using `keyID` as the key and your GnuPG key ID as the value. +The key ID of a GnuPG key is the last 8 characters of the key fingerprint. -**Note**: After updating the email address, you need to generate a new GPG key. -You will also be unable to read your passwords that were stored with the old email address. +For example, using `12345678` as the ID will look like this: ``` -email: newemail@gmail.com +keyID: 12345678 ``` -## Configuring the Clipboard Timer +## 2.2 Password Length -By default, the timer for copying passwords is set to `10` seconds. -This timer is the duration you have to paste the password that you copied using the `copy` option. -You can modify the duration of the timer in the config file by editing the following line: +BashPass allows you to set a default password length, which it will use when generating passwords. +Out of the box, BashPass will generate passwords with a length of `14` characters. +Once set, you can still override this value when generating passwords. -``` -timer: 10 -``` - -**Example**: To update the timer to `15` seconds, update the line to: +For example, to change the default password length to `16`, you can add the following entry to the configuration file: ``` -timer: 15 +length: 16 ``` +## 2.3 Password Store Location -## Configuring the Default Password Length +BashPass will store all password files in a specified location, also known as the password store. +This location must be present in your home directory (`~`). +By default, the password store is located in `~/.local/share/bashpass`. -The default length for all randomly generated passwords is `14` characters if no specific length is given when prompted (since version: `2.0`). -You can change this length to as many characters as you want by editing the following line in the config file: - -``` -length: 14 -``` +For example, to change the passowrd store location to `~/.passwords`, you can add the following entry to the configuration file: -**Example**: To update the default password length to `25` characters, update the line to: +**Note**: The password store location may not include the `~` character. As its added by BashPass. ``` -length: 25 +location: .passwords ``` +## 2.4 Timer -## Configuring the Git Repository URL +When using the `-c` or `--copy` option, BashPass will clear the clipboard after a specified amount of time. +This time is specified in seconds, and defaults to `10` seconds. +However, adding an `timer` entry to the configuration file will allow you to change the default value. -If you want to use the `synchronize` functionality, you need to configure a URL that BashPass will use to push to the remote Git repository. -You can configure this by adding the following line to your config file: +For example, to change the default timer to `5` seconds, you can add the following entry to the configuration file: ``` -gitRepo: +timer: 5 ``` - - -**Example**: To use `AntonVanAssche/BashPass` as the remote repository, update the line to: - -``` -gitRepo: git@github.com:AntonVanAssche/BashPass.git -``` - - -**Note**: It is recommended to use the `SSH` option as shown above. diff --git a/.github/WIKI/Getting-Started.md b/.github/WIKI/Getting-Started.md index 4721289..29393e8 100644 --- a/.github/WIKI/Getting-Started.md +++ b/.github/WIKI/Getting-Started.md @@ -1,4 +1,8 @@ -## Dependencies +This page provides instructions on how to get started with BashPass. +It covers the installation, updating, and uninstalling of BashPass. +As well as the prerequisites and dependencies required to run BashPass. + +# 1. Dependencies - `bash >= 3.0` @@ -19,19 +23,17 @@ - `git` -## Installation +# 2. Installation -### Generating your GPG key +## 2.1 Generating your GPG key -Before you install BashPass, you'll have to generate a GPG key. -Run the following command in your terminal to start key generation process: +Before you install BashPass, you'll have to generate a GPG key: ```console $ gpg --full-generate-key ``` -Once you run this command, you'll be asked to select a encryption protocol. -Select the first option (`RSA`). +Select the first option (`RSA`): ``` Please select what kind of key you want: @@ -45,8 +47,7 @@ Please select what kind of key you want: Your selection? 1 ``` -Now you'll be prompted to choose a keysize. -The default option (`3072`) is fine, for a stronger key select `4096`. +Enter the keysize, the default option (`3072`) is fine, for a stronger key select `4096`: ``` RSA keys may be between 1024 and 4096 bits long. @@ -54,8 +55,7 @@ What keysize do you want? (3072) Requested keysize is 3072 bits ``` -After selecting the keysize, you'll be asked how long you want the key to be valid. -The default option 1 (`key does not expire`) is fine. +Enter time to expire, the default option (`0`) is fine: ``` Please specify how long the key should be valid. @@ -69,28 +69,25 @@ Key does not expire at all Is this correct? (y/N) y ``` -Now it's time to set a name for the key. -This can be anything (example: `BashPass`). +Choose a name for the key, this can be anything you like: ``` Real name: Bashpass ``` -Once you've set a name for the key, it's time to set the email address, this is **IMPORTANT** to remember, you'll need this later to configure BashPass. +Enter the email address you want to use: ``` Email address: example@gmail.com ``` -The final step to generate your GPG key is to set a comment, this isn't needed but can be useful in case you have more than one GPG key on your computer. -After this just confirm the settings and you're done. +Finally, enter a comment, this can be anything you like, empty is fine: ``` Comment: BashPass encryption key ``` -Now your key will be generated. -Once this is done you'll see something like this: +Once all the options are set, you should a see a message like this: ``` pub rsa3072 2022-04-22 [SC] @@ -99,25 +96,10 @@ uid [ultimate] Bashpass (Key to use BashPass) sub rsa3072 2022-04-22 [E] ``` -Note you can see the key fingerprint (`86F27E3CAA49BB273653B39763BBB2BD91082EE1`), this string contains the key ID. -This are the last 8 characters ( `91082EE1`) of the fingerprint. -This part is **IMPORTANT** to remember, you'll need this later to configure BashPass (see: [Post installation](#post-installation)). - -### Installation by using the one-liners - -As of BashPass 3.1, the one-liners provided in the `scripts/` directory can no longer be used to install BashPass, due to the removal of the `install.sh`, `update.sh`, and `uninstall.sh` scripts. -Instead, BashPass now uses two Makefiles (`GNUmakefile` and `BSDmakefile`) for installation, updating, and uninstalling, reducing the codebase and making BashPass more maintainable. -This change makes it easier to maintain the code and reduces unnecessary scripts. - -The `GNUmakefile` and `BSDmakefile` are two different makefiles used by different operating systems. -The `GNUmakefile` is used by most Linux distributions, including Debian and Fedora, as well as macOS, while the `BSDmakefile` is used by BSD-based operating systems like FreeBSD and OpenBSD. - -The reason for having two makefiles is that the syntax and features of the `make` command can vary between these operating systems. -By providing two different makefiles, BashPass can be installed on a wide variety of systems without requiring the user to modify the makefile for their specific platform. +Within the output, you will find the key fingerprint, in this case `86F27E3CAA49BB273653B39763BBB2BD91082EE1`. +From this fingerprint, you can extract the key ID, in this case `91082EE1`, which we will use later. -Therefore, if you want to install BashPass, please see the [Installation by downloading the tarball/zip (recommended)](#install-by-the-tarballzip-recommended) section. - -### Installation By downloading the tarball/zip (recommended) +## 2.2 Installation By downloading the tarball/zip (recommended) If you prefer to download the provided tarball or zip, you can download them from the [release page](https://github.com/AntonVanAssche/BashPass/releases/latest/) of the GitHub repository. This is the recommended way to install BashPass, since it allows you to verify the authenticity of the tarball. @@ -178,117 +160,70 @@ Once the tarball is extracted, it is time to install BashPass, by using the `mak ```console $ cd BashPass-X.X -$ make install -``` - -Alternatively, you can install BashPass by running the following commands: - -**Note**: Lines beginning with `#` must be executed as root, use `sudo` or `doas` depending on your operating system. - -- For Linux and BSD: -```console -$ mkdir -p ~/.config/bashpass/ -$ mkdir -p ~/.local/share/bashpass/ -# cp -r BashPass-X.X/bashpass /usr/bin/bashpass -# cp -r BashPass-X.X/docs/* /usr/share/man/man1/ -$ cp -r BashPass-X.X/config/ ~/.config/bashpass/ -``` +# Linux and macOS +$ sudo make install -- For Mac OS: - -```console -$ mkdir -p ~/.config/bashpass/ -$ mkdir -p ~/.local/share/bashpass/ -# cp -r BashPass-X.X/bashpass /usr/local/bin/bashpass -# cp -r BashPass-X.X/docs/* /usr/local/share/man/man1/ -$ cp -r BashPass-X.X/config/ ~/.config/bashpass/ +# BSD +$ doas make install ``` -### Installation by cloning the repository +## 2.3 Installation by cloning the repository Once you have generated your GPG key, you can proceed to install BashPass. -BashPass can be installed by cloning the repository and running the `make install` command. +BashPass can be installed by cloning the repository and running the `make install` command as a privileged user. **Note**: Replace `X.X` in the commands below with the version number you want to install. ```console $ git clone https://www.github.com/AntonVanAssche/BashPass.git --branch X.X $ cd BashPass-X.X -$ make install -``` - -### Post installation -When you launch BashPass for the first time, you will be asked to enter the key ID and email address associated with the GPG key that you generated (see: [Generating your gpg key](#generating-your-gpg-key)). +# Linux and macOS +$ sudo make install +# BSD +$ doas make install ``` -Enter the key ID of the GPG key you want to use: 91082EE1 -Enter the email address you created the gpg key with: example@gmail.com -``` - -That's it, you can now start using BashPass! -## Updating +## 2.4 Post installation -Updating BashPass to it's latest version is fairly straightforward, this can be achieved by cloning the repository and running the `make update` command. -Alternatively, you can also download the latest release, extract it and run the `make update` command from the extracted directory. +Upon first run, BashPass will ask you to enter the key ID associated with the GPG key you generated (see: [Generating your gpg key](#generating-your-gpg-key)). -**Note**: Replace `X.X` in the commands below with the version number you want to install. - -```console -$ git clone https://www.github.com/AntonVanAssche/BashPass.git --branch X.X -$ cd BashPass-X.X -$ make update ``` - -Alternatively, you can update BashPass by running the following commands: - -**Note**: Lines beginning with `#` must be executed as root, use `sudo` or `doas` depending on your operating system. - -- For Linux and BSD: - -```console -# cp -r BashPass-X.X/bashpass /usr/bin/bashpass -# cp -r BashPass-X.X/docs/* /usr/share/man/man1/ +Enter the key ID associated with your GPG key: 91082EE1 ``` -- For Mac OS: - -```console -# cp -r BashPass-X.X/bashpass /usr/local/bin/bashpass -# cp -r BashPass-X.X/docs/* /usr/local/share/man/man1/ -``` +That's it, you can now start using BashPass! -## Uninstalling +# 3.0 Updating -Uninstalling BashPass is also fairly straightforward, this can be achieved by cloning the repository and running the `make uninstall` command. -Alternatively, you can also download the latest release, extract it and run the `make uninstall` command from the extracted directory. +To update BashPass, you can follow the same steps as the installation process. -Keep in mind that this will remove all configuration files and data associated with BashPass, with the exception of the password store location. +# 4.0 Uninstalling -**Note**: Replace `X.X` in the commands below with the version number you want to install. +Uninstalling BashPass is also fairly straightforward, `make uninstall` can be used to remove BashPass from your system. ```console -$ git clone https://www.github.com/AntonVanAssche/BashPass.git --branch X.X -$ cd BashPass-X.X -$ make uninstall -``` +# Linux and macOS +$ sudo make uninstall -Alternatively, you can uninstall BashPass by running the following commands: +# BSD +$ doas make uninstall +``` -**Note**: Lines beginning with `#` must be executed as root, use `sudo` or `doas` depending on your operating system. +Alternatively, you can uninstall BashPass by running the following commands as a privileged user: - For Linux and BSD: ```console -# rm -rf /usr/bin/bashpass -# rm -rf /usr/share/man/man1/bashpass.{1,conf.1}.gz +$ rm -rf /usr/bin/bashpass +$ rm -rf /usr/share/man/man1/bashpass.{1,conf.1}.gz ``` -- For Mac OS: +- For macOS: ```console -# rm -rf /usr/local/bin/bashpass -# rm -rf /usr/local/share/man/man1/bashpass.{1,conf.1}.gz +$ rm -rf /usr/local/bin/bashpass +$ rm -rf /usr/local/share/man/man1/bashpass.{1,conf.1}.gz ``` diff --git a/.github/WIKI/Home.md b/.github/WIKI/Home.md index c9c60f2..3ab726c 100644 --- a/.github/WIKI/Home.md +++ b/.github/WIKI/Home.md @@ -1,4 +1,4 @@ -## Welcome to the BashPass Wiki +# Welcome to the BashPass Wiki BashPass is a simple command-line tool that helps you manage your passwords securely in a local password store. With BashPass, you don't have to worry about remembering all your different passwords, or writing them down in an insecure manner. diff --git a/.github/WIKI/Usage.md b/.github/WIKI/Usage.md index c37ec78..d384218 100644 --- a/.github/WIKI/Usage.md +++ b/.github/WIKI/Usage.md @@ -1,128 +1,104 @@ -Welcome to the BashPass user guide! -This guide provides an overview of all the features of BashPass, from creating a password to synchronizing your passwords with a remote git repository. +This page provides instructions on how to use BashPass. -## Help option - -If you are not sure about the correct option to use, simply run bashpass with the `--help` or `-h` option. This will display all the features of BashPass. - -**Note**: the `[name]` is optional. +# 1. Basic Command Structure ``` -bashpass [option] [name] - Basic command structure. +Usage: bashpass [OPTION] [NAME | SYNC_COMMAND] Options: ---help or -h - Show this help message. ---version or -v - Show the version number ---list or -l - List all password. ---add or -a [name] - Add a password. ---update or -u [name] - Update a password. ---delete or -d [name] - Delete a password. ---show or -s [name] - Show a password. ---copy or -c [name] - Copy a password to the clipboard. ---sync or -S [synchronize command] - Synchronize password(s) with a git repository. - -Synchronize command: - upload - Upload local password(s) to a remote repository. - download - Download password(s) from a remote repository. + --help | -h Show this help message. + --version | -v Show the version number. + --add | -a [NAME] Add a password. + --copy | -c [NAME] Copy a password to the clipboard. + --delete | -d [NAME] Delete a password. + --show | -s [NAME] Show a password. + --update | -u [NAME] Update a password. + --list | -l List all passwords. + --sync | -S [SYNC_COMMAND] Synchronize password(s) with a git repository. + +Synchronize commands: + upload Upload local password(s) to a remote repository. + download Download password(s) from a remote repository. + +Note: + [NAME] is an optional argument. If not provided, the script will prompt you to enter it. ``` -Examples: - -- `bashpass --add gmail` -- `bashpass --delete gmail` -- `bashpass --show gmail` -- `bashpass --list` +# 2. Options -## Adding a password +## 2.1 `--help` | `-h` -To add a password, use the `--add` or `-a` option. +Show a brief help message. -```console -$ bashpass --add [password] -``` +## 2.2 `--version` | `-v` -BashPass will prompt you to choose whether you want to generate a password or not. -If you want to enter the password manually, type 'n' and then press 'enter'. -Otherwise, just press 'enter'. +Display the version number of your BashPass installation. -``` -Do you want to generate a password [Y/n]: y -``` +## 2.3 `--add` | `-a` -If you choose to generate the password, another prompt will appear asking you to enter the desired password length. -The default length is 14, but this can be changed in the configuration file. -Press 'enter' to use the default length, or enter a number and press 'enter' to specify a different length. +Add a new password to the system. The password can be either self-chosen or auto-generated. +If no `NAME` is specified, BashPass will ask for it. -``` -Give the length of the password (Default: 14): +```console +$ bashpass --add gmail ``` -## Updating a password +## 2.2 `--copy` | `-c` -This feature allows you to update an existing password. To use this option, run BashPass with the `--update` or `-u` flag. +Copy the password of the specified `NAME` to the clipboard. +The clipboard will be cleared after a certain amount of time, specified in the configuration file. ```console -$ bashpass --update [password] +$ bashpass --copy gmail ``` -This will ask the same questions as the `--add` feature. - -## Deleting a password +## 2.3 `--delete` | `-d` -To delete a password from your system, run BashPass with the `--delete` or `-d` option. +> :warning: Be careful, BashPass will not ask for confirmation! -**Note**: Be careful with this option, once you delete a password there is no way to recover it. +Delete the password of the specified `NAME` from the system. ```console -$ bashpass -d [password] +$ bashpass --delete gmail ``` -## Show a password +## 2.4 `--show` | `-s` -This feature will display the password in your terminal. +> :warning: BashPass wil print the password in clear text to the terminal. -**NOTE**: this will return the password in plain text. +Print the password of the specified NAME to stdout. ```console -$ bashpass --show [password] +$ bashpass --show gmail ``` -## Copy a password +## 2.5 `--update` | `-u` -This feature is more secure than the `--show` option because the clipboard will be cleared after a certain amount of time (default is 10 seconds), and the password will never be shown in the terminal. -You can use this feature by using the `--copy` or `-c` flag. +> :warning: BashPass will overwrite the previous password! + +Update the password of the specified `NAME`. +The password can be either self-chosen or auto-generated. ```console -$ bashpass --copy [password] +$ bashpass --update gmail ``` -## Synchronize a password - -BashPass provides a feature to synchronize your local passwords with a remote git repository. -The synchronization functionality requires git to be installed on your system. - -It's recommended to set up an SSH key with the remote git server, whether it's a self-hosted one or a third-party provider like GitHub or GitLab. -BashPass should work with both options. - -By default, BashPass stores passwords in `~/.local/share/bashpass/`. -You can use this location as a git repository or set up a different location as a git repository. -It's up to you to choose which option suits you best. - -**Note**: You'll have to import your GPG key on every device you want to use the synchronization functionality. -You can follow this guide https://www.debuntu.org/how-to-importexport-gpg-key-pair/ for importing and exporting your GPG keys. +## 2.6 `--list` | `-l` -### Upload - -The `upload` option will upload all local changes to the remote git repository. +List all the names of the passwords stored in the password store. ```console -$ bashpass --sync upload +$ bashpass --list ``` -### Download +## 2.7 `--sync` | `-S` -The `download` option will download all changes from the remote git repository to the user's local machine. +> :warning: The password store must be initialized with a remote Git repository before using this command. + +Sync the password store with a remote Git repository. +The `SYNC_COMMAND` can be either `upload` or `download`. ```console +$ bashpass --sync upload $ bashpass --sync download ```