You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+61-72
Original file line number
Diff line number
Diff line change
@@ -3,93 +3,90 @@ passff
3
3
4
4
[](https://gitter.im/jvenant/passff?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
5
5
6
-
**[zx2c4 pass](http://www.zx2c4.com/projects/password-store/)** manager addon for Firefox
7
-
**Official signed version can be found on the [mozilla addon page](https://addons.mozilla.org/firefox/addon/passff)**
6
+
**[zx2c4 pass](http://www.zx2c4.com/projects/password-store/)** management extension for Firefox, Chrome\*, and Opera\*
7
+
8
+
**Official signed version can be found on the [Mozilla add-on page](https://addons.mozilla.org/firefox/addon/passff)**
8
9
9
10
10
11
### Overview
11
-
This plugin will allow you to access your **[zx2c4 pass](http://www.zx2c4.com/projects/password-store/)** repository directly from Firefox.
12
+
This extension will allow you to access your **[zx2c4 pass](http://www.zx2c4.com/projects/password-store/)** repository directly from your web browser.
12
13
13
-
It will try to auto fill and auto submit the login form if a matching password entry is found.
14
+
You can choose to automatically fill and submit login forms if a matching password entry is found.
14
15
15
16
### Installation
16
-
- You need **[zx2c4 pass](http://www.zx2c4.com/projects/password-store/)** installed on your computer
17
-
- You will also need a working password repository
18
-
- Download the last release of the plugin **[here](https://github.com/jvenant/passff/releases)**.
19
-
- You can then manually install the plugin in Firefox from the addons page (Firefox/Add-ons/Install Add-on from File...)
20
-
21
-
Alternatively, to use the git version:
22
-
- Clone this repository
23
-
- From the <code>$LOCAL_CLONE/src/</code> directory, execute <code>make</code>
24
-
- Manually install the resulting plugin from the <code>$LOCAL_CLONE/bin/</code> directory
17
+
- You need **[zx2c4 pass](http://www.zx2c4.com/projects/password-store/)** installed on your computer and a password respository with [password files configured to our format](#password-configuration)
18
+
- You will also need to **[install the host application](docs/INSTALLATION.md#installing-the-host-application)** so the extension can communicate with `pass` to retrieve your passwords
A black icon with a P should appear in your Firefox toolbar.
28
-
From here, you will be able to browse your password repository
29
-
or search using a case sensitive **Fuzzy matching** algorithm.
30
-
The shortcut to open the menu is: **Ctrl-y**
31
-
So considering this repository
32
-
* Internet
33
-
* MySite1
34
-
* MySite2
35
-
* CoolStuf
36
-
* SuperSite1
37
-
* SuperSite2
38
-
39
-
<Ctrl-y>M1<Enter> will send and authenticate you on MySite1 (<Shift-Enter> to open in a new tab)
40
-
41
-
Current supported features are:
42
-
- Fill and submit
43
-
- Goto, fill and submit
44
-
- Copy login to clipboard
45
-
- Copy password to clipboard
24
+
Alternatively, you can install an older version or the latest build from GitHub by refering to [instructions here](docs/INSTALLATION.md).
46
25
47
-
Additionally, if you added the url property in your password info, you will be able to go there by clicking directly on the password menu. (left-click same tab, middle-click new tab)
26
+
##### Password configuration
27
+
If you only want the extension to fill out passwords, you don't need any special format for your password files. But if you follow our format, the extension can also visit the website's URL and fill out the username and other input fields for you.
48
28
49
-
An accepted format for the password info is:
29
+
The format is:
50
30
```
51
31
<the_password>
52
32
login: <the_login>
53
33
url: <the_url>
54
34
<other_inputfield_name> : <inputfield_value>
55
35
```
56
-
Additional password, username, and url tags may be defined through the preferences dialog.
57
36
58
-
PassFF will also try to find login password and url inside the direct child of a pass node.
59
-
For example, if you have a structure like this:
37
+
You can change or configure additional names for the login and url values in preferences.
38
+
39
+
Lines besides the login and URL that match the format `<other_inputfield_name>: <value>` can be used to fill in input fields besides the login and password fields. The left hand side of the colon should match the input field's `name` or `id` attribute.
40
+
41
+
Alternatively, you can organize your login information with file structure. For example, if you have this file structure:
60
42
* www
61
43
* supersite.com
62
44
* login
63
45
* user
64
46
* mysite.com
65
47
66
48
PassFF will
67
-
* get the login from the "login" entry for supersite.com
68
-
* get the login form the "login" field inside the mysite.com entry for mysite.com (see format above)
49
+
* get the login from the "login" file under supersite.com
50
+
* get the login from the "login" field inside the mysite.com entry for mysite.com (see format above)
69
51
70
-
Fields names can be set in the preferences.
52
+
The file structure approach does not support custom input fields, however.
71
53
72
-
From the plugin preferences you will be able to set:
73
-
- Inputs (A comma separated list of input names. Input field names in a html page containing one of those values will be filled with the corresponding value.)
74
-
- Passwords input names.
75
-
- Login input names.
76
-
- Fields (A comma separated list of field names. The first matching field in the password data or in the store tree will be used as the corresponding value.)
77
-
- Login field names.
78
-
- Password field names.
79
-
- Url field names.
80
-
- Pass Scrit params
81
-
- The pass script path.
82
-
- Pass home. If empty, use User home.
83
-
- Location of the gpg agent info file containing environment variables (relative to the home).
54
+
### Usage
55
+
Once installed, you should have a new icon in your toolbar. Click the icon to browse your password repository or search using a **fuzzy matching** algorithm.
84
56
85
-
### See the logs
57
+
##### Keyboard shortcuts
58
+
The default shortcut to open the menu is <kbd>ctrl</kbd>+<kbd>y</kbd>.
86
59
87
-
To enable debug mode, just go in the addon preferences and check the "Enable logs" check box at the bottom of the dialog box. You then have to open the Browser console (Tools/Web Developper/Browser console)
88
-
You should see many lines about passff. You could Filter on "[PassFF]" if you want
60
+
With the menu open, you can press <kbd>enter</kbd> to execute one of the following commands, according to your preferences:
61
+
- Fill and submit
62
+
- Goto, fill and submit
63
+
- Copy login to clipboard
64
+
- Copy password to clipboard
65
+
66
+
##### Preferences
67
+
From the extension preferences you will be able to set:
68
+
- Inputs (A comma separated list of input names. Input field names in a html page containing one of those values will be filled with the corresponding value.)
69
+
- Passwords input names
70
+
- Login input names
71
+
- Fields (A comma separated list of field names. The first matching field in the password data or in the store tree will be used as the corresponding value.)
72
+
- Login field names
73
+
- Password field names
74
+
- URL field names
75
+
- Pass Script params
76
+
- The pass script path
77
+
- Pass home (if empty, uses your user home)
78
+
- Location of the gpg agent info file containing environment variables (relative to the home)
79
+
- Adding Passwords
80
+
- The default length for generating passwords
81
+
- Whether or not to include symbols in generated passwords by default
82
+
- Preferred new password method ("generate" or "insert")
89
83
90
84
### Issues
85
+
If you're having problems, the most common causes are misconfigured preferences or an improperly installation of the host application. You can get more information by [debugging the extension](docs/CONTRIBUTING.md#debugging).
86
+
87
+
First, [make sure the host application is installed correctly](docs/INSTALLATION.md#installing-the-host-application).
91
88
92
-
If you're experiencing problems running passff or have some encoding issue, try using the "through shell" approach in the preferences (under "Pass Script").
89
+
If that's okay, try using the "through shell" approach in the preferences (under "Pass Script").
93
90
94
91
**NOTE:** This method may also be applicable if GPG fails to provide a pin entry
95
92
dialog, or if you experience otherwise unexplained issues with incorrect login
@@ -98,27 +95,19 @@ and/or password data.
98
95
Configure the script's execution parameters appropriately:
99
96
100
97
* Set "User home" to the absolute path to your home directory
101
-
* Set "Pass command" to the path to the ````pass```` binary (if installed with homebrew, the default location is ````/usr/local/bin/pass````)
102
-
* Set "Pass shell" to your preferred shell (e.g. ````/bin/bash````)
103
-
* Set "Shell arguments" to ````--login````
104
-
105
-
With those settings in place, the plugin should be able to find your passwords.
98
+
* Set "Pass command" to the path to the `pass` binary (if installed with homebrew, the default location is `/usr/local/bin/pass`)
99
+
* Set "Pass shell" to your preferred shell (e.g. `/bin/bash`)
100
+
* Set "Shell arguments" to `--login`
106
101
107
-
If you're still having trouble, it may be due to a bug present in version 1.6.5 and earlier of pass. From your shell, check the output of ````pass list````. If the passwords listed end with ````.gpg````, then your version of pass contains the bug. The bug was fixed in [this commit](http://git.zx2c4.com/password-store/commit/?id=a619988f7986d72f4e0ac7256ce48596df6a2a34). You must update your version of ````pass```` or manually apply [this patch](http://git.zx2c4.com/password-store/patch/?id=a619988f7986d72f4e0ac7256ce48596df6a2a34) to the pass script on your machine. Once ````pass list```` lists passwords with the ````.gpg```` stripped off, the plugin should work!
108
-
109
-
### People contributing to the project
102
+
With those settings in place, the extension should be able to find your passwords.
Thanks for your interest in contributing to PassFF!
4
+
5
+
To get started, you'll need clone the repository and install the extension from your local copy. Instructions can be found [here](docs/INSTALLATION.md).
6
+
7
+
If you're using Firefox, you'll need to use Firefox Developer Edition, since unsigned extensions aren't permitted in the normal build.
8
+
9
+
## Development
10
+
Once you've built and installed the XPI file into your browser, you're ready to make changes. When you're ready to run your changes, rebuild the XPI file (by running `make` again), then reload the extension.
11
+
12
+
#### Debugging
13
+
You'll probably want to enable debugging. Follow the instructions for your browser:
14
+
- For Firefox, visit "about:debugging#addons" and check "Enable add-on debugging".
15
+
- For Chrome, visit "chrome://extensions", and check Developer Mode.
16
+
- For Opera, visit "opera:extensions" and enable Developer Mode.
17
+
18
+
19
+
## Style guide
20
+
Please follow these conventions and amend to them when necessary.
This extension requires **[zx2c4 pass](http://www.zx2c4.com/projects/password-store/)** to be installed and set up with a password repository. Make sure you can execute `pass show some-password-name` in a terminal before continuing.
4
+
5
+
To make the most of the extension, you should format your password files according to [our expected format](/README.md#password-configuration).
6
+
7
+
For the extension, you need the extension in your browser *and* what's called the "host application". The host application is what allows the extension to communicate with `pass` on your system.
Download the XPI file from [our releases page](https://github.com/nwallace/passff/releases).
19
+
###### Firefox
20
+
Unsigned extensions are only available with Firefox Developer Edition. Visit "about:debugging#addons", then click "Load Temporary Add-on".
21
+
###### Chrome
22
+
Visit "chrome://extensions", check "Developer mode", then click "Load unpacked extension".
23
+
###### Opera
24
+
Simply drag and drop the XPI file onto your browser!
25
+
26
+
#### Latest from GitHub
27
+
Clone the repository. Then, from the project's `src/` directory, execute `make`. This will create an XPI file in the project's `bin/` directory that you can install in your browser as described above.
28
+
29
+
## Installing the host application
30
+
For the extension to communicate with your system's `pass` script, you need to install what's called the host application.
31
+
32
+
#### Official release
33
+
Download the `install_host_app.sh` script from [our releases page](https://github.com/nwallace/passff/releases) and execute it.
34
+
35
+
#### Latest from GitHub
36
+
Clone the repository. Then, from the project's `host/` directory, execute the installation script for your desired browser (`--firefox`, `--chrome`, `--opera`). Omit the browser flag to install it for any browser you have on your system.
37
+
38
+
```
39
+
$ ./install_host_app.sh --firefox
40
+
```
41
+
42
+
This will link the host application JSON file appropriately for your browser.
43
+
44
+
If this doesn't work, you can link the file yourself. First, change the "path" value in the `passff.json` file to be the absolute path to the project's `host/passff.py` file. Then symlink (or copy) the file `host/passff.json` to the appropriate location for your browser and OS:
0 commit comments