populate README.md

README.md

@@ -0,0 +1,77 @@
+
+
+<!-- ABOUT THE PROJECT -->
+# pyjod
+
+Open-source implementation of the Strong Customer Authentication client agent used by the italian provider Poste Italiane S.p.A.
+
+### DISCLAIMER:
+* The main purpose of this project is research and understanding of the techniques and protocols used.
+* This project is under development and unstable, using it could cause revocation or ban of your user account.
+* Using this software would very likely compromise most of the security of having a 2-factor authentication scheme. Also, this software is not security-audited at all and is storing all your private keys and secret UNENCRYPTED on your computer!
+
+In conclusion: USE IT ONLY AT YOUR RISKS, UNDER YOUR RESPONSABILITY, AND IF YOU KNOW VERY WELL WHAT YOU ARE DOING!
+
+
+## Installation
+
+All the following instruction assumes that you are using a BASH shell under Linux,
+you will have to adapt them if you use a different Operating System or a different shell.
+
+1. Ensure you have a proper and recent Python (> 3.9) installed. 
+2. (Strongly suggested) create a dedicated Python virtual environment
+   ```sh
+   mkdir -p ~/.venvs
+   python3 -m venv ~/.venvs/pyjod
+   ```
+3. Activate the virtual environment
+   ```sh
+   source ~/.venvs/pyjod/bin/activate
+   ```
+4. Install `pyjod` and the optional dependencies you want
+   ```sh
+   # For a basic installation
+   pip install "git+https://projects.lilik.it/zolfa/pyjod"
+   # To include QR generator for OTP Authenticator apps
+   pip install "git+https://projects.lilik.it/zolfa/pyjod#egg=pyjod[qr]"
+   # To include also the QR screen scanner for instant authentication
+   pip install "git+https://projects.lilik.it/zolfa/pyjod#egg=pyjod[qr,scanqr]"
+   ```
+5. Create a symbolic link from a directory available in your `$PATH`
+   ```sh
+   ln -s ~/.venvs/pyjod/bin/posteid ~/.local/bin/posteid
+   ```
+
+## Basic usage
+
+1. Execute `posteid` in a terminal, you will be guided into logging in and
+   configuring the application and enroling the device to your account.
+   ```sh
+   posteid
+   ```
+2. After the first execution, you can call `posteid` again to check the status of
+   your device-account enrolment.
+2. Generate an OTP-code to authenticate using the "Generate a single-use code" option.
+   ```sh
+   posteid otp
+   ```
+3. List all the pending authentication request, and authorize one of them.
+   You will only see the requests generated using the "Send a notification to my device"
+   option.
+   ```sh
+   posteid authorize
+   ```
+4. Export the QR generation seed to a compatible app using a standard provisioning QR-code
+   _You will need the extra requirements [qr]_
+   ```sh
+   posteid qr
+   ```
+5. Detect a rapid-authentication qr in your screen and authorize the access using it.
+   _You will need the extra requirements [scanqr]_
+   ```sh
+   posteid scanqr
+   ```
+6. Revoke your device enrolment, disabling private keys and OTP generator.
+   ```sh
+   posteid revoke
+   ```