Metadata-Version: 2.1
Name: totpcgi
Version: 0.7.1
Summary: A centralized hotp/totp solution based on google-authenticator
Author-email: Konstantin Ryabitsev <mricon@kernel.org>
License: GPL-2.0-or-later
Project-URL: Homepage, https://github.com/mricon/totp-cgi
Project-URL: Issues, https://github.com/mricon/totp-cgi/issues
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: COPYING
Requires-Dist: passlib
Requires-Dist: pyotp
Requires-Dist: bcrypt
Provides-Extra: cgi
Requires-Dist: flup ; extra == 'cgi'
Requires-Dist: qrcode ; extra == 'cgi'
Provides-Extra: encrypted-secret
Requires-Dist: pycryptodome ; extra == 'encrypted-secret'
Provides-Extra: ldap
Requires-Dist: python-ldap ; extra == 'ldap'
Provides-Extra: mysql
Requires-Dist: pymysql ; extra == 'mysql'
Provides-Extra: pgsql
Requires-Dist: psycopg2-binary ; extra == 'pgsql'

TOTPCGI
=======
---------------------------------------------------------
A centralized totp solution based on google-authenticator
---------------------------------------------------------

:Author:    mricon@kernel.org
:Copyright: Konstantin Ryabitsev and contributors
:License:   GPLv2+
:Version:   0.7.1

PROJECT STATUS: LIFE SUPPORT
----------------------------
**You should almost certainly not be deploying this for a new project.**

totpcgi was first written in 2012 and has not received meaningful new
development since 2019. It is kept buildable on currently-supported
distributions (AlmaLinux 10 / RHEL 10 / Python 3.12) for the benefit of
existing deployments only. New features are not planned; bug fixes are
best-effort.

If you are reaching for this in 2026, please look elsewhere first:

* For SSH 2-factor authentication, prefer FIDO2 / WebAuthn hardware
  tokens (e.g. yubikey) with ``ssh-ed25519-sk`` / ``ssh-ecdsa-sk`` keys.
* For PAM TOTP, Google's ``pam_google_authenticator`` is actively
  maintained and lives in most distro repos.
* For a full enterprise 2FA / OTP server, ``privacyIDEA`` is the
  modern, actively-developed equivalent of what totpcgi does.

KNOWN LIMITATIONS
-----------------
* **Python 3.13+ is not supported.** The CGI scripts use the stdlib
  ``cgi`` and ``cgitb`` modules, which were removed outright from
  Python 3.13 per PEP 594. The project works on Python 3.12 (the
  version shipped by AlmaLinux 10 / RHEL 10) but will fail to import
  on any newer interpreter without significant rework. There is
  currently no plan to do that rework — see "life support", above.

DESCRIPTION
-----------
The idea of totpcgi (pronounced "Toopy-CGI") came when lamenting that
google-authenticator implementation is "almost there" to be used as a
generic org-wide 2-factor solution, but is annoyingly written to be a
one-secret-per-service (or -per-host) solution. Thus, totpcgi was born,
which uses files generated by google-authenticator and serves them from
a central installation.

It is intended to be used with pam_url_.

.. _pam_url: https://fedorahosted.org/pam_url/

FEATURES
--------
1. Fully interoperable with Google-Authenticator
2. Uses Google-Authenticator-generated secret files
3. Supports pincodes (i.e. users log in with 'usercode555555')
4. Supports file-based state backend for non-redundant installations and
   Postgresql for load-balanced setups.
5. Supports encrypting the Google-Authenticator master secret with the
   user's pincode.
6. Supports web-based provisioning to generate Google-Authenticator
   compatible files (or database entries).

REQUIREMENTS
------------
1. pyotp_
2. google-authenticator_ to generate the .totp files by hand
3. flup_ (for .fcgi only)
4. psycopg2_ (for postgresql backend support)
5. py-bcrypt_ (for pincode support using bcrypt)
6. pycrypto_ and passlib_ (for encrypted-secret support)
7. pam_url_ (for PAM support)
8. python-qrcode_ (for provisioning support)
9. MySQL-python_ (for MySQL backend support)

All of these dependencies are in EPEL for RHEL 6.

.. _pyotp: https://github.com/nathforge/pyotp
.. _google-authenticator: https://code.google.com/p/google-authenticator/
.. _flup: http://trac.saddi.com/flup
.. _psycopg2: http://initd.org/psycopg/
.. _py-bcrypt: https://code.google.com/p/py-bcrypt/
.. _pycrypto: https://www.dlitz.net/software/pycrypto/
.. _passlib: https://code.google.com/p/passlib/
.. _python-qrcode: https://github.com/lincolnloop/python-qrcode
.. _MySQL-python: http://sourceforge.net/projects/mysql-python/

AUTHORS
-------
  * Konstantin Ryabitsev <mricon@kernel.org>
  * Andrew Grimberg <agrimberg@linuxfoundation.org>

SUPPORT
-------
Please open an issue on GitHub: https://github.com/mricon/totp-cgi/issues
