uthmandev/swift2fa

A secure and easy way to implement Two-Factor Authentication (2FA) with PHP. This library provides an easy-to-use solution for integrating 2FA into your applications, including QR code generation, token verification, and secret key management.

v1.0.2 2024-12-08 08:37 UTC

Requires

• php: ^7.4 || ^8.0
• chillerlan/php-qrcode: dev-main
• paragonie/constant_time_encoding: dev-master
• phpmailer/phpmailer: dev-master
• twilio/sdk: dev-main
• vlucas/phpdotenv: ^5.0

Requires (Dev)

• phpunit/phpunit: ^12.0@dev

MIT

• uthmandev

• php
• security
• Authentication
• qr code
• 2fa
• Two-factor Authentication
• Token verification

README

SWIFT2FA

Easy and Secure 2-Factor Authentication

Overview

Swift2FA is a secure and easy-to-use PHP library for implementing two-factor authentication. It supports various authentication methods, including:

• Authenticator apps (Google Authenticator and others)
• Email authentication via SMTP with PHPMailer
• SMS-based authentication using services like Twilio

Key Features

• Simple integration process
• High-security standards
• Multiple authentication methods
• Built-in encryption for secret keys
• QR code generation
• Flexible time-step settings
• Email and SMS delivery options

Installation

composer require uthmandev/swift2fa

Usage Guide

Basic Setup

use Swift2FA\Swift2FA;

$swift2fa = new Swift2FA();

Key Management

1. Encrypting Keys

// Generate and encrypt a new secret key
$encryptedKey = $swift2fa->encryptKey();

1. Decrypting Keys

// Decrypt a stored encrypted key
$decryptedKey = $swift2fa->decryptKey($encryptedKey);

TOTP Operations

1. Generating TOTP

// Generate a time-based one-time password
$totpCode = $swift2fa->generateTOTP($secret, $timeStep = 30, $codeLength = 6);

1. Validating TOTP

// Validate a user-provided TOTP code
$isValid = $swift2fa->TOTPValidate($userInput, $secret);

QR Code Generation

// Generate a QR code for authenticator apps
$qrCode = $swift2fa->generateQR($userEmail, $decryptedSecret);

Authentication Link Generation

// Generate an otpauth:// link
$authLink = $swift2fa->generatelink($userEmail, $decryptedSecret);

Sending Authentication Codes

1. Via Email

// Send TOTP via email
$swift2fa->Mail(
    mailType: 'SMTP',
    email: '[e-mail]',
    message: 'Your authentication code is: ' . $totpCode,
    name: 'User Name',
    subject: 'Authentication Code'
);

1. Via SMS

// Send TOTP via SMS
$swift2fa->SMS(
    phoneNumber: '[phone]',
    messageBody: 'Your authentication code is: ' . $totpCode,
    name: 'User Name'
);

Configuration

Environment Variables

Create a .env file with the following configurations:

# General Settings
APP_NAME=your_app_name
ENCRYPTION_KEY=your_secure_encryption_key

# Email (SMTP) Settings
HOST=smtp.gmail.com
USER_NAME=[e-mail]
PASSWORD=your_gmail_app_password
PORT=465
SMTP_SECURE=ssl

# SMS (Twilio) Settings
TWILIO_SID=your_twilio_sid
TWILIO_AUTH_TOKEN=your_twilio_auth_token
TWILIO_PHONE_NUMBER=your_twilio_phone_number

Important Notes

1. Security

   • Store encryption keys securely
   • Restrict access to environment files
   • Use HTTPS for all authentication operations

2. TOTP Validation

   • Standard time step is 30 seconds
   • Email TOTP might require longer time steps (e.g., 120 seconds)
   • QR codes should be the primary method for adding TOTP to authenticator apps

3. Authentication Links

   • otpauth:// links won't work in browsers
   • Use QR codes for adding to authenticator apps

Contributing

Contributions are welcome! To contribute:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

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

Contact

• Developer: Uthman Oladele
• Website: dev-utman.vercel.app
• Email: [e-mail]

If you find this project useful, please consider giving it a ⭐ star on GitHub!