././@PaxHeader0000000000000000000000000000003400000000000011452 xustar000000000000000028 mtime=1690501252.1599317 pyotp-2.9.0/0000755000076600000240000000000000000000000014776 5ustar00andrey.kislyukstaff00000000000000././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1639042081.0 pyotp-2.9.0/LICENSE0000644000076600000240000000222600000000000016005 0ustar00andrey.kislyukstaff00000000000000Copyright (C) 2011-2021 Mark Percival , Nathan Reynolds , Andrey Kislyuk , and PyOTP contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1639042183.0 pyotp-2.9.0/MANIFEST.in0000644000076600000240000000006300000000000016533 0ustar00andrey.kislyukstaff00000000000000include LICENSE include README.rst include test.py ././@PaxHeader0000000000000000000000000000003300000000000011451 xustar000000000000000027 mtime=1690501252.158836 pyotp-2.9.0/PKG-INFO0000644000076600000240000002272400000000000016102 0ustar00andrey.kislyukstaff00000000000000Metadata-Version: 2.1 Name: pyotp Version: 2.9.0 Summary: Python One Time Password Library Home-page: https://github.com/pyotp/pyotp Author: PyOTP contributors Author-email: kislyuk@gmail.com License: MIT License Project-URL: Documentation, https://pyauth.github.io/pyotp Project-URL: Source Code, https://github.com/pyauth/pyotp Project-URL: Issue Tracker, https://github.com/pyauth/pyotp/issues Project-URL: Change Log, https://github.com/pyauth/pyotp/blob/master/Changes.rst Platform: MacOS X Platform: Posix Classifier: Intended Audience :: Developers Classifier: License :: OSI Approved :: MIT License Classifier: Operating System :: MacOS :: MacOS X Classifier: Operating System :: POSIX Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.7 Classifier: Programming Language :: Python :: 3.8 Classifier: Programming Language :: Python :: 3.9 Classifier: Programming Language :: Python :: 3.10 Classifier: Programming Language :: Python :: 3.11 Classifier: Topic :: Software Development :: Libraries :: Python Modules Requires-Python: >=3.7 Provides-Extra: test License-File: LICENSE PyOTP - The Python One-Time Password Library ============================================ PyOTP is a Python library for generating and verifying one-time passwords. It can be used to implement two-factor (2FA) or multi-factor (MFA) authentication methods in web applications and in other systems that require users to log in. Open MFA standards are defined in `RFC 4226 `_ (HOTP: An HMAC-Based One-Time Password Algorithm) and in `RFC 6238 `_ (TOTP: Time-Based One-Time Password Algorithm). PyOTP implements server-side support for both of these standards. Client-side support can be enabled by sending authentication codes to users over SMS or email (HOTP) or, for TOTP, by instructing users to use `Google Authenticator `_, `Authy `_, or another compatible app. Users can set up auth tokens in their apps easily by using their phone camera to scan `otpauth:// `_ QR codes provided by PyOTP. Implementers should read and follow the `HOTP security requirements `_ and `TOTP security considerations `_ sections of the relevant RFCs. At minimum, application implementers should follow this checklist: - Ensure transport confidentiality by using HTTPS - Ensure HOTP/TOTP secret confidentiality by storing secrets in a controlled access database - Deny replay attacks by rejecting one-time passwords that have been used by the client (this requires storing the most recently authenticated timestamp, OTP, or hash of the OTP in your database, and rejecting the OTP when a match is seen) - Throttle (rate limit) brute-force attacks against your application's login functionality (see RFC 4226, section 7.3) - When implementing a "greenfield" application, consider supporting `FIDO U2F `_/`WebAuthn `_ in addition to HOTP/TOTP. U2F uses asymmetric cryptography to avoid using a shared secret design, which strengthens your MFA solution against server-side attacks. Hardware U2F also sequesters the client secret in a dedicated single-purpose device, which strengthens your clients against client-side attacks. And by automating scoping of credentials to relying party IDs (application origin/domain names), U2F adds protection against phishing attacks. One implementation of FIDO U2F/WebAuthn is PyOTP's sister project, `PyWARP `_. We also recommend that implementers read the `OWASP Authentication Cheat Sheet `_ and `NIST SP 800-63-3: Digital Authentication Guideline `_ for a high level overview of authentication best practices. Quick overview of using One Time Passwords on your phone -------------------------------------------------------- * OTPs involve a shared secret, stored both on the phone and the server * OTPs can be generated on a phone without internet connectivity * OTPs should always be used as a second factor of authentication (if your phone is lost, you account is still secured with a password) * Google Authenticator and other OTP client apps allow you to store multiple OTP secrets and provision those using a QR Code Installation ------------ :: pip install pyotp Usage ----- Time-based OTPs ~~~~~~~~~~~~~~~ :: import pyotp import time totp = pyotp.TOTP('base32secret3232') totp.now() # => '492039' # OTP verified for current time totp.verify('492039') # => True time.sleep(30) totp.verify('492039') # => False Counter-based OTPs ~~~~~~~~~~~~~~~~~~ :: import pyotp hotp = pyotp.HOTP('base32secret3232') hotp.at(0) # => '260182' hotp.at(1) # => '055283' hotp.at(1401) # => '316439' # OTP verified with a counter hotp.verify('316439', 1401) # => True hotp.verify('316439', 1402) # => False Generating a Secret Key ~~~~~~~~~~~~~~~~~~~~~~~ A helper function is provided to generate a 32-character base32 secret, compatible with Google Authenticator and other OTP apps:: pyotp.random_base32() Some applications want the secret key to be formatted as a hex-encoded string:: pyotp.random_hex() # returns a 40-character hex-encoded secret Google Authenticator Compatible ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PyOTP works with the Google Authenticator iPhone and Android app, as well as other OTP apps like Authy. PyOTP includes the ability to generate provisioning URIs for use with the QR Code scanner built into these MFA client apps:: pyotp.totp.TOTP('JBSWY3DPEHPK3PXP').provisioning_uri(name='alice@google.com', issuer_name='Secure App') >>> 'otpauth://totp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXP&issuer=Secure%20App' pyotp.hotp.HOTP('JBSWY3DPEHPK3PXP').provisioning_uri(name="alice@google.com", issuer_name="Secure App", initial_count=0) >>> 'otpauth://hotp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXP&issuer=Secure%20App&counter=0' This URL can then be rendered as a QR Code (for example, using https://github.com/soldair/node-qrcode) which can then be scanned and added to the users list of OTP credentials. Parsing these URLs is also supported:: pyotp.parse_uri('otpauth://totp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXP&issuer=Secure%20App') >>> pyotp.parse_uri('otpauth://hotp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXP&issuer=Secure%20App&counter=0' >>> Working example ~~~~~~~~~~~~~~~ Scan the following barcode with your phone's OTP app (e.g. Google Authenticator): .. image:: https://chart.apis.google.com/chart?cht=qr&chs=250x250&chl=otpauth%3A%2F%2Ftotp%2Falice%40google.com%3Fsecret%3DJBSWY3DPEHPK3PXP Now run the following and compare the output:: import pyotp totp = pyotp.TOTP("JBSWY3DPEHPK3PXP") print("Current OTP:", totp.now()) Third-party contributions ~~~~~~~~~~~~~~~~~~~~~~~~~ The following third-party contributions are not described by a standard, not officially supported, and provided for reference only: * ``pyotp.contrib.Steam()``: An implementation of Steam TOTP. Uses the same API as `pyotp.TOTP()`. Links ~~~~~ * `Project home page (GitHub) `_ * `Documentation `_ * `Package distribution (PyPI) `_ * `Change log `_ * `RFC 4226: HOTP: An HMAC-Based One-Time Password `_ * `RFC 6238: TOTP: Time-Based One-Time Password Algorithm `_ * `ROTP `_ - Original Ruby OTP library by `Mark Percival `_ * `OTPHP `_ - PHP port of ROTP by `Le Lag `_ * `OWASP Authentication Cheat Sheet `_ * `NIST SP 800-63-3: Digital Authentication Guideline `_ For new applications: * `WebAuthn `_ * `PyWARP `_ Versioning ~~~~~~~~~~ This package follows the `Semantic Versioning 2.0.0 `_ standard. To control changes, it is recommended that application developers pin the package version and manage it using `pip-tools `_ or similar. For library developers, pinning the major version is recommended. .. image:: https://github.com/pyauth/pyotp/workflows/Python%20package/badge.svg :target: https://github.com/pyauth/pyotp/actions .. image:: https://img.shields.io/codecov/c/github/pyauth/pyotp/master.svg :target: https://codecov.io/github/pyauth/pyotp?branch=master .. image:: https://img.shields.io/pypi/v/pyotp.svg :target: https://pypi.python.org/pypi/pyotp .. image:: https://img.shields.io/pypi/l/pyotp.svg :target: https://pypi.python.org/pypi/pyotp .. image:: https://readthedocs.org/projects/pyotp/badge/?version=latest :target: https://pyotp.readthedocs.io/ ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1686874945.0 pyotp-2.9.0/README.rst0000644000076600000240000002047300000000000016473 0ustar00andrey.kislyukstaff00000000000000PyOTP - The Python One-Time Password Library ============================================ PyOTP is a Python library for generating and verifying one-time passwords. It can be used to implement two-factor (2FA) or multi-factor (MFA) authentication methods in web applications and in other systems that require users to log in. Open MFA standards are defined in `RFC 4226 `_ (HOTP: An HMAC-Based One-Time Password Algorithm) and in `RFC 6238 `_ (TOTP: Time-Based One-Time Password Algorithm). PyOTP implements server-side support for both of these standards. Client-side support can be enabled by sending authentication codes to users over SMS or email (HOTP) or, for TOTP, by instructing users to use `Google Authenticator `_, `Authy `_, or another compatible app. Users can set up auth tokens in their apps easily by using their phone camera to scan `otpauth:// `_ QR codes provided by PyOTP. Implementers should read and follow the `HOTP security requirements `_ and `TOTP security considerations `_ sections of the relevant RFCs. At minimum, application implementers should follow this checklist: - Ensure transport confidentiality by using HTTPS - Ensure HOTP/TOTP secret confidentiality by storing secrets in a controlled access database - Deny replay attacks by rejecting one-time passwords that have been used by the client (this requires storing the most recently authenticated timestamp, OTP, or hash of the OTP in your database, and rejecting the OTP when a match is seen) - Throttle (rate limit) brute-force attacks against your application's login functionality (see RFC 4226, section 7.3) - When implementing a "greenfield" application, consider supporting `FIDO U2F `_/`WebAuthn `_ in addition to HOTP/TOTP. U2F uses asymmetric cryptography to avoid using a shared secret design, which strengthens your MFA solution against server-side attacks. Hardware U2F also sequesters the client secret in a dedicated single-purpose device, which strengthens your clients against client-side attacks. And by automating scoping of credentials to relying party IDs (application origin/domain names), U2F adds protection against phishing attacks. One implementation of FIDO U2F/WebAuthn is PyOTP's sister project, `PyWARP `_. We also recommend that implementers read the `OWASP Authentication Cheat Sheet `_ and `NIST SP 800-63-3: Digital Authentication Guideline `_ for a high level overview of authentication best practices. Quick overview of using One Time Passwords on your phone -------------------------------------------------------- * OTPs involve a shared secret, stored both on the phone and the server * OTPs can be generated on a phone without internet connectivity * OTPs should always be used as a second factor of authentication (if your phone is lost, you account is still secured with a password) * Google Authenticator and other OTP client apps allow you to store multiple OTP secrets and provision those using a QR Code Installation ------------ :: pip install pyotp Usage ----- Time-based OTPs ~~~~~~~~~~~~~~~ :: import pyotp import time totp = pyotp.TOTP('base32secret3232') totp.now() # => '492039' # OTP verified for current time totp.verify('492039') # => True time.sleep(30) totp.verify('492039') # => False Counter-based OTPs ~~~~~~~~~~~~~~~~~~ :: import pyotp hotp = pyotp.HOTP('base32secret3232') hotp.at(0) # => '260182' hotp.at(1) # => '055283' hotp.at(1401) # => '316439' # OTP verified with a counter hotp.verify('316439', 1401) # => True hotp.verify('316439', 1402) # => False Generating a Secret Key ~~~~~~~~~~~~~~~~~~~~~~~ A helper function is provided to generate a 32-character base32 secret, compatible with Google Authenticator and other OTP apps:: pyotp.random_base32() Some applications want the secret key to be formatted as a hex-encoded string:: pyotp.random_hex() # returns a 40-character hex-encoded secret Google Authenticator Compatible ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PyOTP works with the Google Authenticator iPhone and Android app, as well as other OTP apps like Authy. PyOTP includes the ability to generate provisioning URIs for use with the QR Code scanner built into these MFA client apps:: pyotp.totp.TOTP('JBSWY3DPEHPK3PXP').provisioning_uri(name='alice@google.com', issuer_name='Secure App') >>> 'otpauth://totp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXP&issuer=Secure%20App' pyotp.hotp.HOTP('JBSWY3DPEHPK3PXP').provisioning_uri(name="alice@google.com", issuer_name="Secure App", initial_count=0) >>> 'otpauth://hotp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXP&issuer=Secure%20App&counter=0' This URL can then be rendered as a QR Code (for example, using https://github.com/soldair/node-qrcode) which can then be scanned and added to the users list of OTP credentials. Parsing these URLs is also supported:: pyotp.parse_uri('otpauth://totp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXP&issuer=Secure%20App') >>> pyotp.parse_uri('otpauth://hotp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXP&issuer=Secure%20App&counter=0' >>> Working example ~~~~~~~~~~~~~~~ Scan the following barcode with your phone's OTP app (e.g. Google Authenticator): .. image:: https://chart.apis.google.com/chart?cht=qr&chs=250x250&chl=otpauth%3A%2F%2Ftotp%2Falice%40google.com%3Fsecret%3DJBSWY3DPEHPK3PXP Now run the following and compare the output:: import pyotp totp = pyotp.TOTP("JBSWY3DPEHPK3PXP") print("Current OTP:", totp.now()) Third-party contributions ~~~~~~~~~~~~~~~~~~~~~~~~~ The following third-party contributions are not described by a standard, not officially supported, and provided for reference only: * ``pyotp.contrib.Steam()``: An implementation of Steam TOTP. Uses the same API as `pyotp.TOTP()`. Links ~~~~~ * `Project home page (GitHub) `_ * `Documentation `_ * `Package distribution (PyPI) `_ * `Change log `_ * `RFC 4226: HOTP: An HMAC-Based One-Time Password `_ * `RFC 6238: TOTP: Time-Based One-Time Password Algorithm `_ * `ROTP `_ - Original Ruby OTP library by `Mark Percival `_ * `OTPHP `_ - PHP port of ROTP by `Le Lag `_ * `OWASP Authentication Cheat Sheet `_ * `NIST SP 800-63-3: Digital Authentication Guideline `_ For new applications: * `WebAuthn `_ * `PyWARP `_ Versioning ~~~~~~~~~~ This package follows the `Semantic Versioning 2.0.0 `_ standard. To control changes, it is recommended that application developers pin the package version and manage it using `pip-tools `_ or similar. For library developers, pinning the major version is recommended. .. image:: https://github.com/pyauth/pyotp/workflows/Python%20package/badge.svg :target: https://github.com/pyauth/pyotp/actions .. image:: https://img.shields.io/codecov/c/github/pyauth/pyotp/master.svg :target: https://codecov.io/github/pyauth/pyotp?branch=master .. image:: https://img.shields.io/pypi/v/pyotp.svg :target: https://pypi.python.org/pypi/pyotp .. image:: https://img.shields.io/pypi/l/pyotp.svg :target: https://pypi.python.org/pypi/pyotp .. image:: https://readthedocs.org/projects/pyotp/badge/?version=latest :target: https://pyotp.readthedocs.io/ ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1686874945.0 pyotp-2.9.0/pyproject.toml0000644000076600000240000000016000000000000017707 0ustar00andrey.kislyukstaff00000000000000[tool.black] line-length = 120 [tool.isort] profile = "black" line_length = 120 [tool.ruff] line-length = 120 ././@PaxHeader0000000000000000000000000000003400000000000011452 xustar000000000000000028 mtime=1690501252.1600897 pyotp-2.9.0/setup.cfg0000644000076600000240000000004600000000000016617 0ustar00andrey.kislyukstaff00000000000000[egg_info] tag_build = tag_date = 0 ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1690501116.0 pyotp-2.9.0/setup.py0000755000076600000240000000304300000000000016513 0ustar00andrey.kislyukstaff00000000000000#!/usr/bin/env python from setuptools import setup setup( name="pyotp", version="2.9.0", url="https://github.com/pyotp/pyotp", project_urls={ "Documentation": "https://pyauth.github.io/pyotp", "Source Code": "https://github.com/pyauth/pyotp", "Issue Tracker": "https://github.com/pyauth/pyotp/issues", "Change Log": "https://github.com/pyauth/pyotp/blob/master/Changes.rst", }, license="MIT License", author="PyOTP contributors", author_email="kislyuk@gmail.com", description="Python One Time Password Library", long_description=open("README.rst").read(), python_requires=">=3.7", install_requires=[], extras_require={ "test": ["coverage", "wheel", "ruff", "mypy"], }, packages=["pyotp", "pyotp.contrib"], package_dir={"": "src"}, package_data={"pyotp": ["py.typed"]}, platforms=["MacOS X", "Posix"], zip_safe=False, test_suite="test", classifiers=[ "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Operating System :: MacOS :: MacOS X", "Operating System :: POSIX", "Programming Language :: Python", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.7", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Topic :: Software Development :: Libraries :: Python Modules", ], ) ././@PaxHeader0000000000000000000000000000003400000000000011452 xustar000000000000000028 mtime=1690501252.1466246 pyotp-2.9.0/src/0000755000076600000240000000000000000000000015565 5ustar00andrey.kislyukstaff00000000000000././@PaxHeader0000000000000000000000000000003300000000000011451 xustar000000000000000027 mtime=1690501252.154266 pyotp-2.9.0/src/pyotp/0000755000076600000240000000000000000000000016740 5ustar00andrey.kislyukstaff00000000000000././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1690501060.0 pyotp-2.9.0/src/pyotp/__init__.py0000644000076600000240000000732000000000000021053 0ustar00andrey.kislyukstaff00000000000000import hashlib from re import split from typing import Any, Dict, Sequence from urllib.parse import parse_qsl, unquote, urlparse from . import contrib # noqa:F401 from .compat import random from .hotp import HOTP as HOTP from .otp import OTP as OTP from .totp import TOTP as TOTP def random_base32(length: int = 32, chars: Sequence[str] = list("ABCDEFGHIJKLMNOPQRSTUVWXYZ234567")) -> str: # Note: the otpauth scheme DOES NOT use base32 padding for secret lengths not divisible by 8. # Some third-party tools have bugs when dealing with such secrets. # We might consider warning the user when generating a secret of length not divisible by 8. if length < 32: raise ValueError("Secrets should be at least 160 bits") return "".join(random.choice(chars) for _ in range(length)) def random_hex(length: int = 40, chars: Sequence[str] = list("ABCDEF0123456789")) -> str: if length < 40: raise ValueError("Secrets should be at least 160 bits") return random_base32(length=length, chars=chars) def parse_uri(uri: str) -> OTP: """ Parses the provisioning URI for the OTP; works for either TOTP or HOTP. See also: https://github.com/google/google-authenticator/wiki/Key-Uri-Format :param uri: the hotp/totp URI to parse :returns: OTP object """ # Secret (to be filled in later) secret = None # Encoder (to be filled in later) encoder = None # Digits (to be filled in later) digits = None # Data we'll parse to the correct constructor otp_data: Dict[str, Any] = {} # Parse with URLlib parsed_uri = urlparse(unquote(uri)) if parsed_uri.scheme != "otpauth": raise ValueError("Not an otpauth URI") # Parse issuer/accountname info accountinfo_parts = split(":|%3A", parsed_uri.path[1:], maxsplit=1) if len(accountinfo_parts) == 1: otp_data["name"] = accountinfo_parts[0] else: otp_data["issuer"] = accountinfo_parts[0] otp_data["name"] = accountinfo_parts[1] # Parse values for key, value in parse_qsl(parsed_uri.query): if key == "secret": secret = value elif key == "issuer": if "issuer" in otp_data and otp_data["issuer"] is not None and otp_data["issuer"] != value: raise ValueError("If issuer is specified in both label and parameters, it should be equal.") otp_data["issuer"] = value elif key == "algorithm": if value == "SHA1": otp_data["digest"] = hashlib.sha1 elif value == "SHA256": otp_data["digest"] = hashlib.sha256 elif value == "SHA512": otp_data["digest"] = hashlib.sha512 else: raise ValueError("Invalid value for algorithm, must be SHA1, SHA256 or SHA512") elif key == "encoder": encoder = value elif key == "digits": digits = int(value) otp_data["digits"] = digits elif key == "period": otp_data["interval"] = int(value) elif key == "counter": otp_data["initial_count"] = int(value) elif key != "image": raise ValueError("{} is not a valid parameter".format(key)) if encoder != "steam": if digits is not None and digits not in [6, 7, 8]: raise ValueError("Digits may only be 6, 7, or 8") if not secret: raise ValueError("No secret found in URI") # Create objects if encoder == "steam": return contrib.Steam(secret, **otp_data) if parsed_uri.netloc == "totp": return TOTP(secret, **otp_data) elif parsed_uri.netloc == "hotp": return HOTP(secret, **otp_data) raise ValueError("Not a supported OTP type") ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1639042081.0 pyotp-2.9.0/src/pyotp/compat.py0000644000076600000240000000032100000000000020571 0ustar00andrey.kislyukstaff00000000000000# Use secrets module if available (Python version >= 3.6) per PEP 506 try: from secrets import SystemRandom # type: ignore except ImportError: from random import SystemRandom random = SystemRandom() ././@PaxHeader0000000000000000000000000000003300000000000011451 xustar000000000000000027 mtime=1690501252.158217 pyotp-2.9.0/src/pyotp/contrib/0000755000076600000240000000000000000000000020400 5ustar00andrey.kislyukstaff00000000000000././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1662994414.0 pyotp-2.9.0/src/pyotp/contrib/__init__.py0000644000076600000240000000004600000000000022511 0ustar00andrey.kislyukstaff00000000000000from .steam import Steam # noqa:F401 ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1690501060.0 pyotp-2.9.0/src/pyotp/contrib/steam.py0000644000076600000240000000260200000000000022063 0ustar00andrey.kislyukstaff00000000000000import hashlib from typing import Optional from ..totp import TOTP STEAM_CHARS = "23456789BCDFGHJKMNPQRTVWXY" # steam's custom alphabet STEAM_DEFAULT_DIGITS = 5 # Steam TOTP code length class Steam(TOTP): """ Steam's custom TOTP. Subclass of `pyotp.totp.TOTP`. """ def __init__( self, s: str, name: Optional[str] = None, issuer: Optional[str] = None, interval: int = 30, digits: int = 5 ) -> None: """ :param s: secret in base32 format :param interval: the time interval in seconds for OTP. This defaults to 30. :param name: account name :param issuer: issuer """ self.interval = interval super().__init__(s=s, digits=10, digest=hashlib.sha1, name=name, issuer=issuer) def generate_otp(self, input: int) -> str: """ :param input: the HMAC counter value to use as the OTP input. Usually either the counter, or the computed integer based on the Unix timestamp """ str_code = super().generate_otp(input) int_code = int(str_code) steam_code = "" total_chars = len(STEAM_CHARS) for _ in range(STEAM_DEFAULT_DIGITS): pos = int_code % total_chars char = STEAM_CHARS[int(pos)] steam_code += char int_code //= total_chars return steam_code ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1677960194.0 pyotp-2.9.0/src/pyotp/hotp.py0000644000076600000240000000516000000000000020266 0ustar00andrey.kislyukstaff00000000000000import hashlib from typing import Any, Optional from . import utils from .otp import OTP class HOTP(OTP): """ Handler for HMAC-based OTP counters. """ def __init__( self, s: str, digits: int = 6, digest: Any = None, name: Optional[str] = None, issuer: Optional[str] = None, initial_count: int = 0, ) -> None: """ :param s: secret in base32 format :param initial_count: starting HMAC counter value, defaults to 0 :param digits: number of integers in the OTP. Some apps expect this to be 6 digits, others support more. :param digest: digest function to use in the HMAC (expected to be SHA1) :param name: account name :param issuer: issuer """ if digest is None: digest = hashlib.sha1 self.initial_count = initial_count super().__init__(s=s, digits=digits, digest=digest, name=name, issuer=issuer) def at(self, count: int) -> str: """ Generates the OTP for the given count. :param count: the OTP HMAC counter :returns: OTP """ return self.generate_otp(self.initial_count + count) def verify(self, otp: str, counter: int) -> bool: """ Verifies the OTP passed in against the current counter OTP. :param otp: the OTP to check against :param counter: the OTP HMAC counter """ return utils.strings_equal(str(otp), str(self.at(counter))) def provisioning_uri( self, name: Optional[str] = None, initial_count: Optional[int] = None, issuer_name: Optional[str] = None, image: Optional[str] = None, ) -> str: """ Returns the provisioning URI for the OTP. This can then be encoded in a QR Code and used to provision an OTP app like Google Authenticator. See also: https://github.com/google/google-authenticator/wiki/Key-Uri-Format :param name: name of the user account :param initial_count: starting HMAC counter value, defaults to 0 :param issuer_name: the name of the OTP issuer; this will be the organization title of the OTP entry in Authenticator :returns: provisioning URI """ return utils.build_uri( self.secret, name=name if name else self.name, initial_count=initial_count if initial_count else self.initial_count, issuer=issuer_name if issuer_name else self.issuer, algorithm=self.digest().name, digits=self.digits, image=image, ) ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1690501057.0 pyotp-2.9.0/src/pyotp/otp.py0000644000076600000240000000425600000000000020123 0ustar00andrey.kislyukstaff00000000000000import base64 import hashlib import hmac from typing import Any, Optional class OTP(object): """ Base class for OTP handlers. """ def __init__( self, s: str, digits: int = 6, digest: Any = hashlib.sha1, name: Optional[str] = None, issuer: Optional[str] = None, ) -> None: self.digits = digits if digits > 10: raise ValueError("digits must be no greater than 10") self.digest = digest self.secret = s self.name = name or "Secret" self.issuer = issuer def generate_otp(self, input: int) -> str: """ :param input: the HMAC counter value to use as the OTP input. Usually either the counter, or the computed integer based on the Unix timestamp """ if input < 0: raise ValueError("input must be positive integer") hasher = hmac.new(self.byte_secret(), self.int_to_bytestring(input), self.digest) hmac_hash = bytearray(hasher.digest()) offset = hmac_hash[-1] & 0xF code = ( (hmac_hash[offset] & 0x7F) << 24 | (hmac_hash[offset + 1] & 0xFF) << 16 | (hmac_hash[offset + 2] & 0xFF) << 8 | (hmac_hash[offset + 3] & 0xFF) ) str_code = str(10_000_000_000 + (code % 10**self.digits)) return str_code[-self.digits :] def byte_secret(self) -> bytes: secret = self.secret missing_padding = len(secret) % 8 if missing_padding != 0: secret += "=" * (8 - missing_padding) return base64.b32decode(secret, casefold=True) @staticmethod def int_to_bytestring(i: int, padding: int = 8) -> bytes: """ Turns an integer to the OATH specified bytestring, which is fed to the HMAC along with the secret """ result = bytearray() while i != 0: result.append(i & 0xFF) i >>= 8 # It's necessary to convert the final result from bytearray to bytes # because the hmac functions in python 2.6 and 3.3 don't work with # bytearray return bytes(bytearray(reversed(result)).rjust(padding, b"\0")) ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1639042081.0 pyotp-2.9.0/src/pyotp/py.typed0000644000076600000240000000000000000000000020425 0ustar00andrey.kislyukstaff00000000000000././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1677960194.0 pyotp-2.9.0/src/pyotp/totp.py0000644000076600000240000001000000000000000020267 0ustar00andrey.kislyukstaff00000000000000import calendar import datetime import hashlib import time from typing import Any, Optional, Union from . import utils from .otp import OTP class TOTP(OTP): """ Handler for time-based OTP counters. """ def __init__( self, s: str, digits: int = 6, digest: Any = None, name: Optional[str] = None, issuer: Optional[str] = None, interval: int = 30, ) -> None: """ :param s: secret in base32 format :param interval: the time interval in seconds for OTP. This defaults to 30. :param digits: number of integers in the OTP. Some apps expect this to be 6 digits, others support more. :param digest: digest function to use in the HMAC (expected to be SHA1) :param name: account name :param issuer: issuer """ if digest is None: digest = hashlib.sha1 self.interval = interval super().__init__(s=s, digits=digits, digest=digest, name=name, issuer=issuer) def at(self, for_time: Union[int, datetime.datetime], counter_offset: int = 0) -> str: """ Accepts either a Unix timestamp integer or a datetime object. To get the time until the next timecode change (seconds until the current OTP expires), use this instead: .. code:: python totp = pyotp.TOTP(...) time_remaining = totp.interval - datetime.datetime.now().timestamp() % totp.interval :param for_time: the time to generate an OTP for :param counter_offset: the amount of ticks to add to the time counter :returns: OTP value """ if not isinstance(for_time, datetime.datetime): for_time = datetime.datetime.fromtimestamp(int(for_time)) return self.generate_otp(self.timecode(for_time) + counter_offset) def now(self) -> str: """ Generate the current time OTP :returns: OTP value """ return self.generate_otp(self.timecode(datetime.datetime.now())) def verify(self, otp: str, for_time: Optional[datetime.datetime] = None, valid_window: int = 0) -> bool: """ Verifies the OTP passed in against the current time OTP. :param otp: the OTP to check against :param for_time: Time to check OTP at (defaults to now) :param valid_window: extends the validity to this many counter ticks before and after the current one :returns: True if verification succeeded, False otherwise """ if for_time is None: for_time = datetime.datetime.now() if valid_window: for i in range(-valid_window, valid_window + 1): if utils.strings_equal(str(otp), str(self.at(for_time, i))): return True return False return utils.strings_equal(str(otp), str(self.at(for_time))) def provisioning_uri( self, name: Optional[str] = None, issuer_name: Optional[str] = None, image: Optional[str] = None ) -> str: """ Returns the provisioning URI for the OTP. This can then be encoded in a QR Code and used to provision an OTP app like Google Authenticator. See also: https://github.com/google/google-authenticator/wiki/Key-Uri-Format """ return utils.build_uri( self.secret, name if name else self.name, issuer=issuer_name if issuer_name else self.issuer, algorithm=self.digest().name, digits=self.digits, period=self.interval, image=image, ) def timecode(self, for_time: datetime.datetime) -> int: """ Accepts either a timezone naive (`for_time.tzinfo is None`) or a timezone aware datetime as argument and returns the corresponding counter value (timecode). """ if for_time.tzinfo: return int(calendar.timegm(for_time.utctimetuple()) / self.interval) else: return int(time.mktime(for_time.timetuple()) / self.interval) ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1677960194.0 pyotp-2.9.0/src/pyotp/utils.py0000644000076600000240000000606000000000000020454 0ustar00andrey.kislyukstaff00000000000000import unicodedata from hmac import compare_digest from typing import Dict, Optional, Union from urllib.parse import quote, urlencode, urlparse def build_uri( secret: str, name: str, initial_count: Optional[int] = None, issuer: Optional[str] = None, algorithm: Optional[str] = None, digits: Optional[int] = None, period: Optional[int] = None, image: Optional[str] = None, ) -> str: """ Returns the provisioning URI for the OTP; works for either TOTP or HOTP. This can then be encoded in a QR Code and used to provision the Google Authenticator app. For module-internal use. See also: https://github.com/google/google-authenticator/wiki/Key-Uri-Format :param secret: the hotp/totp secret used to generate the URI :param name: name of the account :param initial_count: starting counter value, defaults to None. If none, the OTP type will be assumed as TOTP. :param issuer: the name of the OTP issuer; this will be the organization title of the OTP entry in Authenticator :param algorithm: the algorithm used in the OTP generation. :param digits: the length of the OTP generated code. :param period: the number of seconds the OTP generator is set to expire every code. :param image: optional logo image url :returns: provisioning uri """ # initial_count may be 0 as a valid param is_initial_count_present = initial_count is not None # Handling values different from defaults is_algorithm_set = algorithm is not None and algorithm != "sha1" is_digits_set = digits is not None and digits != 6 is_period_set = period is not None and period != 30 otp_type = "hotp" if is_initial_count_present else "totp" base_uri = "otpauth://{0}/{1}?{2}" url_args: Dict[str, Union[None, int, str]] = {"secret": secret} label = quote(name) if issuer is not None: label = quote(issuer) + ":" + label url_args["issuer"] = issuer if is_initial_count_present: url_args["counter"] = initial_count if is_algorithm_set: url_args["algorithm"] = algorithm.upper() # type: ignore if is_digits_set: url_args["digits"] = digits if is_period_set: url_args["period"] = period if image: image_uri = urlparse(image) if image_uri.scheme != "https" or not image_uri.netloc or not image_uri.path: raise ValueError("{} is not a valid url".format(image_uri)) url_args["image"] = image uri = base_uri.format(otp_type, label, urlencode(url_args).replace("+", "%20")) return uri def strings_equal(s1: str, s2: str) -> bool: """ Timing-attack resistant string comparison. Normal comparison using == will short-circuit on the first mismatching character. This avoids that by scanning the whole string, though we still reveal to a timing attack whether the strings are the same length. """ s1 = unicodedata.normalize("NFKC", s1) s2 = unicodedata.normalize("NFKC", s2) return compare_digest(s1.encode("utf-8"), s2.encode("utf-8")) ././@PaxHeader0000000000000000000000000000003400000000000011452 xustar000000000000000028 mtime=1690501252.1574738 pyotp-2.9.0/src/pyotp.egg-info/0000755000076600000240000000000000000000000020432 5ustar00andrey.kislyukstaff00000000000000././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1690501252.0 pyotp-2.9.0/src/pyotp.egg-info/PKG-INFO0000644000076600000240000002272400000000000021536 0ustar00andrey.kislyukstaff00000000000000Metadata-Version: 2.1 Name: pyotp Version: 2.9.0 Summary: Python One Time Password Library Home-page: https://github.com/pyotp/pyotp Author: PyOTP contributors Author-email: kislyuk@gmail.com License: MIT License Project-URL: Documentation, https://pyauth.github.io/pyotp Project-URL: Source Code, https://github.com/pyauth/pyotp Project-URL: Issue Tracker, https://github.com/pyauth/pyotp/issues Project-URL: Change Log, https://github.com/pyauth/pyotp/blob/master/Changes.rst Platform: MacOS X Platform: Posix Classifier: Intended Audience :: Developers Classifier: License :: OSI Approved :: MIT License Classifier: Operating System :: MacOS :: MacOS X Classifier: Operating System :: POSIX Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.7 Classifier: Programming Language :: Python :: 3.8 Classifier: Programming Language :: Python :: 3.9 Classifier: Programming Language :: Python :: 3.10 Classifier: Programming Language :: Python :: 3.11 Classifier: Topic :: Software Development :: Libraries :: Python Modules Requires-Python: >=3.7 Provides-Extra: test License-File: LICENSE PyOTP - The Python One-Time Password Library ============================================ PyOTP is a Python library for generating and verifying one-time passwords. It can be used to implement two-factor (2FA) or multi-factor (MFA) authentication methods in web applications and in other systems that require users to log in. Open MFA standards are defined in `RFC 4226 `_ (HOTP: An HMAC-Based One-Time Password Algorithm) and in `RFC 6238 `_ (TOTP: Time-Based One-Time Password Algorithm). PyOTP implements server-side support for both of these standards. Client-side support can be enabled by sending authentication codes to users over SMS or email (HOTP) or, for TOTP, by instructing users to use `Google Authenticator `_, `Authy `_, or another compatible app. Users can set up auth tokens in their apps easily by using their phone camera to scan `otpauth:// `_ QR codes provided by PyOTP. Implementers should read and follow the `HOTP security requirements `_ and `TOTP security considerations `_ sections of the relevant RFCs. At minimum, application implementers should follow this checklist: - Ensure transport confidentiality by using HTTPS - Ensure HOTP/TOTP secret confidentiality by storing secrets in a controlled access database - Deny replay attacks by rejecting one-time passwords that have been used by the client (this requires storing the most recently authenticated timestamp, OTP, or hash of the OTP in your database, and rejecting the OTP when a match is seen) - Throttle (rate limit) brute-force attacks against your application's login functionality (see RFC 4226, section 7.3) - When implementing a "greenfield" application, consider supporting `FIDO U2F `_/`WebAuthn `_ in addition to HOTP/TOTP. U2F uses asymmetric cryptography to avoid using a shared secret design, which strengthens your MFA solution against server-side attacks. Hardware U2F also sequesters the client secret in a dedicated single-purpose device, which strengthens your clients against client-side attacks. And by automating scoping of credentials to relying party IDs (application origin/domain names), U2F adds protection against phishing attacks. One implementation of FIDO U2F/WebAuthn is PyOTP's sister project, `PyWARP `_. We also recommend that implementers read the `OWASP Authentication Cheat Sheet `_ and `NIST SP 800-63-3: Digital Authentication Guideline `_ for a high level overview of authentication best practices. Quick overview of using One Time Passwords on your phone -------------------------------------------------------- * OTPs involve a shared secret, stored both on the phone and the server * OTPs can be generated on a phone without internet connectivity * OTPs should always be used as a second factor of authentication (if your phone is lost, you account is still secured with a password) * Google Authenticator and other OTP client apps allow you to store multiple OTP secrets and provision those using a QR Code Installation ------------ :: pip install pyotp Usage ----- Time-based OTPs ~~~~~~~~~~~~~~~ :: import pyotp import time totp = pyotp.TOTP('base32secret3232') totp.now() # => '492039' # OTP verified for current time totp.verify('492039') # => True time.sleep(30) totp.verify('492039') # => False Counter-based OTPs ~~~~~~~~~~~~~~~~~~ :: import pyotp hotp = pyotp.HOTP('base32secret3232') hotp.at(0) # => '260182' hotp.at(1) # => '055283' hotp.at(1401) # => '316439' # OTP verified with a counter hotp.verify('316439', 1401) # => True hotp.verify('316439', 1402) # => False Generating a Secret Key ~~~~~~~~~~~~~~~~~~~~~~~ A helper function is provided to generate a 32-character base32 secret, compatible with Google Authenticator and other OTP apps:: pyotp.random_base32() Some applications want the secret key to be formatted as a hex-encoded string:: pyotp.random_hex() # returns a 40-character hex-encoded secret Google Authenticator Compatible ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PyOTP works with the Google Authenticator iPhone and Android app, as well as other OTP apps like Authy. PyOTP includes the ability to generate provisioning URIs for use with the QR Code scanner built into these MFA client apps:: pyotp.totp.TOTP('JBSWY3DPEHPK3PXP').provisioning_uri(name='alice@google.com', issuer_name='Secure App') >>> 'otpauth://totp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXP&issuer=Secure%20App' pyotp.hotp.HOTP('JBSWY3DPEHPK3PXP').provisioning_uri(name="alice@google.com", issuer_name="Secure App", initial_count=0) >>> 'otpauth://hotp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXP&issuer=Secure%20App&counter=0' This URL can then be rendered as a QR Code (for example, using https://github.com/soldair/node-qrcode) which can then be scanned and added to the users list of OTP credentials. Parsing these URLs is also supported:: pyotp.parse_uri('otpauth://totp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXP&issuer=Secure%20App') >>> pyotp.parse_uri('otpauth://hotp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXP&issuer=Secure%20App&counter=0' >>> Working example ~~~~~~~~~~~~~~~ Scan the following barcode with your phone's OTP app (e.g. Google Authenticator): .. image:: https://chart.apis.google.com/chart?cht=qr&chs=250x250&chl=otpauth%3A%2F%2Ftotp%2Falice%40google.com%3Fsecret%3DJBSWY3DPEHPK3PXP Now run the following and compare the output:: import pyotp totp = pyotp.TOTP("JBSWY3DPEHPK3PXP") print("Current OTP:", totp.now()) Third-party contributions ~~~~~~~~~~~~~~~~~~~~~~~~~ The following third-party contributions are not described by a standard, not officially supported, and provided for reference only: * ``pyotp.contrib.Steam()``: An implementation of Steam TOTP. Uses the same API as `pyotp.TOTP()`. Links ~~~~~ * `Project home page (GitHub) `_ * `Documentation `_ * `Package distribution (PyPI) `_ * `Change log `_ * `RFC 4226: HOTP: An HMAC-Based One-Time Password `_ * `RFC 6238: TOTP: Time-Based One-Time Password Algorithm `_ * `ROTP `_ - Original Ruby OTP library by `Mark Percival `_ * `OTPHP `_ - PHP port of ROTP by `Le Lag `_ * `OWASP Authentication Cheat Sheet `_ * `NIST SP 800-63-3: Digital Authentication Guideline `_ For new applications: * `WebAuthn `_ * `PyWARP `_ Versioning ~~~~~~~~~~ This package follows the `Semantic Versioning 2.0.0 `_ standard. To control changes, it is recommended that application developers pin the package version and manage it using `pip-tools `_ or similar. For library developers, pinning the major version is recommended. .. image:: https://github.com/pyauth/pyotp/workflows/Python%20package/badge.svg :target: https://github.com/pyauth/pyotp/actions .. image:: https://img.shields.io/codecov/c/github/pyauth/pyotp/master.svg :target: https://codecov.io/github/pyauth/pyotp?branch=master .. image:: https://img.shields.io/pypi/v/pyotp.svg :target: https://pypi.python.org/pypi/pyotp .. image:: https://img.shields.io/pypi/l/pyotp.svg :target: https://pypi.python.org/pypi/pyotp .. image:: https://readthedocs.org/projects/pyotp/badge/?version=latest :target: https://pyotp.readthedocs.io/ ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1690501252.0 pyotp-2.9.0/src/pyotp.egg-info/SOURCES.txt0000644000076600000240000000070000000000000022313 0ustar00andrey.kislyukstaff00000000000000LICENSE MANIFEST.in README.rst pyproject.toml setup.py test.py src/pyotp/__init__.py src/pyotp/compat.py src/pyotp/hotp.py src/pyotp/otp.py src/pyotp/py.typed src/pyotp/totp.py src/pyotp/utils.py src/pyotp.egg-info/PKG-INFO src/pyotp.egg-info/SOURCES.txt src/pyotp.egg-info/dependency_links.txt src/pyotp.egg-info/not-zip-safe src/pyotp.egg-info/requires.txt src/pyotp.egg-info/top_level.txt src/pyotp/contrib/__init__.py src/pyotp/contrib/steam.py././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1690501252.0 pyotp-2.9.0/src/pyotp.egg-info/dependency_links.txt0000644000076600000240000000000100000000000024500 0ustar00andrey.kislyukstaff00000000000000 ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1639042325.0 pyotp-2.9.0/src/pyotp.egg-info/not-zip-safe0000644000076600000240000000000100000000000022660 0ustar00andrey.kislyukstaff00000000000000 ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1690501252.0 pyotp-2.9.0/src/pyotp.egg-info/requires.txt0000644000076600000240000000004100000000000023025 0ustar00andrey.kislyukstaff00000000000000 [test] coverage wheel ruff mypy ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1690501252.0 pyotp-2.9.0/src/pyotp.egg-info/top_level.txt0000644000076600000240000000000600000000000023160 0ustar00andrey.kislyukstaff00000000000000pyotp ././@PaxHeader0000000000000000000000000000002600000000000011453 xustar000000000000000022 mtime=1690501060.0 pyotp-2.9.0/test.py0000755000076600000240000004762000000000000016343 0ustar00andrey.kislyukstaff00000000000000#!/usr/bin/env python import base64 import datetime import hashlib import os import sys import unittest from urllib.parse import parse_qsl, urlparse from warnings import warn sys.path.insert(0, os.path.join(os.path.dirname(__file__), "src")) import pyotp # noqa class HOTPExampleValuesFromTheRFC(unittest.TestCase): def test_match_rfc(self): # 12345678901234567890 in Bas32 # GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ hotp = pyotp.HOTP("GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ") self.assertEqual(hotp.at(0), "755224") self.assertEqual(hotp.at(1), "287082") self.assertEqual(hotp.at(2), "359152") self.assertEqual(hotp.at(3), "969429") self.assertEqual(hotp.at(4), "338314") self.assertEqual(hotp.at(5), "254676") self.assertEqual(hotp.at(6), "287922") self.assertEqual(hotp.at(7), "162583") self.assertEqual(hotp.at(8), "399871") self.assertEqual(hotp.at(9), "520489") def test_invalid_input(self): hotp = pyotp.HOTP("GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ") with self.assertRaises(ValueError): hotp.at(-1) def test_verify_otp_reuse(self): hotp = pyotp.HOTP("GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ") self.assertTrue(hotp.verify("520489", 9)) self.assertFalse(hotp.verify("520489", 10)) self.assertFalse(hotp.verify("520489", 10)) def test_provisioning_uri(self): hotp = pyotp.HOTP("wrn3pqx5uqxqvnqr", name="mark@percival") url = urlparse(hotp.provisioning_uri()) self.assertEqual(url.scheme, "otpauth") self.assertEqual(url.netloc, "hotp") self.assertEqual(url.path, "/mark%40percival") self.assertEqual(dict(parse_qsl(url.query)), {"secret": "wrn3pqx5uqxqvnqr", "counter": "0"}) self.assertEqual(hotp.provisioning_uri(), pyotp.parse_uri(hotp.provisioning_uri()).provisioning_uri()) hotp = pyotp.HOTP("wrn3pqx5uqxqvnqr", name="mark@percival", initial_count=12) url = urlparse(hotp.provisioning_uri()) self.assertEqual(url.scheme, "otpauth") self.assertEqual(url.netloc, "hotp") self.assertEqual(url.path, "/mark%40percival") self.assertEqual(dict(parse_qsl(url.query)), {"secret": "wrn3pqx5uqxqvnqr", "counter": "12"}) self.assertEqual(hotp.provisioning_uri(), pyotp.parse_uri(hotp.provisioning_uri()).provisioning_uri()) hotp = pyotp.HOTP("wrn3pqx5uqxqvnqr", name="mark@percival", issuer="FooCorp!") url = urlparse(hotp.provisioning_uri()) self.assertEqual(url.scheme, "otpauth") self.assertEqual(url.netloc, "hotp") self.assertEqual(url.path, "/FooCorp%21:mark%40percival") self.assertEqual( dict(parse_qsl(url.query)), {"secret": "wrn3pqx5uqxqvnqr", "counter": "0", "issuer": "FooCorp!"} ) self.assertEqual(hotp.provisioning_uri(), pyotp.parse_uri(hotp.provisioning_uri()).provisioning_uri()) key = "c7uxuqhgflpw7oruedmglbrk7u6242vb" hotp = pyotp.HOTP(key, digits=8, digest=hashlib.sha256, name="baco@peperina", issuer="FooCorp") url = urlparse(hotp.provisioning_uri()) self.assertEqual(url.scheme, "otpauth") self.assertEqual(url.netloc, "hotp") self.assertEqual(url.path, "/FooCorp:baco%40peperina") self.assertEqual( dict(parse_qsl(url.query)), { "secret": "c7uxuqhgflpw7oruedmglbrk7u6242vb", "counter": "0", "issuer": "FooCorp", "digits": "8", "algorithm": "SHA256", }, ) self.assertEqual(hotp.provisioning_uri(), pyotp.parse_uri(hotp.provisioning_uri()).provisioning_uri()) hotp = pyotp.HOTP(key, digits=8, name="baco@peperina", issuer="Foo Corp", initial_count=10) url = urlparse(hotp.provisioning_uri()) self.assertEqual(url.scheme, "otpauth") self.assertEqual(url.netloc, "hotp") self.assertEqual(url.path, "/Foo%20Corp:baco%40peperina") self.assertEqual( dict(parse_qsl(url.query)), {"secret": "c7uxuqhgflpw7oruedmglbrk7u6242vb", "counter": "10", "issuer": "Foo Corp", "digits": "8"}, ) self.assertEqual(hotp.provisioning_uri(), pyotp.parse_uri(hotp.provisioning_uri()).provisioning_uri()) code = pyotp.totp.TOTP("S46SQCPPTCNPROMHWYBDCTBZXV") self.assertEqual(code.provisioning_uri(), "otpauth://totp/Secret?secret=S46SQCPPTCNPROMHWYBDCTBZXV") code.verify("123456") self.assertEqual(code.provisioning_uri(), "otpauth://totp/Secret?secret=S46SQCPPTCNPROMHWYBDCTBZXV") def test_other_secret(self): hotp = pyotp.HOTP("N3OVNIBRERIO5OHGVCMDGS4V4RJ3AUZOUN34J6FRM4P6JIFCG3ZA") self.assertEqual(hotp.at(0), "737863") self.assertEqual(hotp.at(1), "390601") self.assertEqual(hotp.at(2), "363354") self.assertEqual(hotp.at(3), "936780") self.assertEqual(hotp.at(4), "654019") class TOTPExampleValuesFromTheRFC(unittest.TestCase): RFC_VALUES = { (hashlib.sha1, b"12345678901234567890"): ( (59, "94287082"), (1111111109, "07081804"), (1111111111, "14050471"), (1234567890, "89005924"), (2000000000, "69279037"), (20000000000, "65353130"), ), (hashlib.sha256, b"12345678901234567890123456789012"): ( (59, 46119246), (1111111109, "68084774"), (1111111111, "67062674"), (1234567890, "91819424"), (2000000000, "90698825"), (20000000000, "77737706"), ), (hashlib.sha512, b"1234567890123456789012345678901234567890123456789012345678901234"): ( (59, 90693936), (1111111109, "25091201"), (1111111111, "99943326"), (1234567890, "93441116"), (2000000000, "38618901"), (20000000000, "47863826"), ), } def test_match_rfc(self): for digest, secret in self.RFC_VALUES: totp = pyotp.TOTP(base64.b32encode(secret), 8, digest) for utime, code in self.RFC_VALUES[(digest, secret)]: if utime > sys.maxsize: warn( "32-bit platforms use native functions to handle timestamps, so they fail this test" + " (and will fail after 19 January 2038)" ) continue value = totp.at(utime) msg = "%s != %s (%s, time=%d)" msg %= (value, code, digest().name, utime) self.assertEqual(value, str(code), msg) def test_match_rfc_digit_length(self): totp = pyotp.TOTP("GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ") self.assertEqual(totp.at(1111111111), "050471") self.assertEqual(totp.at(1234567890), "005924") self.assertEqual(totp.at(2000000000), "279037") def test_match_google_authenticator_output(self): totp = pyotp.TOTP("wrn3pqx5uqxqvnqr") with Timecop(1297553958): self.assertEqual(totp.now(), "102705") def test_validate_totp(self): totp = pyotp.TOTP("wrn3pqx5uqxqvnqr") with Timecop(1297553958): self.assertTrue(totp.verify("102705")) self.assertTrue(totp.verify("102705")) with Timecop(1297553958 + 30): self.assertFalse(totp.verify("102705")) def test_input_before_epoch(self): totp = pyotp.TOTP("GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ") # -1 and -29.5 round down to 0 (epoch) self.assertEqual(totp.at(-1), "755224") self.assertEqual(totp.at(-29.5), "755224") with self.assertRaises(ValueError): totp.at(-30) def test_validate_totp_with_digit_length(self): totp = pyotp.TOTP("GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ") with Timecop(1111111111): self.assertTrue(totp.verify("050471")) with Timecop(1297553958 + 30): self.assertFalse(totp.verify("050471")) def test_provisioning_uri(self): totp = pyotp.TOTP("wrn3pqx5uqxqvnqr", name="mark@percival") url = urlparse(totp.provisioning_uri()) self.assertEqual(url.scheme, "otpauth") self.assertEqual(url.netloc, "totp") self.assertEqual(url.path, "/mark%40percival") self.assertEqual(dict(parse_qsl(url.query)), {"secret": "wrn3pqx5uqxqvnqr"}) self.assertEqual(totp.provisioning_uri(), pyotp.parse_uri(totp.provisioning_uri()).provisioning_uri()) totp = pyotp.TOTP("wrn3pqx5uqxqvnqr", name="mark@percival", issuer="FooCorp!") url = urlparse(totp.provisioning_uri()) self.assertEqual(url.scheme, "otpauth") self.assertEqual(url.netloc, "totp") self.assertEqual(url.path, "/FooCorp%21:mark%40percival") self.assertEqual(dict(parse_qsl(url.query)), {"secret": "wrn3pqx5uqxqvnqr", "issuer": "FooCorp!"}) self.assertEqual(totp.provisioning_uri(), pyotp.parse_uri(totp.provisioning_uri()).provisioning_uri()) key = "c7uxuqhgflpw7oruedmglbrk7u6242vb" totp = pyotp.TOTP(key, digits=8, interval=60, digest=hashlib.sha256, name="baco@peperina", issuer="FooCorp") url = urlparse(totp.provisioning_uri()) self.assertEqual(url.scheme, "otpauth") self.assertEqual(url.netloc, "totp") self.assertEqual(url.path, "/FooCorp:baco%40peperina") self.assertEqual( dict(parse_qsl(url.query)), { "secret": "c7uxuqhgflpw7oruedmglbrk7u6242vb", "issuer": "FooCorp", "digits": "8", "period": "60", "algorithm": "SHA256", }, ) self.assertEqual(totp.provisioning_uri(), pyotp.parse_uri(totp.provisioning_uri()).provisioning_uri()) totp = pyotp.TOTP(key, digits=8, interval=60, name="baco@peperina", issuer="FooCorp") url = urlparse(totp.provisioning_uri()) self.assertEqual(url.scheme, "otpauth") self.assertEqual(url.netloc, "totp") self.assertEqual(url.path, "/FooCorp:baco%40peperina") self.assertEqual( dict(parse_qsl(url.query)), {"secret": "c7uxuqhgflpw7oruedmglbrk7u6242vb", "issuer": "FooCorp", "digits": "8", "period": "60"}, ) self.assertEqual(totp.provisioning_uri(), pyotp.parse_uri(totp.provisioning_uri()).provisioning_uri()) totp = pyotp.TOTP(key, digits=8, name="baco@peperina", issuer="FooCorp") url = urlparse(totp.provisioning_uri()) self.assertEqual(url.scheme, "otpauth") self.assertEqual(url.netloc, "totp") self.assertEqual(url.path, "/FooCorp:baco%40peperina") self.assertEqual( dict(parse_qsl(url.query)), {"secret": "c7uxuqhgflpw7oruedmglbrk7u6242vb", "issuer": "FooCorp", "digits": "8"}, ) self.assertEqual(totp.provisioning_uri(), pyotp.parse_uri(totp.provisioning_uri()).provisioning_uri()) def test_random_key_generation(self): self.assertEqual(len(pyotp.random_base32()), 32) self.assertEqual(len(pyotp.random_base32(length=34)), 34) self.assertEqual(len(pyotp.random_hex()), 40) self.assertEqual(len(pyotp.random_hex(length=42)), 42) with self.assertRaises(ValueError): pyotp.random_base32(length=31) with self.assertRaises(ValueError): pyotp.random_hex(length=39) class SteamTOTP(unittest.TestCase): def test_match_examples(self): steam = pyotp.contrib.Steam("BASE32SECRET3232") self.assertEqual(steam.at(0), "2TC8B") self.assertEqual(steam.at(30), "YKKK4") self.assertEqual(steam.at(60), "M4HQB") self.assertEqual(steam.at(90), "DTVB3") steam = pyotp.contrib.Steam("FMXNK4QEGKVPULRTADY6JIDK5VHUBGZW") self.assertEqual(steam.at(0), "C5V56") self.assertEqual(steam.at(30), "QJY8Y") self.assertEqual(steam.at(60), "R3WQY") self.assertEqual(steam.at(90), "JG3T3") def test_verify(self): steam = pyotp.contrib.Steam("BASE32SECRET3232") with Timecop(1662883100): self.assertTrue(steam.verify("N3G63")) with Timecop(1662883100 + 30): self.assertFalse(steam.verify("N3G63")) with Timecop(946681223): self.assertTrue(steam.verify("7VP3X")) with Timecop(946681223 + 30): self.assertFalse(steam.verify("7VP3X")) steam = pyotp.contrib.Steam("FMXNK4QEGKVPULRTADY6JIDK5VHUBGZW") with Timecop(1662884261): self.assertTrue(steam.verify("V6WKJ")) with Timecop(1662884261 + 30): self.assertFalse(steam.verify("V6WKJ")) with Timecop(946681223): self.assertTrue(steam.verify("4MK54")) with Timecop(946681223 + 30): self.assertFalse(steam.verify("4MK54")) class CompareDigestTest(unittest.TestCase): method = staticmethod(pyotp.utils.compare_digest) def test_comparisons(self): self.assertTrue(self.method("", "")) self.assertTrue(self.method("a", "a")) self.assertTrue(self.method("a" * 1000, "a" * 1000)) self.assertFalse(self.method("", "a")) self.assertFalse(self.method("a", "")) self.assertFalse(self.method("a" * 999 + "b", "a" * 1000)) class StringComparisonTest(CompareDigestTest): method = staticmethod(pyotp.utils.strings_equal) def test_fullwidth_input(self): self.assertTrue(self.method("ｘs１２３45", "xs12345")) def test_unicode_equal(self): self.assertTrue(self.method("ěšč45", "ěšč45")) class CounterOffsetTest(unittest.TestCase): def test_counter_offset(self): totp = pyotp.TOTP("ABCDEFGH") self.assertEqual(totp.at(200), "028307") self.assertTrue(totp.at(200, 1), "681610") class ValidWindowTest(unittest.TestCase): def test_valid_window(self): totp = pyotp.TOTP("ABCDEFGH") self.assertTrue(totp.verify("451564", 200, 1)) self.assertTrue(totp.verify("028307", 200, 1)) self.assertTrue(totp.verify("681610", 200, 1)) self.assertFalse(totp.verify("195979", 200, 1)) class ParseUriTest(unittest.TestCase): def test_invalids(self): with self.assertRaises(ValueError) as cm: pyotp.parse_uri("http://hello.com") self.assertEqual("Not an otpauth URI", str(cm.exception)) with self.assertRaises(ValueError) as cm: pyotp.parse_uri("otpauth://totp") self.assertEqual("No secret found in URI", str(cm.exception)) with self.assertRaises(ValueError) as cm: pyotp.parse_uri("otpauth://derp?secret=foo") self.assertEqual("Not a supported OTP type", str(cm.exception)) with self.assertRaises(ValueError) as cm: pyotp.parse_uri("otpauth://totp?foo=secret") self.assertEqual("foo is not a valid parameter", str(cm.exception)) with self.assertRaises(ValueError) as cm: pyotp.parse_uri("otpauth://totp?digits=-1") self.assertEqual("Digits may only be 6, 7, or 8", str(cm.exception)) with self.assertRaises(ValueError) as cm: pyotp.parse_uri("otpauth://totp/SomeIssuer:?issuer=AnotherIssuer") self.assertEqual("If issuer is specified in both label and parameters, it should be equal.", str(cm.exception)) with self.assertRaises(ValueError) as cm: pyotp.parse_uri("otpauth://totp?algorithm=aes") self.assertEqual("Invalid value for algorithm, must be SHA1, SHA256 or SHA512", str(cm.exception)) def test_parse_steam(self): otp = pyotp.parse_uri("otpauth://totp/Steam:?secret=SOME_SECRET&encoder=steam") self.assertEqual(type(otp), pyotp.contrib.Steam) otp = pyotp.parse_uri("otpauth://totp/Steam:?secret=SOME_SECRET") self.assertNotEqual(type(otp), pyotp.contrib.Steam) @unittest.skipIf(sys.version_info < (3, 6), "Skipping test that requires deterministic dict key enumeration") def test_algorithms(self): otp = pyotp.parse_uri("otpauth://totp?algorithm=SHA1&secret=GEZDGNBV&algorithm=SHA1") self.assertEqual(hashlib.sha1, otp.digest) self.assertEqual(otp.at(0), "734055") self.assertEqual(otp.at(30), "662488") self.assertEqual(otp.at(60), "289363") self.assertEqual(otp.provisioning_uri(), "otpauth://totp/Secret?secret=GEZDGNBV") self.assertEqual(otp.provisioning_uri(name="n", issuer_name="i"), "otpauth://totp/i:n?secret=GEZDGNBV&issuer=i") otp = pyotp.parse_uri("otpauth://totp?algorithm=SHA1&secret=GEZDGNBV&algorithm=SHA1&period=60") self.assertEqual(hashlib.sha1, otp.digest) self.assertEqual(otp.at(30), "734055") self.assertEqual(otp.at(60), "662488") self.assertEqual( otp.provisioning_uri(name="n", issuer_name="i"), "otpauth://totp/i:n?secret=GEZDGNBV&issuer=i&period=60" ) otp = pyotp.parse_uri("otpauth://hotp?algorithm=SHA1&secret=GEZDGNBV&algorithm=SHA1") self.assertEqual(hashlib.sha1, otp.digest) self.assertEqual(otp.at(0), "734055") self.assertEqual(otp.at(1), "662488") self.assertEqual(otp.at(2), "289363") self.assertEqual( otp.provisioning_uri(name="n", issuer_name="i"), "otpauth://hotp/i:n?secret=GEZDGNBV&issuer=i&counter=0" ) otp = pyotp.parse_uri("otpauth://hotp?algorithm=SHA1&secret=GEZDGNBV&algorithm=SHA1&counter=1") self.assertEqual(hashlib.sha1, otp.digest) self.assertEqual(otp.at(0), "662488") self.assertEqual(otp.at(1), "289363") self.assertEqual( otp.provisioning_uri(name="n", issuer_name="i"), "otpauth://hotp/i:n?secret=GEZDGNBV&issuer=i&counter=1" ) otp = pyotp.parse_uri("otpauth://totp?algorithm=SHA1&secret=GEZDGNBV&algorithm=SHA256") self.assertEqual(hashlib.sha256, otp.digest) self.assertEqual(otp.at(0), "918961") self.assertEqual(otp.at(9000), "934470") otp = pyotp.parse_uri("otpauth://totp?algorithm=SHA1&secret=GEZDGNBV&algorithm=SHA512") self.assertEqual(hashlib.sha512, otp.digest) self.assertEqual(otp.at(0), "816660") self.assertEqual(otp.at(9000), "524153") self.assertEqual( otp.provisioning_uri(name="n", issuer_name="i", image="https://test.net/test.png"), "otpauth://totp/i:n?secret=GEZDGNBV&issuer=i&algorithm=SHA512&image=https%3A%2F%2Ftest.net%2Ftest.png", ) with self.assertRaises(ValueError): otp.provisioning_uri(name="n", issuer_name="i", image="nourl") otp = pyotp.parse_uri(otp.provisioning_uri(name="n", issuer_name="i", image="https://test.net/test.png")) self.assertEqual(hashlib.sha512, otp.digest) otp = pyotp.parse_uri("otpauth://totp/Steam:?secret=FMXNK4QEGKVPULRTADY6JIDK5VHUBGZW&encoder=steam") self.assertEqual(type(otp), pyotp.contrib.Steam) self.assertEqual(otp.at(0), "C5V56") self.assertEqual(otp.at(30), "QJY8Y") self.assertEqual(otp.at(60), "R3WQY") self.assertEqual(otp.at(90), "JG3T3") # period and digits should be ignored otp = pyotp.parse_uri("otpauth://totp/Steam:?secret=FMXNK4QEGKVPULRTADY6JIDK5VHUBGZW&period=15&digits=7&encoder=steam") self.assertEqual(type(otp), pyotp.contrib.Steam) self.assertEqual(otp.at(0), "C5V56") self.assertEqual(otp.at(30), "QJY8Y") self.assertEqual(otp.at(60), "R3WQY") self.assertEqual(otp.at(90), "JG3T3") class Timecop(object): """ Half-assed clone of timecop.rb, just enough to pass our tests. """ def __init__(self, freeze_timestamp): self.freeze_timestamp = freeze_timestamp def __enter__(self): self.real_datetime = datetime.datetime datetime.datetime = self.frozen_datetime() def __exit__(self, type, value, traceback): datetime.datetime = self.real_datetime def frozen_datetime(self): class FrozenDateTime(datetime.datetime): @classmethod def now(cls, **kwargs): return cls.fromtimestamp(timecop.freeze_timestamp) timecop = self return FrozenDateTime if __name__ == "__main__": unittest.main()