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

   mkdir -p ~/.venvs
   python3 -m venv ~/.venvs/pyjod
   

3. Activate the virtual environment

   source ~/.venvs/pyjod/bin/activate
   

4. Install pyjod and the optional dependencies you want

   # 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

   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.

   posteid
   

2. After the first execution, you can call posteid again to check the status of your device-account enrolment.
3. Generate an OTP-code to authenticate using the "Generate a single-use code" option.

   posteid otp
   

4. 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.

   posteid authorize
   

5. Export the QR generation seed to a compatible app using a standard provisioning QR-code You will need the extra requirements [qr]

   posteid qr
   

6. Detect a rapid-authentication qr in your screen and authorize the access using it. You will need the extra requirements [scanqr]

   posteid scanqr
   

7. Revoke your device enrolment, disabling private keys and OTP generator.

   posteid revoke