Welcome to ppass

GPG Password Manager

ppass is heavily inspired from pass

I wanted to extend some of its functionnalities, and decided to rewrite the application in Python. It was a good exercice to try Python as I am more used to program in js/ts and c++/qt.

This beeing said, ppass is not as well tested or stable as pass. I intend to make it evolve in the future, as I am using it on a daily basis. I am however alone on this one. If you want stability and portability, with a great community, please use pass.

Stores created with ppass are compatible with pass. They are thus also compatible with pass clients like Android Password Store.

Main features

• gpg password creation (one file per password)
• enhanced password file with username, url and comments
• open web browser from password file
• automatic fill in username and password to web browser
• automatic ssh connexion with username and password
• cli commands shortcuts for fast access to passwords
• git integration
• possibility to handle several distinct stores
• commands and params autocompletion
• cli user interface or json response

Roadmap

• enhanced filter
• enhanced clip functionnality
• test on other platforms
• code cleaning
• more to come...

---

• Welcome to ppass
  • Installation
    • Requirements
    • Install from pypi
    • Install from deb package
  • Usage
    • Initialise
    • Create a folder
    • Create a new password
    • Clip username and password
    • Filter
    • Add a new store
    • Use a store
    • Initialise new git repository
    • Initialise from existing git repository
    • Publish to git
    • Change output to JSON
    • Create a one time password
    • Shortcuts and Aliases
  • SSH Connexion
  • Build
  • Dependencies
  • Author
  • Issues
  • License

Installation

Requirements

The application is developped and used on ubuntu 22.04, with python 3.10.4. Any feedback on other platforms is welcomed.

• python3 >=3.6.2,<4.0
• xdotool: sudo apt install xdotool
• git: sudo apt install git
• gpg: sudo apt install gnupg
• nano: sudo apt install nano
• xclip: sudo apt install xclip

Install from pypi

pip install ppass

For an isolated environment with pipx:

pipx install ppass

Install from deb package

A deb package is available, built using dh-virtualenv. Installing this package will create a new Python virtual environment in opt/venvs. It will then create the symlink usr/bin/ppass pointing to opt/venvs/ppass/bin/ppass.

Note that dh-virtualenv built packages are dependent of python version. Use this only if you have default python version installed:

• ubuntu bionic 18.04: Python 3.6
• ubuntu focal 20.04: Python 3.8
• ubuntu hirsute 21.04: Python 3.9 : deprecated (new releases will not be available)
• ubuntu impish 21.10: Python 3.9 : deprecated (new releases will not be available)
• ubuntu jammy 22.04: Python 3.10

Download latest .deb file from the release page.

sudo dpkg -i ppass_1.3.3_{{os}}_amd64.deb

Usage

Initialise

Initialisation is required before using the application, to select GPG identity.

ppass init

A configuration file .ppassrc is created in the user home directory.

By default, passwords will be stored in ${HOME}/.ppass/ folder.

The --edit option will open configuration file in edit mode.

Create a folder

A folder needs to be created before creating a password file.

ppass folders create

# or

ppass folders create --name "${NAME}"

Create a new password

You can then create a new password file.

If you want a new password to be generated:

ppass generate

If you already know the password:

ppass insert

If there is only one folder, it will be selected by default. Otherwise the list of available folders will be prompted for selection.

Clip username and password

ppass open will open a new webbrowser with the saved url

ppass clip will copy and paste to the active window the username as well as the password : {username} {TAB} {password} {RETURN}

ppass user will copy username to clipboard

ppass pass will copy password to clipboard

In case a password is saved with your GPG identity, it will be prompted through a modal window.

Filter

Currently password filter is only done on the password name, not on the folder name.

A future enhancement will provide a better filter functionnality.

ppass <command> <anything> will filter displayed passwords based on anything value (name containing this value).

Add a new store

You can create several stores (config sections). Default store path is ${HOME}/.ppass-${NAME}/

ppass -c "${STORE}" init --new-section

You can also select path via the option --path. The folder will be created if it does not exist.

ppass -c "${STORE}" init --new-section --path "${PATH}"

Use a store

All functions can be used for a specific store by using the -c option from ppass application.

ppass -c "${STORE}" generate ...
ppass -c "${STORE}" insert ...
ppass -c "${STORE}" open ...
ppass -c "${STORE}" clip ...
# etc.

Initialise new git repository

You can initialise a new git repository in store path. It will set automatic git push for every password creation or modification. The git repository needs to be created on your platform before.

A default branch main is created.

ppass -c "${STORE}" init-git

You can also pass parameter through cli command:

ppass -c "${STORE}" init-git --repo "${REPO}" --user "${USER}" --mail "${EMAIL}" --branch "${BRANCH}"

Initialise from existing git repository

If the git repository already exists, you can restore it in the current store folder by adding the --pull option to init-git command.

It will download the latest commit from main branch. If the branch name is different, you can update it in the config file through ppass init --edit or through --branch option.

Publish to git

When a git repository is enabled, all changes to passwords will be pushed to remote. However, there will never be automatic pull to retrieve potential password changes from remote (from other application, computer, user, android app, aso.).

Automatic pull is not activated so that access to password remain fast.

It can be done manually through

ppass -c "${STORE} git pull"
  # or
ppass -c "${STORE} git sync" # pull then push

In case a remote change is done but not pulled, the automatic push on password modification will fail. A manual git sync will be required to merge local and remote.

Change output to JSON

Default application prints in the cli items in a user friendly way: tables, prompts, aso.

It is however possible to pass all required parameters through command options, and retrieve function results in JSON format.

ppass --json <command> ...

Create a one time password

It is possible to generate a password for direct usage, without saving it to any password file.

ppass otp

ppass does not need to be initialized.

By default, the password will be saved to clipboard.

It is possible to output json file: ppass --json otp

It is also possible to output raw text password: ppass otp --text

Shortcuts and Aliases

Application must give a fast access to passwords to be useful.

All commands can be called by shortcuts with their first letter(s):

• g for generate
• c for clip
• o for open
• ...

I personnaly also defined shortcuts in my home .bashrc file:

alias pp='ppass -c PRO'
alias ppc='ppass -c PRO clip'
alias ppo='ppass -c PRO open'
alias ppp='ppass -c PERSO'
alias pppc='ppass -c PERSO clip'
alias pppo='ppass -c PERSO open'

SSH Connexion

In case you are using login / password to connect to a server through SSH, it can be done via ppass. Please note that we discourage such type of connexion. Prefer a connexion with SSH keys instead.

In ppass, set "ssh+${DOMAIN}" in the url field.

The open and clip commands will open a new terminal and fill in SSH connexion.

Please note this is using gnome-terminal as an additional application dependency.

Build

Requirements

• debhelper: sudo apt install debhelper
• dh-virtualenv
• build
• virtualenv

Commands

poetry install

# build deb
dpkg-buildpackage -us -uc
dpkg-buildpackage -Tclean

# build python package
python3 -m build

Dependencies

Python Libraries

• click
• rich
• pyclip
• python-gnupg

Python Development Libraries

• poetry

Author

Sébastien Guerri - github page

Issues

Contributions, issues and feature requests are welcome!

Feel free to check issues page. You can also contact me.

License

Copyright (C) 2022 Sebastien Guerri

ppass is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

ppass is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with ppass. If not, see https://www.gnu.org/licenses/.