<!-- Kamailio Pull Request Template -->
<!-- IMPORTANT: - for detailed contributing guidelines, read: https://github.com/kamailio/kamailio/blob/master/.github/CONTRIBUTING.md - pull requests must be done to master branch, unless they are backports of fixes from master branch to a stable branch - backports to stable branches must be done with 'git cherry-pick -x ...' - code is contributed under BSD for core and main components (tm, sl, auth, tls) - code is contributed GPLv2 or a compatible license for the other components - GPL code is contributed with OpenSSL licensing exception -->
#### Pre-Submission Checklist <!-- Go over all points below, and after creating the PR, tick all the checkboxes that apply --> <!-- All points should be verified, otherwise, read the CONTRIBUTING guidelines from above--> <!-- If you're unsure about any of these, don't hesitate to ask on sr-dev mailing list --> - [x] Commit message has the format required by CONTRIBUTING guide - [x] Commits are split per component (core, individual modules, libs, utils, ...) - [x] Each component has a single commit (if not, squash them into one commit) - [x] No commits to README files for modules (changes must be done to docbook files in `doc/` subfolder, the README file is autogenerated)
#### Type Of Change - [ ] Small bug fix (non-breaking change which fixes an issue) - [x] New feature (non-breaking change which adds new functionality) - [ ] Breaking change (fix or feature that would change existing functionality)
#### Checklist: <!-- Go over all points below, and after creating the PR, tick all the checkboxes that apply --> - [x] PR should be backported to stable branches - [x] Tested changes locally - [ ] Related to issue #XXXX (replace XXXX with an open issue number)
#### Description <!-- Describe your changes in detail --> Add auth_web3 module for blockchain-based authentication
This PR introduces a new authentication module that provides blockchain-powered digest authentication via Oasis Sapphire smart contracts while maintaining full compatibility with standard Kamailio auth module functions.
**Key Features:** - Blockchain-based digest authentication via Oasis Sapphire smart contracts - RFC2617 compliant MD5 and SHA-256 digest authentication - Full compatibility with standard auth functions (www_authenticate, proxy_authenticate) - Configurable parameters: web3_rpc_url, web3_contract_address, web3_debug_mode, web3_timeout - Comprehensive error handling for network failures and blockchain connectivity - Nonce management and replay protection identical to traditional auth
**Files Added:** - src/modules/auth_web3/ (complete module with 9 .c files and supporting headers) - Comprehensive documentation in doc/ subfolder - CMakeLists.txt with curl dependency handling
**Testing Summary:** - **Build Verification**: Module compiles successfully with curl dependency - **Load Testing**: Module loads without errors in Kamailio configuration - **Authentication Scenarios**: - Valid credentials: Successful authentication with correct blockchain credentials - Invalid credentials: Proper rejection of wrong passwords (tested with Zoiper) - Network failures: Graceful handling of blockchain RPC connectivity issues - Parameter validation: All module parameters properly validated - **Compatibility Testing**: Full compatibility with existing auth module functions - **Error Handling**: Comprehensive error logging and fallback behavior
**Documentation Status:** - Complete XML documentation in doc/ subfolder - Module parameters documented (auth_web3_params.xml) - Functions documented (auth_web3_functions.xml) - Configuration examples provided - Usage patterns and best practices included
**Limitations:** - Requires external blockchain RPC endpoint (Oasis Sapphire) - Network dependency for authentication (no offline fallback) - Requires curl library for HTTP requests to blockchain - Smart contract must be deployed on target blockchain network - Authentication speed depends on blockchain network response time
**Build System:** - Added to MOD_LIST_UTILS group for proper curl dependency handling - Includes CMakeLists.txt with find_package(CURL REQUIRED)
This module provides a drop-in replacement for traditional authentication while leveraging blockchain technology for credential verification. You can view, comment on, or merge this pull request online at:
https://github.com/kamailio/kamailio/pull/4328
-- Commit Summary --
* auth_web3: initial blockchain authentication module * cmake: add auth_web3 to MOD_LIST_UTILS group
-- File Changes --
M cmake/groups.cmake (4) A src/modules/auth_web3/CMakeLists.txt (9) A src/modules/auth_web3/Makefile (17) A src/modules/auth_web3/README (1229) A src/modules/auth_web3/api.c (324) A src/modules/auth_web3/api.h (170) A src/modules/auth_web3/auth_web3_mod.c (1739) A src/modules/auth_web3/auth_web3_mod.h (54) A src/modules/auth_web3/challenge.c (316) A src/modules/auth_web3/challenge.h (54) A src/modules/auth_web3/doc/Makefile (4) A src/modules/auth_web3/doc/auth_web3.xml (174) A src/modules/auth_web3/doc/auth_web3_faq.xml (174) A src/modules/auth_web3/doc/auth_web3_functions.xml (405) A src/modules/auth_web3/doc/auth_web3_params.xml (922) A src/modules/auth_web3/nc.c (246) A src/modules/auth_web3/nc.h (78) A src/modules/auth_web3/nid.c (96) A src/modules/auth_web3/nid.h (88) A src/modules/auth_web3/nonce.c (460) A src/modules/auth_web3/nonce.h (228) A src/modules/auth_web3/ot_nonce.c (232) A src/modules/auth_web3/ot_nonce.h (83) A src/modules/auth_web3/rfc2617.c (145) A src/modules/auth_web3/rfc2617.h (97) A src/modules/auth_web3/rfc2617_sha256.c (150) A src/modules/auth_web3/rfc2617_sha256.h (71)
-- Patch Links --
https://github.com/kamailio/kamailio/pull/4328.patch https://github.com/kamailio/kamailio/pull/4328.diff
daBatmanCoder left a comment (kamailio/kamailio#4328)
To see this `auth_web3` module in action and test the blockchain authentication functionality:
**Interactive Demo**: [cellact.github.io/oasis-authentication-app](https://cellact.github.io/oasis-authentication-app/) Try the complete authentication system with a user-friendly web interface.
**Complete Documentation & Smart Contracts**: [github.com/cellact/oasis-authentication-hardhat](https://github.com/cellact/oasis-authentication-hardhat) Full implementation details, contract addresses, and integration examples.
**Web Demo Source**: [github.com/cellact/oasis-authentication-app](https://github.com/cellact/oasis-authentication-app) React application demonstrating real-world integration patterns.
### Quick Test Setup: 1. Visit the [live demo](https://cellact.github.io/oasis-authentication-app/) 2. Connect MetaMask to Oasis Sapphire Testnet 3. Register test users and see confidential authentication in action 4. Test against our live SIP server: `mvno.cellact.nl`
The demo uses the same smart contracts that this Kamailio module authenticates against, providing end-to-end verification of the blockchain authentication flow. All user credentials are stored confidentially on Oasis Sapphire - passwords are never visible even to blockchain nodes.
**Contract Addresses (Testnet)**: - Auth Contract: `0xE773BB79689379d32Ad1Db839868b6756B493aea` - MD5 Hasher: `0x578d36D80A17030a8a15549d276a93Ac8BBf194C`
miconda left a comment (kamailio/kamailio#4328)
I haven't had the time for proper review, but at a quick look, a lot of files seem to be copied from auth module. If it is the case, then isn't it possible to reuse functions via intermodule API in the similar way that auth_db uses auth functions?
daBatmanCoder left a comment (kamailio/kamailio#4328)
I haven't had the time for proper review, but at a quick look, a lot of files seem to be copied from auth module. If it is the case, then isn't it possible to reuse functions via intermodule API in the similar way that auth_db uses auth functions?
Our initial approach was to build a **complete drop-in replacement** for `auth.so`.
- Same API and function signatures as the original auth module - Just swap `loadmodule "auth.so"` for `loadmodule "web3_auth.so"` - Keep all the SIP digest auth stuff working, but use blockchain verification instead of passwords - Work with existing Kamailio configs without changes
We understand your response and after seeing how `auth_db` uses the intermodule API makes it clear that **building an extension module** would be a smarter approach.
We're going to refactor our approach and upload an updated version.
henningw left a comment (kamailio/kamailio#4328)
I haven't had the time for proper review, but at a quick look, a lot of files seem to be copied from auth module. If it is the case, then isn't it possible to reuse functions via intermodule API in the similar way that auth_db uses auth functions?
Our initial approach was to build a **complete drop-in replacement** for `auth.so`.
* Same API and function signatures as the original auth module * Just swap `loadmodule "auth.so"` for `loadmodule "web3_auth.so"` * Keep all the SIP digest auth stuff working, but use blockchain verification instead of passwords * Work with existing Kamailio configs without changesWe understand your response and after seeing how `auth_db` uses the intermodule API makes it clear that **building an extension module** would be a smarter approach.
We're going to refactor our approach and upload an updated version.
Thank you, I would also prefer if this module uses using the auth inter-module API. I did a quick look to the code yesterday, but its difficult to review in its current shape with all this duplicated code.
-
Ariana -
Daniel-Constantin Mierla
-
Henning Westerholt
-
Jonathan Kandel