README

A simple and lightweight PHP library for generating Time-based One-Time Passwords (TOTP) according to RFC 6238.

Installation

You can install the library using Composer:

composer require contipay/php-totp

Usage

Basic Usage

<?php

require_once 'vendor/autoload.php';

use Contipay\PhpTotp\Totp;

// Initialize with your secret key
$secret = 'JBSWY3DPEHPK3PXP';
$totp = new Totp($secret);

// Get current TOTP code
$code = $totp->now();
echo $code; // Outputs a 6-digit code

Generate New Secret Key

// Generate a new random secret key
$secret = Totp::generateSecret();
$totp = new Totp($secret);

Google Authenticator Integration

// Generate a TOTP URL for Google Authenticator
$totpUrl = $totp->getTotpUrl('user@example.com', 'Your Company Name');

// The URL can be used to generate a QR code
// Format: otpauth://totp/{label}?secret={secret}&issuer={issuer}

Generate a Google QR Code URL

// Generate a Google Charts QR code URL for the TOTP
$qrCodeUrl = $totp->getQrCodeUrl('user@example.com', 'Your Company Name');

// You can embed this URL in an <img> tag in your HTML:
// <img src="$qrCodeUrl" alt="Scan this QR code with Google Authenticator">

Validate TOTP Code

// Validate a TOTP code
$code = '123456'; // The code to validate
$isValid = $totp->validateCode($code);

// You can also specify a time window (default is 1, meaning current and previous interval)
$isValid = $totp->validateCode($code, 2); // Check current, previous, and next interval

Custom Interval

By default, the library uses a 30-second interval. You can customize this when initializing the TOTP object:

// Initialize with a custom interval (in seconds)
$totp = new Totp($secret, 60); // 60-second interval

Features

• Generates TOTP codes according to RFC 6238
• Supports custom time intervals
• Handles Base32 decoding internally
• Generates Google Authenticator compatible TOTP URLs
• Generates Google QR code URLs for easy scanning
• Includes secure random secret key generation
• Validates TOTP codes with configurable time window
• Lightweight and easy to use
• No external dependencies

Requirements

• PHP 7.1 or higher

Security Notes

• Always keep your secret key secure and never expose it in client-side code
• The secret key should be stored securely in your application
• Consider using environment variables or a secure configuration management system for storing secrets
• When generating QR codes, ensure the TOTP URL is transmitted securely
• Use constant-time comparison (hash_equals) for code validation to prevent timing attacks

License

This project is licensed under the MIT License - see the LICENSE file for details.