https://github.com/sakibweb/phtp
PHTP is a PHP Library for handling Time-based One-Time Passwords (TOTP) and other OTP uses
https://github.com/sakibweb/phtp
php php-otp php-totp sakib sakiburrahman sakibweb
Last synced: 3 months ago
JSON representation
PHTP is a PHP Library for handling Time-based One-Time Passwords (TOTP) and other OTP uses
- Host: GitHub
- URL: https://github.com/sakibweb/phtp
- Owner: sakibweb
- License: mit
- Created: 2024-06-12T21:38:15.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-10-21T09:42:24.000Z (8 months ago)
- Last Synced: 2024-10-21T13:48:16.861Z (8 months ago)
- Topics: php, php-otp, php-totp, sakib, sakiburrahman, sakibweb
- Language: PHP
- Homepage:
- Size: 23.4 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# PHTP
## PHTP - PHP Time-based One-Time Password (TOTP) Library
PHTP is a lightweight PHP library for generating and verifying Time-based One-Time Passwords (TOTP) and standard One-Time Passwords (OTP). It's designed to be easy to use and integrate into your PHP applications for enhanced security. PHTP is compatible with popular authenticator apps like Google Authenticator and Microsoft Authenticator.
## Features
* **TOTP and OTP Generation:** Create secure time-based and standard OTPs.
* **OTP Verification:** Verify user-submitted OTPs against the secret key.
* **Customizable OTP Length and Algorithm:** Control the number of digits and hashing algorithm (SHA1, SHA256, SHA512).
* **Time Drift Tolerance (TOTP):** Handle slight time discrepancies between server and client.
* **OTP Expiration (OTP):** Implement time-limited OTPs.
* **URI Generation:** Create setup URIs for easy integration with authenticator apps.
* **Error Handling:** Provides clear error messages for invalid inputs or other issues.
## Installation
Simply include the `PHTP.php` file in your project:
```php
require_once 'PHTP.php';
```
## Usage
### 1. Generating a Secret Key
The first step is to generate a secret key. This key should be stored securely for each user and used for both generating and verifying OTPs.
```php
$keyResult = PHTP::key(24); // Generates a 24-character secret key for TOTP
if ($keyResult['status']) {
$secret = $keyResult['data'];
echo "Secret Key: " . $secret; // Store this securely!
} else {
echo "Error: " . $keyResult['message'];
}
// For OTP mode, specify the mode:
$otpKeyResult = PHTP::key(24, 'OTP');
if ($otpKeyResult['status']) {
$otpSecret = $otpKeyResult['data'];
echo "OTP Secret: ".$otpSecret; // Store this securely for OTP usage
} else {
echo "Error: ".$otpKeyResult['message'];
}
```
The `key()` function takes an optional `$length` parameter (default 24) which must be a multiple of 8 and at least 16. It also takes an optional `$mode` parameter with 'TOTP' as default, or 'OTP'.
### 2. Generating an OTP
Once you have a secret key, you can generate an OTP.
**TOTP:**
```php
$codeResult = PHTP::code($secret); // $secret is the base32 encoded secret key
if ($codeResult['status']) {
$otp = $codeResult['data'];
echo "TOTP: " . $otp;
} else {
echo "Error: " . $codeResult['message'];
}
```
**OTP:**
Requires `PHTM` library. Assuming you have the `PHTM` class, and it handles date/time operations with functions like `setTime` and `calculate`.
```php
$otpCodeResult = PHTP::code($otpSecret, 'OTP'); // $otpSecret from Step 1
if ($otpCodeResult['status']) {
$otp = $otpCodeResult['data'];
echo "OTP: " . $otp;
} else {
echo "Error: " . $otpCodeResult['message'] . ". New OTP: ".$otpCodeResult['data']; // Handle expiry and get new OTP
}
```
**Optional parameters for `code()`:**
* `$mode`: 'TOTP' (default) or 'OTP'.
* `$digits`: The number of digits in the OTP (default 6).
* `$time`: The time interval in seconds for TOTP (default 30). For OTP, it adds this time to the creation time embedded in the `$otpSecret`.
* `$offset`: Time offset in seconds to account for drift (default 0). Use only with `TOTP` mode.
* `$algo`: Hashing algorithm: 'sha1' (default), 'sha256', or 'sha512'.
### 3. Verifying an OTP
To verify a user-submitted OTP:
```php
$userOtp = $_POST['otp']; // Get the OTP from the user
$verifyResult = PHTP::verify($userOtp, $secret); // Or use $otpSecret for OTP mode
if ($verifyResult['status']) {
echo "OTP is valid!";
} else {
echo "Invalid OTP: " . $verifyResult['message'];
// print_r($verifyResult); // Debugging (show returned error if needed).
}
```
The `verify()` function takes the same optional parameters as `code()`: `$mode`, `$digits`, `$time`, `$offset`, and `$algo`. Be sure to use the same parameters for verification that you used for generation.
### 4. Generating a Setup URI
PHTP can generate a URI that can be encoded as a QR code for easy setup with authenticator apps.
```php
$urlResult = PHTP::url('[email protected]', $secret, 6, 30, 'My App'); // TOTP
if ($urlResult['status']) {
$uri = $urlResult['data'];
echo "Setup URI: " . $uri; // Display as QR code or link
} else {
echo "Error: ".$urlResult['message'];
}
```
**Parameters for `url()`:**
* `$account`: The user's account name (e.g., email).
* `$secret`: The base32 encoded secret key.
* `$digits`: OTP length (optional).
* `$time`: Time interval (optional).
* `$issuer`: The name of your app/service (optional).
* `$algo`: The HMAC hash algorithm (optional).
## Error Handling
All PHTP functions return an associative array with the following structure:
```
[
'status' => (bool) true/false indicating success or failure,
'message' => (string) A message describing the result or error,
'data' => (mixed) The generated OTP, secret key, or URI on success, or additional error data on failure.
]
```
Always check the `status` element to determine if the operation was successful.
## Contributing
Contributions are welcome! Please submit pull requests via GitHub at [PHTP GitHub](https://github.com/sakibweb).
## License
This library is open-sourced under the [MIT License](LICENSE).