1e99/passed
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

rework readme

Browse source
This commit is contained in:
1e99 2024-11-09 22:13:32 +01:00
parent 0b9c5cccf5
commit 55191c0269
1 changed files with 37 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

65
README.md
View file

@ -1,28 +1,36 @@
# PassED
[Discord](https://discord.gg/NuGxJKtDKS) [Demo](https://passed.1e99.eu/)
[![Discord](https://badgen.net/badge/icon/discord?icon=discord&label)](https://discord.gg/NuGxJKtDKS)
[![Demo](https://img.shields.io/website-up-down-green-red/https/passed.1e99.eu.svg)](https://passed.1e99.eu/)
[![Made with Go](https://img.shields.io/badge/Made%20with-Go-1f425f.svg)](https://go.dev/)
EMail, but for passwords.
Did you ever run into the issue of needing to share a password with someone in a secure manner and you did not know how?
Did you ever run into the issue of needing to share a password with someone securely?
You want to send it to them by EMail, but there it will surely get logged along the way.
You want to share it using EMail, but there it will surely get logged along the way.
You want to write it send it to them over WhatsApp, but that's not that secure.
You want to share it using WhatsApp, but there it will show up in the notifications for everyone to read.
You want to write it on paper, but everyone can read that.
You want to share it on paper, but everyone can read that too.
PassED solves these issues by allowing you to generate single-use URLs that contain your password.
PassED solves this issue by allowing you to generate single-use URLs with your password.
## How it works
When you create a password URL, PassED firstly encrypts the password in your browser using `AES-GCM`. It then uploads the encrypted password to the server, which responds with an ID that uniquely identifies that password. The AES Key and IV (Initialization vector) is then stored in the URL, along with the ID.
When you generate a URL...
1. The browser generates an AES key.
2. The password you entered gets encrypted using this key.
3. The encrypted password is uploaded to the server, which responds with an ID to uniquely identify the password.
4. A URL is generated that contains the ID and AES key.
When someone views the password, PassED looks at the URL. It knows the password ID, AES Key and IV. It reaches out to the server, asks for a password with the ID from the URL, and then decrypts it with the AES Key and IV.
When you view a password...
1. The browser imports the AES key from the URL.
2. The browser asks the server for the password using the ID in the URL.
3. The browser decrypts the password from the server using the AES key from the URL.
This model ensures that a malicous host can not read the passwords.
## Setup
Setting up PassED can be done with docker compose or from source. As the website relies on the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) it requires a [secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts). In other words you must setup a reverse proxy for HTTPS, or access the site via `localhost`.
## Installation
Installation can be done with docker compose or from source. As the website uses the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) it needs to be in a [secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts). That means that you will need to access the website via "localhost" or HTTPS.
### Docker Compose
### Docker compose
```yaml
services:
"passed":
@ -30,33 +38,34 @@ services:
volumes:
- "./passed:/etc/passed"
environment:
- "PASSED_ADDRESS=:3000"
- "PASSED_STORE_TYPE=dir"
- "PASSED_STORE_DIR_PATH=/etc/passed"
ports:
- "3000:3000"
```
### Source
1. Download the source code
```sh
git clone https://git.1e99.eu/1e99/passed.git
### From Source
1. Clonse the source code
```bash
git clone https://git.1e99.eu/1e99/passed.git --depth 1
```
2. Ensure that you have go installed, if not follow this [guide](https://go.dev/doc/install).
3. Build the project
```sh
3. Build the project.
```bash
go build -o passed .
```
4. Run the project
```sh
4. Run the binary.
```bash
PASSED_STORE_TYPE=dir ./passed
```
## Configuration
Configuration is done with environment variables.
- `PASSED_ADDRESS`: Specifies the address that PassED should listen on, defaults to `:3000`.
- `PASSED_LOG_REQUESTS`: Specifies wether HTTP requests should be logged or not, defaults to `true`.
- `PASSED_MAX_LENGTH`: Specifies the maximum password length in bytes, defaults to `12288` (12KiB).
- `PASSED_STORE_TYPE`: Specify which store is used to save passwords, defaults to `ram`:
- `ram`: Stores all passwords in RAM, they are lost on restart.
- `dir`: Stores all passwords in a directory. Requires `PASSED_STORE_DIR_PATH` to be set to the directory, defaults to `passwords`. PassED will **not** create the directory.
- `PASSED_STORE_CLEAR_INTERVAL`: Specifies the delay in seconds to wait between clearing expired passwords, defaults to `30`.
Configuration is done using environment variables.
- `PASSED_ADDRESS`: The address that PassED should listen on, defaults to `:3000`.
- `PASSED_LOG_REQUESTS`: Should requests be logged, defaults to `true`.
- `PASSED_MAX_LENGTH`: Maximum password length in KiB, defaults to `12288`.
- `PASSED_STORE_TYPE`: Store type to pick, defaults to `ram`.
- `ram`: Passwords are stored in RAM.
- `dir`: Passwords are stored in a directory. The directory is specified using `PASSED_STORE_DIR_PATH`, which defaults to `passwords`. PassED will **not** create the directory for you.
- `PASSED_STORE_CLEAR_INTERVAL`: Time that should pass between clearing expired passwords in seconds, defaults to `30`.