summaryrefslogtreecommitdiff
path: root/README.md
authorMarco Barulli <marco@clipperz.com>2014-05-02 10:20:51 (UTC)
committer Marco Barulli <marco@clipperz.com>2014-05-02 10:20:51 (UTC)
commit03659f6b3d9766898854e8a769c0c9341b3de80c (patch) (unidiff)
treeda1bcc8d9a5623c34ea9b541ea71f84848aa6d33 /README.md
parente4074dbd68760aab9350fad4c7a588a44da187c3 (diff)
downloadclipperz-03659f6b3d9766898854e8a769c0c9341b3de80c.zip
clipperz-03659f6b3d9766898854e8a769c0c9341b3de80c.tar.gz
clipperz-03659f6b3d9766898854e8a769c0c9341b3de80c.tar.bz2
added more visible security warning, updated URLs
Diffstat (limited to 'README.md') (more/less context) (ignore whitespace changes)
-rw-r--r--README.md32
1 files changed, 17 insertions, 15 deletions
diff --git a/README.md b/README.md
index e44df48..8e7cb6b 100644
--- a/README.md
+++ b/README.md
@@ -1,118 +1,120 @@
1# ![Clipperz icon][icon] CLIPPERZ - Online Password Manager 1# ![Clipperz icon][icon] CLIPPERZ - Online Password Manager
2 2
3[icon]: ./Icon.png 3[icon]: ./Icon.png
4 4
5##What does Clipperz do? 5##What does Clipperz do?
6 6
7Clipperz is an online vault where you can store confidential data without worrying about security. It can be used to save and manage passwords, private notes, burglar alarm codes, credit and debit card details, PINs, software keys, … 7Clipperz is an online vault where you can store confidential data without worrying about security. It can be used to save and manage passwords, private notes, burglar alarm codes, credit and debit card details, PINs, software keys, …
8Since passwords are the most common type of private information that you need to protect, we have added a great deal of functionality to make Clipperz a great [online password manager][home] thus solving the “password fatigue” problem. 8Since passwords are the most common type of private information that you need to protect, we have added a great deal of functionality to make Clipperz a great [online password manager][home] thus solving the “password fatigue” problem.
9 9
10**Clipperz makes the Internet the most convenient and safe place to keep you most precious and sensitive data.** 10**Clipperz makes the Internet the most convenient and safe place to keep you most precious and sensitive data.**
11 11
12Read more on the [Clipperz website][home]. 12Read more on the [Clipperz website][home].
13 13
14[home]: http://www.clipperz.com 14[home]: https://clipperz.is
15 15
16## Why an open source version 16## Why an open source version of Clipperz?
17 17
18Because we want to enable as many people as possible to play with our code. So that you can start trusting it, the code not the developers. 18Because we want to enable as many people as possible to play with our code. So that they can start trusting it. The code, not its developers.
19 19
20In order to allow you to inspect the code and analyze the traffic it generates between client and server, we had to provide an easy way to locally deploy the whole service. 20In order to allow anyone not just to inspect the source code, but also to analyze the traffic it generates between client and server, we made available this open source version as an easy way to locally deploy the whole password manager web app on your machine. You can choose among the available backends (PHP/MySQL, Python/AppEngine, …) or [contribute][CA] your own.
21 21
22Feel free to host on your machine a web service identical to [Clipperz online password manager][home]. You can choose among **multiple backends** (PHP/MySQL, Python/AppEngine, …) or you can [contribute][CA] your own. 22Whatever is your motivation for playing with Clipperz code, we would love to hear from you: [get in contact][contact]!
23 23
24Whatever is your motivation, we would love to hear from you: [get in contact!][contact] 24## Security warning
25 25
26[CA]: http://www.clipperz.com/open_source/contributor_agreement 26The open source version of Clipperz is suitable for **testing and educational purposes only**. Do not use it as an actual password management solution.
27[contact]: http://www.clipperz.com/about/contacts 27
28As an example, the current PHP backend lacks several critical capabilities such as bot protection and concurrent sessions management, moreover it could be vulnerable to serious threats (SQL injections, remote code execution, ...).
29
30[CA]: https://clipperz.is/open_source/contributor_agreement
31[contact]: https://clipperz.is/about/contacts
32[clipperz]: https://clipperz.is
28 33
29 34
30## Donations 35## Donations
31If you like what Clipperz is building, its openness and its view of cryptography as a powerful tool for liberty, then you may consider making a donation. 36If you like what Clipperz is building, its openness and its view of cryptography as a powerful tool for liberty, then you may consider making a donation.
32 37
33Our favorite payment method is clearly Bitcoin ([learn why here][why]), but you can also send your donation via credit card, Paypal or bank transfer. In all cases there will be no link between your real identity and your encrypted data stored on Clipperz. 38Our favorite payment method is clearly Bitcoin ([learn why here][why]), but you can also send your donation via credit card, Paypal or bank transfer. In all cases there will be no link between your real identity and your encrypted data stored on Clipperz.
34 39
35**To make your donation visit [this page][donations]. Thanks!** 40**To make your donation visit [this page][donations]. Thanks!**
36 41
37[why]: http://www.clipperz.com/pricing/why_bitcoin 42[why]: https://clipperz.is/pricing/why_bitcoin
38[donations]: http://www.clipperz.com/donations 43[donations]: https://clipperz.is/donations
39 44
40 45
41## License 46## License
42ALL the code included in this project, if not otherwise stated, is released with the [AGPL v3][agpl] license (see `LICENSE.txt`), and all rights are reserved to Clipperz Srl. For any use not allowed by the AGPL license, please [contact us][contact] to inquire about licensing options for commercial applications. 47ALL the code included in this project, if not otherwise stated, is released with the [AGPL v3][agpl] license (see `LICENSE.txt`), and all rights are reserved to Clipperz Srl. For any use not allowed by the AGPL license, please [contact us][contact] to inquire about licensing options for commercial applications.
43 48
44[agpl]: http://www.gnu.org/licenses/agpl.html 49[agpl]: http://www.gnu.org/licenses/agpl.html
45 50
46 51
47## Warnings
48Please note that the open source version of Clipperz Password Manager may not be suitable for mass deployments, depending on how robust is the backend you select. As an example, the current PHP backend lacks several critical capabilities such as bot protection and concurrent sessions management.
49
50## Contributions 52## Contributions
51Your contributions to Clipperz are very welcome! In order to avoid jeopardizing the ownership of the code base, we will require every developer to sign the Clipperz [Contributor Agreement][CA] 53Your contributions to Clipperz are very welcome! In order to avoid jeopardizing the ownership of the code base, we will require every developer to sign the Clipperz [Contributor Agreement][CA]
52 54
53This enables a single entity to represent the aggregated code base and gives the community flexibility to act as a whole to changing situations. 55This enables a single entity to represent the aggregated code base and gives the community flexibility to act as a whole to changing situations.
54 56
55The CA establishes a joint copyright assignment in which the contributor retains copyright ownership while also granting those rights to Clipperz Srl. With the CA in place, the aggregated code base within any Clipperz open source project is protected by both the distribution license and copyright law. 57The CA establishes a joint copyright assignment in which the contributor retains copyright ownership while also granting those rights to Clipperz Srl. With the CA in place, the aggregated code base within any Clipperz open source project is protected by both the distribution license and copyright law.
56 58
57Please [download][CA] and review the Contributor Agreement for a complete understanding of its terms and conditions. You may send your signed and completed CA to Clipperz by scanning your completed form and emailing the image or by fax. Please retain a copy for your records. **Thanks!** 59Please [download][CA] and review the Contributor Agreement for a complete understanding of its terms and conditions. You may send your signed and completed CA to Clipperz by scanning your completed form and emailing the image or by fax. Please retain a copy for your records. **Thanks!**
58 60
59 61
60## Building 62## Building
61In order to build the deployable version, you need to invoke the following command: 63In order to build the deployable version, you need to invoke the following command:
62 64
63 git clone git@github.com:clipperz/password-manager.git 65 git clone git@github.com:clipperz/password-manager.git
64 cd password-manager 66 cd password-manager
65 ./scripts/build install --backends php python --frontends beta gamma 67 ./scripts/build install --backends php python --frontends beta gamma
66 68
67The output will be available in the `target` folder, with a separate folder for each backend (currently the available options are `php` and `python`). 69The output will be available in the `target` folder, with a separate folder for each backend (currently the available options are `php` and `python`).
68The script, invoked with these parameters, will build both the full version (`install` -> index.html) and the debug version (index_debug.html) of the specified frontends. 70The script, invoked with these parameters, will build both the full version (`install` -> index.html) and the debug version (index_debug.html) of the specified frontends.
69 71
70Besides PHP and Python, more backends are in the works, most notably a node.js version. 72Besides PHP and Python, more backends are in the works, most notably a node.js version.
71 73
72 74
73### Developing 75### Developing
74To support the development of the application, a few extra tools have been built, the most useful one being `dev-proxy`. 76To support the development of the application, a few extra tools have been built, the most useful one being `dev-proxy`.
75This script, located in `scripts/dev-proxy`, is invoked without any parameters (to simplify daily usage) and all its configurations are hard coded into the actual code it executes: `scripts/proxy/main.py`. 77This script, located in `scripts/dev-proxy`, is invoked without any parameters (to simplify daily usage) and all its configurations are hard coded into the actual code it executes: `scripts/proxy/main.py`.
76 78
77The aim of this proxy is to mask the actual location of frontend JS files from the actual backend handling requests. 79The aim of this proxy is to mask the actual location of frontend JS files from the actual backend handling requests.
78 80
79When executed, this script will start listening on localhost:8888. 81When executed, this script will start listening on localhost:8888.
80 82
81All 'backend' requests (whose path starts with either `/json` or `/dump`) will be forwarded to the actual backend, that is configured as a `ReverseProxyResource` (in the current code: `proxy.ReverseProxyResource('localhost', 8084, '/java-backend')`). 83All 'backend' requests (whose path starts with either `/json` or `/dump`) will be forwarded to the actual backend, that is configured as a `ReverseProxyResource` (in the current code: `proxy.ReverseProxyResource('localhost', 8084, '/java-backend')`).
82All other requests (html files, Javascript code, CSS stylesheets and other resources) will be handled by reading the resource from the filesystem; the proxy is aware of the layout of the project, so it will be able to locate the right resource in the right place. 84All other requests (html files, Javascript code, CSS stylesheets and other resources) will be handled by reading the resource from the filesystem; the proxy is aware of the layout of the project, so it will be able to locate the right resource in the right place.
83 85
84The only file that needs to be `build`, and not read directly from the file system, is the `index.html` file. 86The only file that needs to be `build`, and not read directly from the file system, is the `index.html` file.
85 87
86In order to build this file, the following command should be executed: 88In order to build this file, the following command should be executed:
87 89
88 ./scripts/build --frontends beta gamma gamma.mobile --backends dev 90 ./scripts/build --frontends beta gamma gamma.mobile --backends dev
89 91
90 92
91Once the index.html files have been built (one for each frontend) and a backend is running and has been correctly configured in the proxy script, it is possible to access the different versions of the application at the following URLs: 93Once the index.html files have been built (one for each frontend) and a backend is running and has been correctly configured in the proxy script, it is possible to access the different versions of the application at the following URLs:
92 94
93- `http://localhost:8888/beta/index.html` 95- `http://localhost:8888/beta/index.html`
94- `http://localhost:8888/gamma/index.html` 96- `http://localhost:8888/gamma/index.html`
95- `http://localhost:8888/gamma/index.mobile.html` 97- `http://localhost:8888/gamma/index.mobile.html`
96 98
97 99
98## Installing 100## Installing
99 101
100### PHP + MySQL backend 102### PHP + MySQL backend
101 103
102* **PHP** 104* **PHP**
103 Once the project has been successfully build, the application needs to be moved in a location where the web server can run it. Everything that is needed is located into `target/php`. 105 Once the project has been successfully build, the application needs to be moved in a location where the web server can run it. Everything that is needed is located into `target/php`.
104 106
105* **MySQL** 107* **MySQL**
106 The application needs a simple MySQL database; to configure all the credentials to access the previously allocated DB, edit the file found in `php/configuration.php`. You need to edit the file actually used by the web server; this will usually be the one moved into the right place in the previous step. 108 The application needs a simple MySQL database; to configure all the credentials to access the previously allocated DB, edit the file found in `php/configuration.php`. You need to edit the file actually used by the web server; this will usually be the one moved into the right place in the previous step.
107 Once the application is in place, and the DB credentials have been configured, you should initialize the DB itself; in order to do so, just point your browser at the following url: `http://<host>/<path>/php/setup/index.php`. 109 Once the application is in place, and the DB credentials have been configured, you should initialize the DB itself; in order to do so, just point your browser at the following url: `http://<host>/<path>/php/setup/index.php`.
108 Here you will find the standard [POG][pog] setup page: it should be enough to click the "POG me up!" button at the bottom of the page, and then the "Process" button on the next page. 110 Here you will find the standard [POG][pog] setup page: it should be enough to click the "POG me up!" button at the bottom of the page, and then the "Process" button on the next page.
109 The POG interface will allow also a very basic access to the DB data that may be useful to check that the application is actually writing something on the DB (even if you will not be able to make much sense out of the data you will see, as they are all encrypted!) 111 The POG interface will allow also a very basic access to the DB data that may be useful to check that the application is actually writing something on the DB (even if you will not be able to make much sense out of the data you will see, as they are all encrypted!)
110 More information about building the PHP backend may be found in the `doc/install.php.txt` file. 112 More information about building the PHP backend may be found in the `doc/install.php.txt` file.
111 113
112 114
113## Disclaimer 115## Disclaimer
114 116
115This application has not been fully tested, so there may be still problems due to the new build script or to the new repository structure. So, for the moment, **use it at your own risk!** 117This application has not been fully tested, so there may be still problems due to the new build script or to the new repository structure. So, for the moment, **use it at your own risk!**
116 118
117 119
118[pog]: http://www.phpobjectgenerator.com/ \ No newline at end of file 120[pog]: http://www.phpobjectgenerator.com/