gPass

gPass Git Source Tree

Root/README.md

1gPass : global Password for Firefox and Chrome
2==============================================
3
4Introduction
5------------
6
7Everyday we have a lot of passwords to manage corresponding to a lot of accounts we use. It's hard to remain all of these, moreover if we don't use it often. So, what most people do is to generate only a subset of passwords easy to remain. This implies two common errors :
8
9 * Password are not very strong
10 * We use them for multiple accounts
11
12The best way to avoid these errors is to have a unique strong password for each account. gPass helps to reach this goal : you keep a subset of passwords (called masterkey) and for each login/masterkey tuple you chose, gPass returns the real password by querying a password server.
13
14To have a high level of security, all information is stored encrypted (server side). Nothing is stored on client. The decryption is done on the fly when it's needed and only with user input. So, a hacker can get your password database, it will not be able to see any information (except if it brute force or leak your masterkey) ! So it's important to choose a strong masterkey !
15
16This addon is like [last pass](https://lastpass.com/) one, but I wanted it to be open source and self hostable (be careful on server down !). Moreover, with gPass, you can have multiple master keys !
17
18
19Usage
20-----
21
22The first thing to do is to populate your database (from your/a password server) with website address/login/password/master key values. You can use "*" character to access to all subdomains of a specific website (ie *.google.com). If you want to make a strong password, there is a password generator. After that, configure your addon in "tools -> addons -> gPass -> preferences" in Firefox or "More tools -> extensions -> gPass -> options" in Chrome to point to your password server (+ username). **Don't forget to enable addon within private mode**. Be careful, login and password are case sensitive !
23
24When you're in a login form and you want to use gPass, type your login (case sensitive !) and fill "@@masterkey" in password field (only if gPass icon is green !). Then submit and password will automatically be replaced by the one in the database (after addon decrypt it).
25
26**You can also type "@_masterkey" to only replace your password without automatic submit. This allows to support more websites.**
27
28Another option is to enter your credentials in the new popup menu by clicking on gPass icon. If it's possible, gPass will auto fill password field, if not result password is stored into your clipboard. Popup path is a safest method as website page will never see your masterkey. There is also an option to disable addon for a specific website (it's a local configuration, so it must be done for each browser).
29
30
31Technical details
32-----------------
33
34The two main columns in database are "login" and "password".
35login is compounded by "domain;login", salted and encrypted with AES 256-CBC
36
37The real key that encrypts these fields is PBKDF2 (hmac-sha256, masterkey, password_server_url, 1000, 256), IV is PBKDF2 (hmac-sha256, password_server_url, masterkey, 1000, 256)
38
39PBKDF2 level can be changed by user.
40
41Server side is written in PHP (with SQLite3 for database component).
42
43
44Server
45------
46
47To host a password server, you need a webserver. Just copy server files in a directory read/write for web server user (www-data). A sample apache2 configuration file is available in resources. Since v0.8 and the use of Crypto API, **it's manadatory to have an HTTPS access (valid SSL/TLS certificate) to the server**. Without that, the decryption will fails.
48
49Configuration parameters are in conf.php
50
51A demonstration server is available [here](https://gpass-demo.soutade.fr). It's the default server configuration for fresh installed addon (user demo).
52
53**Warning** The master key derivation is partially based on account URL. So it's linked to your current server information. You can't move databases from servers with different URLs, you need to export them and import it again.
54
55**Server side is available [here](http://indefero.soutade.fr/p/gpass/downloads)**
56
57Version 0.6 introduces shadow logins. It's a protection again illegal database dump and purge but requires twice computation. Database update is transparent.
58
59The principle is to generate a random value (shadow login) that must be encrypted with the masterkey to get an access token. This access token allows to get the true (but encrypted) login/password couple. It's a kind of challenge : if I can encrypt the shadow login, I know the masterkey ! For security reason, the derivation of masterkey for deciphering passwords is different than for encrypting shadow logins (it uses its own salt). It's enabled by default.
60
61
62Client
63------
64
65Just install the package. You can have debug information by setting DEBUG in main.js.
66
67
68Command line interface
69----------------------
70
71A command line interface is also available with the following usage :
72
73 Usage: ./gpass_cli [-f config_file] [-p server_port] [-c CA_certificate_path] [-l PBKDF2_level] [-s gpass_server] [-v] -d domain -u username
74
75You can save recurrent parameters into a configuration file. Default config file is found at $HOME/.local/share/gpass/gpass.ini
76
77The dependencies are libcurl and OpenSSL (-dev packages : ie _libcurl4-openssl-dev_ and _libssl-dev_)
78
79A sample configuration file is available _gpass.ini.sample_
80
81
82Version Information
83-------------------
84
85Current version is 0.9. **(not compatible with 0.7)**
86
87Firefox will remove support for addons, so the gPass addon code is not supported since v0.8, please migrate to webextension.
88
89Transition from v0.7 to v0.8 : **Please update your masterkey (even with the same one) to gain a security level of your passwords's wallet.**
90
91
92License
93-------
94
95All the code is licensed under GPL v3. Source code is available [here](http://indefero.soutade.fr/p/gpass).

Archive Download this file