This is a custom 2FA (Two-Factor Authentication) middleware for the Fiber web framework. It provides a secure and easy-to-use solution for implementing 2FA in Fiber applications. The middleware supports both HOTP (HMAC-based One-Time Password) and TOTP (Time-based One-Time Password) authentication and offers customizable configuration options.
Warning
This 2FA middleware is still a work in progress and may not be stable for use in production environments (e.g., QR Code Builder), since it is rewritten from scratch with some improvements. Use it with caution and thoroughly test it before deploying to production. It is recommended to use it locally for testing purposes.
Note
This 2FA project was inspired by some QR code systems in my country (e.g., https://qris.id/). However, it is built in a modern way and purely written in Go (which is more secure and can leverage the system easily), rather than the traditional way (where it is written in PHP). More QR code system projects might be implemented in the future (e.g., payment systems through banking similar to https://qris.id/).
The middleware provides the following features:
- Generation and verification of HOTP tokens
- Customizable token length and counter synchronization
- Automatic generation of random secrets if not provided
- Support for various hash algorithms (SHA1, SHA256, SHA512, BLAKE2b, BLAKE3)
- Configurable synchronization window for handling counter desynchronization
- Automatic counter resynchronization based on predefined thresholds
- Dynamic adjustment of synchronization window size based on counter mismatch frequency
Note
Some HOTP implementations here follow the standards defined in RFC 4226. However, they are built on top of modern & advanced cryptographic knowledge and best practices, rather than using outdated or traditional approaches. This is because Go is considered one of the best programming languages for cryptographic implementations, compared to C or C++.
- Generation and verification of TOTP tokens
- Customizable token length and time step size
- Automatic generation of random secrets if not provided
- Support for various hash algorithms (SHA1, SHA256, SHA512, BLAKE2b, BLAKE3)
- Configurable synchronization window for handling time drift
- Automatic token expiration and cleanup
Note
Some TOTP implementations here adhere to the standards defined in RFC 6238. However, they are built on top of modern & advanced cryptographic knowledge and best practices, rather than relying on outdated or traditional methods. This is because Go is considered one of the best programming languages for cryptographic implementations, compared to C or C++.
The notes effectively communicate that the HOTP and TOTP implementations follow the respective RFCs while leveraging modern and advanced cryptographic knowledge and best practices. The emphasis on Go's suitability for cryptographic implementations compared to C or C++ is also clearly stated.
- Support for various storage providers (e.g., in-memory, MongoDB, MySQL, PostgreSQL, Redis, SQLite3)
- Customizable storage configuration
- Secure cookie-based authentication for 2FA validation
- Customizable cookie settings (name, expiration, domain, etc.)
- Configurable redirect URL for 2FA validation
- Ability to skip 2FA for specific paths
- Customizable JSON marshaling and unmarshaling functions
- Support for custom JSON encoding/decoding
- Customizable context key for storing 2FA information
- Ability to skip middleware based on custom logic
- Automatic generation of QR code images for 2FA secret keys
- Customizable QR code path template
- Support for custom QR code images
- Customizable QR code content template
- Configurable QR code recovery level and image size
- Flexible token lookup from various sources (header, query, form, param, cookie)
- Configurable token lookup string format
- Customizable context key for storing 2FA information in the request context
- Ability to retrieve and manage context keys based on account names
- Customizable error handling for unauthorized and internal server errors
- Support for various response formats (plain text, JSON, XML)
- Most bits and Unix timestamps are built using 64-bit integers, capable of representing dates billions of years into the future.
More features and validation capabilities will be added in the future to enhance the middleware's functionality and cater to a wider range of validation scenarios.
- Support Cloud Messaging Gateway (SMS2FA) for local countries (e.g., INDONESIA), which is more capable than 2FA apps
Note
These TODO items will be implemented when the internal components are done, as currently, the project is being rewritten from scratch due to poor ecosystems.
goos: windows
goarch: amd64
pkg: github.com/H0llyW00dzZ/fiber2fa
cpu: AMD Ryzen 9 3900X 12-Core Processor
BenchmarkJSONSonicMiddlewareWithInvalidCookie-24 113605 9290 ns/op 6065 B/op 29 allocs/op
BenchmarkJSONSonicWithValid2FA-24 55086 21073 ns/op 9598 B/op 66 allocs/op
BenchmarkJSONSonicWithValidCookie-24 96120 12311 ns/op 7399 B/op 41 allocs/op
BenchmarkJSONStdLibraryMiddlewareWithInvalidCookie-24 128434 9386 ns/op 6003 B/op 29 allocs/op
BenchmarkJSONStdLibraryMiddlewareWithValid2FA-24 49399 24714 ns/op 8200 B/op 68 allocs/op
BenchmarkJSONStdLibraryWithValidCookie-24 60553 20039 ns/op 7108 B/op 46 allocs/op
Note
The benchmark results are based on the latest version of the middleware (v0.3.0) and were performed on a Windows machine with an AMD Ryzen 9 3900X 12-Core Processor. The results may vary depending on the system configuration and environment.
The benchmark tests cover different scenarios, including:
- Middleware performance with an invalid cookie using the Sonic JSON library
- Middleware performance with a valid 2FA token using the Sonic JSON library
- Middleware performance with a valid cookie using the Sonic JSON library
- Middleware performance with an invalid cookie using the standard library JSON package
- Middleware performance with a valid 2FA token using the standard library JSON package
- Middleware performance with a valid cookie using the standard library JSON package
The benchmark results provide insights into the performance characteristics of the middleware under different conditions and JSON libraries. It's important to consider these results when evaluating the middleware's suitability for specific use cases and performance requirements.
Also note that benchmark results may be updated in the future as the middleware evolves and new versions are released.
Contributions are welcome! If you encounter any issues or have suggestions for improvements, please open an issue or submit a pull request.
This project is licensed under the BSD License.