diff --git a/README.md b/README.md index d2c50d70..1181612b 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,7 @@ Passman is a full featured password manager. [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/nextcloud/passman/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/nextcloud/passman/?branch=master) ## Join us! -There is a Telegram-Group: -* [Passman General](https://t.me/passman_general) - -Those are mainly used to discuss all sorts of topics for Passman and it's apps! +Visit the [“Passman General Talk” Telegram Group](https://t.me/passman_general) to participate in all sorts of topical discussions about Passman and its apps! ## Contents @@ -44,13 +41,13 @@ For more screenshots: [Click here](http://imgur.com/a/giKVt) ## Features: -- Vaults -- Vault key is never sent to the server -- Credentials are stored with 256 bit AES (see [security](https://github.com/nextcloud/passman#security)) -- Ability to add custom fields to credentials -- Built-in OTP(One Time Password) generator +- Multiple vaults +- Vault keys are never sent to the server +- 256-bit AES-encrypted credentials (see [security](https://github.com/nextcloud/passman#security)) +- User-defined custom credentials fields +- Built-in OTP (One Time Password) generator - Password analyzer -- Share passwords internally and via link in a secure manner. +- Securely share passwords internally and via link - Import from various password managers: - KeePass - LastPass @@ -86,79 +83,70 @@ Untested databases: ## Security ### Password generation -Passman features a build in password generator. -Not it only generates passwords, but it also measures their strength using [zxcvbn](https://github.com/dropbox/zxcvbn). +Passman can generate passwords *and* measure their strength using [zxcvbn](https://github.com/dropbox/zxcvbn). ![](http://i.imgur.com/2qVBUfM.png) Generate passwords as you like ![](http://i.imgur.com/jcRicOV.png) -Passwords are generated using the random functions from `sjcl`. +Passwords are generated using `sjcl` randomization. ### Storing credentials -All passwords are encrypted client side using [sjcl](https://github.com/bitwiseshiftleft/sjcl) which uses AES-256 bit. -Users supply a vault key which is feed into sjcl as encryption key. -After the credentials are encrypted they are send to the server, there they will be encrypted again. -This time using the following routine: -- A key is generated using `passwordsalt` and `secret` from config.php *so back those up* -- Then the key is [stretched](http://en.wikipedia.org/wiki/Key_stretching) using [Password-Based Key Derivation Function 2](http://en.wikipedia.org/wiki/PBKDF2) (PBKDF2). -- [Encrypt-then-MAC](http://en.wikipedia.org/wiki/Authenticated_encryption#Approaches_to_Authenticated_Encryption) (EtM) is used for ensuring the authenticity of the encrypted data. -- Uses openssl with the `aes-256-cbc` ciper. -- [Initialization vector](http://en.wikipedia.org/wiki/Initialization_vector) (IV) is hidden -- [Double Hash-based Message Authentication Code](http://en.wikipedia.org/wiki/Hash-based_message_authentication_code) (HMAC) is applied for verification of the source data. +All passwords are encrypted client side with [sjcl](https://github.com/bitwiseshiftleft/sjcl) using 256-bit AES. +You supply a vault key which sjcl uses to encrypt your credentials. Your encrypted credentials are then sent to the server and encrypted yet again using the following routine: +- A key is generated using `passwordsalt` and `secret` from config.php *(so back those up)*. +- The key is [stretched](http://en.wikipedia.org/wiki/Key_stretching) using [Password-Based Key Derivation Function 2](http://en.wikipedia.org/wiki/PBKDF2) (PBKDF2). +- [Encrypt-then-MAC](http://en.wikipedia.org/wiki/Authenticated_encryption#Approaches_to_Authenticated_Encryption) (EtM) is used to ensure encrypted data authenticity. +- Uses openssl with the `aes-256-cbc` cipher. +- [Initialization vector](http://en.wikipedia.org/wiki/Initialization_vector) (IV) is hidden. +- [Double Hash-based Message Authentication Code](http://en.wikipedia.org/wiki/Hash-based_message_authentication_code) (HMAC) is applied for source data verification. -### Sharing credentials. -Passman allows users to share passwords (this can be turned off by an administrator). +### Sharing credentials +Passman allows users to share passwords. *(Administrators may disable this feature.)* ## API -For developers Passman offers an [api](https://github.com/nextcloud/passman/wiki/API). +Passman offers a developer API [api](https://github.com/nextcloud/passman/wiki/API). ## Support Passman -Passman is open source, and we would gladly accept a beer (or pizza!) -Please consider donating +Passman is open source but we’ll gladly accept a beer *or pizza!* Please consider donating: - [PayPal](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=6YS8F97PETVU2) - [Patreon](https://www.patreon.com/user?u=4833592) - [Flattr](https://flattr.com/@passman) - bitcoin: 1H2c5tkGX54n48yEtM4Wm4UrAGTW85jQpe ## Code reviews -If you have any improvements regarding our code. -Please do the following +If you have any code improvements: - Clone us - Make your edits -- Add your name to the contributors +- Add your name to the contributors - Send a [PR](https://github.com/nextcloud/passman/pulls) -Or if you're feeling lazy, create an issue, and we'll think about it. +Or, if you’re feeling lazy, create an issue and we’ll think about it. ## Docker -To run Passman with [Docker](https://www.docker.com/) you can use our test docker image. -You have to supply your own SSL certs, self signed or Let's encrypt it doesn't matter. -Please note that the docker is only for testing purposes, as database user / password are hardcoded. +To run Passman with [Docker](https://www.docker.com/), use our test Docker image. Supply your own self-signed SSL certs or use [Let’s Encrypt](https://letsencrypt.org/). Please note: The Docker image is for _testing *only*_ as database user / password are hardcoded. -If you like to spiece up our docker image and make it a full fledged secure, production ready install, you're welcome to do so. -Please note that: +If you’d like to *spice up* our Passman Docker image into a full-fledged, production-ready install, you’re welcome to do so. Please note: - Port 80 and 443 are used -- SSL is enabled (or disabled if certs not found) -- Startup time of container must be less than 15 seconds +- SSL is enabled (or disabled if no certs are found) +- Container startup time must be less than 15 seconds Example: ``` docker run -p 8080:80 -p 8443:443 -v /directory/cert.pem:/data/ssl/cert.pem -v /directory/cert.key:/data/ssl/cert.key brantje/passman ``` -If you want a production ready container you can use the [Nextcloud docker](https://hub.docker.com/_/nextcloud/), and install passman as an app. - +If you want a production-ready container, use the [Nextcloud Docker](https://hub.docker.com/_/nextcloud/) and install Passman as an app. ## Development -Passman uses a single `.js` file for the templates. This gives the benefit that we don't need to request every template with XHR. -For CSS we use SASS so you need ruby and sass installed. -`templates.js` and the CSS are built with `grunt`. -To watch for changes use `grunt watch` -To run the unit tests install phpunit globally, and setup the environment variables on the `launch_phpunit.sh` script then just run that script, any arguments passed to this script will be forwarded to phpunit. +- Passman uses a single `.js` file for templates which minimizes XHR template requests. +- CSS uses SASS, so Ruby and SASS must be installed. +- `templates.js` and the CSS are built with `grunt`. +- Watch for changes using `grunt watch`. +- Run unit tests — Install phpunit globally, setup environment variables in the `launch_phpunit.sh` script, and run the script. All arguments passed to `launch_phpunit.sh` are forwarded to phpunit. ## Main developers - Brantje @@ -171,4 +159,4 @@ Add yours when creating a [pull request](https://help.github.com/articles/creati ## FAQ **Are you adding something to check if malicious code is executing on the browser?** -No, because malicious code could edit the functions that check for malicious code. +No, because malicious code can edit functions that check for malicious code.