lib2fas Python
Unofficial implementation of 2fas for Python (as a library). This library serves as the backend for the robinvandernoord/2fas-python CLI, a command-line tool that provides an easy interface to interact with the 2fas TOTP.
Installation
To install this project, use pip:
pip install lib2fas
# or to also install the cli tool:
pip install 2fas
Usage
After installing the package, you can import it in your Python scripts as follows:
import lib2fas
services = lib2fas.load_services("/path/to/file.2fas", passphrase="optional") # -> TwoFactorStorage
services.generate() # generate all TOTP keys
gmail = services["gmail"] # exact match (case-insensitive), returns a list of 'TwoFactorAuthDetails' instances.
github = services.find("githbu") # fuzzy match should find GitHub, returns a new TwoFactorStorage.
for label, services in github.items():
# one label can have multiple services!
for service in services: # 'service' is a TwoFactorAuthDetails instance
# Print label, service name, and TOTP code
print("Label:", label)
print("Service Name:", service.name)
print("TOTP Code:", service.generate()) # or .generate_int() to get the code as a number.
The passphrase option of load_services is optional.
If you don't provide a passphrase and your file is encrypted, you will be prompted for one.
When available, the OS keyring stores it under a per-session name. After a reboot it is no longer
retrieved, although its stale keyring item may remain until it is cleaned up.
Storing the passphrase in the login keyring is a cache-expiry mechanism, not access control. Do not assume it protects the passphrase from other processes in your unlocked login session; the exact protection depends on the keyring backend.
Note: only the "Secret Storage" keychain backend on Debian-based Linux has been tested.
Unlocking with a key instead of a passphrase
A .2fas file is encrypted with AES-GCM under a key that PBKDF2 derives from your passphrase and a
salt stored inside the file itself. You can work with that key directly instead of the passphrase:
import json
import lib2fas
with open("/path/to/file.2fas") as f:
encrypted_block = json.load(f)["servicesEncrypted"]
salt = lib2fas.extract_salt(encrypted_block) # the PBKDF2 salt embedded in the file
key = lib2fas.derive_key("my passphrase", salt) # 32 bytes
services = lib2fas.load_services("/path/to/file.2fas", key=key)
For interactive unlocking you can inject your own UnlockerProtocol instead, which lets the caller
decide where a key comes from and how long it is cached. For example, unlocking with a key stored on
a hardware token instead of typing a passphrase:
import lib2fas
class HardwareKeyUnlocker(lib2fas.UnlockerProtocol):
def unlock(self, filename: str, salt: bytes) -> bytes | None:
return my_hardware_token.derive_key(salt)
def invalidate(self, filename: str, salt: bytes) -> None: ...
def cleanup(self) -> int:
return -1 # number of stale items removed, or -1 if unknown
services = lib2fas.load_services("/path/to/file.2fas", unlocker=HardwareKeyUnlocker())
invalidate is called automatically when a key fails to decrypt, so the unlocker can evict a bad
cached entry before the next retry. load_services retries until unlock() returns None (in which
case it returns None too); pass max_retries=N to tolerate N failures and raise the
PermissionError on the next one. The default unlocker is lib2fas.PassphraseUnlocker, which
reproduces the keyring behaviour described above.
License
This project is licensed under the MIT License.
Metadata
Release files for lib2fas 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| lib2fas-1.0.0.tar.gz | 234.5 kB | Without provenance | Details for lib2fas-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| lib2fas-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for lib2fas-1.0.0-py3-none-any.whl |
Total release size: 248.6 kB
Release files / lib2fas-1.0.0.tar.gz
| Download URL | lib2fas-1.0.0.tar.gz |
|---|---|
| Size | 234.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dcfb845738a78f0e6b6442cc30e9b09874448ce4198857e24fc3c28580ebccf6
|
|
BLAKE2b-256 checksum How to use checksums |
0bc64054c17c0103fadf17de3353f874d262885145b6684e9e8a6dd1073b3242
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Linux Mint","version":"22.3","id":"zena","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / lib2fas-1.0.0-py3-none-any.whl
| Download URL | lib2fas-1.0.0-py3-none-any.whl |
|---|---|
| Size | 14.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a5586a46126314d7cfed776acc6fb25513f3676d2b10dc08ea468e9ab341ecc8
|
|
BLAKE2b-256 checksum How to use checksums |
25aea40f8950d0d03d05ec69021f1fb9a76ffad60f4c094dadf4e89d102edc98
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Linux Mint","version":"22.3","id":"zena","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for lib2fas 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.