Feature/auth web3 module

[OfficeRon]

Summary

This PR adds a new auth_web3 module that enables Web3-based authentication for OpenSIPS, allowing SIP authentication through blockchain technology and ENS (Ethereum Name Service) resolution.

Details

This is a new feature that addresses the growing need for decentralized authentication in SIP environments. Traditional SIP authentication relies on centralized databases or password files, which creates single points of failure and requires complex user management.

The auth_web3 module solves this by:

• Enabling ENS-based user identification (e.g., alice.eth)
• Verifying authentication through blockchain smart contracts
• Supporting both WWW-Authenticate and Proxy-Authenticate flows
• Maintaining full SIP RFC 3261 compliance

This is particularly valuable for:

• Decentralized communication platforms
• Web3-native applications requiring SIP integration
• Organizations wanting blockchain-based identity verification
• Scenarios requiring tamper-proof authentication records

Solution

The module implements a complete Web3 authentication system:

1. ENS Resolution: Resolves ENS names (e.g., alice.eth) to wallet addresses via Ethereum mainnet
2. Blockchain Verification: Verifies SIP digest authentication responses on Oasis Sapphire blockchain
3. Standard Compliance: Uses standard SIP digest authentication (RFC 3261) - no client changes required
4. Dual Authentication: Supports both WWW-Authenticate and Proxy-Authenticate flows

Technical Implementation:

• web3_www_authenticate() and web3_proxy_authenticate() functions
• ABI-encoded smart contract calls for digest verification
• Keccak256 hashing implementation for blockchain compatibility
• Comprehensive error handling and logging

Configuration Parameters:

• authentication_rpc_url: Oasis Sapphire RPC endpoint
• authentication_contract_address: Smart contract address
• ens_rpc_url: Ethereum mainnet RPC for ENS resolution
• ens_registry_address: ENS registry contract address
• contract_debug_mode: Debug logging control
• rpc_timeout: Blockchain call timeout

Documentation:

• Complete DocBook documentation with examples
• Comprehensive README with setup instructions
• FAQ section addressing common use cases

Compatibility

This module is fully backward compatible:

• No breaking changes: Existing authentication methods continue to work unchanged
• Optional integration: Only affects requests explicitly calling Web3 authentication functions
• Standard SIP compliance: Uses standard digest authentication - no client modifications needed
• Independent operation: Can coexist with traditional auth modules (auth, auth_db, etc.)
• Graceful fallback: If ENS resolution fails, do direct wallet address authentication

Dependencies:

• libcurl (for HTTP RPC calls)
• OpenSSL (for cryptographic operations)
• Both are standard dependencies in most OpenSIPS deployments

Closing issues

This is a new feature submission, not addressing a specific existing issue.

[OfficeRon]

Due to merging conflicts encountered with the previous version of this PR, I have created this new pull request to ensure a clean submission. The previous PR was assigned to @razvancrainea for review, and this updated version incorporates the feedback received during that review process. I hope this mishap wont cause too much trouble for the opensips team.

Changes Made

Based on the feedback received, I have made the following updates to the module:

• Copyright Updates: Changed all copyright headers from individual contributor names to Cellact B.V. to clarify ownership and address copyright concerns.
• Documentation Focus: Updated all documentation and code comments to focus exclusively on OpenSIPS, removing any references to Kamailio to eliminate confusion about the module's target platform.
• Code Cleanup: Removed build artifacts and unnecessary files to ensure a clean submission.

[github-actions]

Any updates here? No progress has been made in the last 30 days, marking as stale.

[sobomax]

Pretty cool, thanks!

[bogdan-iancu]

@OfficeRon , thanks for the PR, I just merged it. While I'm doing all the web hooks for the module docs , let me ask you about the docs you have there. There is the doc directory with the xml files - this results into the README file. You also have the .md doc files there - what is the intention with them and why being separated ? I see no inclusion between the sets of docs (xml and md). I'm asking as the ideally we should have a single doc file / page where the users can access all the info (the xml is converted to html and gets on the web site, while the .md will be visible only on git here).

[OfficeRon]

Thank you very much for merging. I appreciate it a lot!
We were working on a similar module for Kamailio at the same time as this module, their requirements for README's and documentation were a bit different, that's why our one here is also a bit odd, apologies for that.
But, if I understand correctly, you'd like to just have all the documentation in one place (like only in the xml) correct? If so then I agree with you and I'd happily edit the module to fit that.
Shall I open a new PR for the edit? Or is there something else I should do? let me know please!

[razvancrainea]

@OfficeRon Yes, please incorporate the README.md files in the docs/*xml ones - this ensures that the documentation gets properly propagated across all our buids (tars, debian repos, redhat RPMs, etc).

[razvancrainea]

@OfficeRon I tried to create debian and redhat packages for the module too, but it doesn't seem to compile:

api.c:36:20: error: unknown type name ‘web3_auth_api_t’; did you mean ‘auth_api_t’?
   36 | int bind_web3_auth(web3_auth_api_t *api) {
      |                    ^~~~~~~~~~~~~~~
      |                    auth_api_t
auth_web3_mod.c:89:20: error: unknown type name ‘web3_auth_api_t’; did you mean ‘auth_api_t’?
   89 | int bind_web3_auth(web3_auth_api_t *api);
      |                    ^~~~~~~~~~~~~~~
      |                    auth_api_t
make[2]: *** [../../Makefile.rules:29: api.o] Error 1
make[2]: *** Waiting for unfinished jobs....
auth_web3_mod.c:103:38: error: ‘bind_web3_auth’ undeclared here (not in a function); did you mean ‘bind_auth’?
  103 |     {"bind_web3_auth", (cmd_function)bind_web3_auth, {{0, 0, 0}}, 0},
      |                                      ^~~~~~~~~~~~~~
      |                                      bind_auth
make[2]: *** [../../Makefile.rules:29: auth_web3_mod.o] Error 1
ERROR: Building auth_web3 module failed!

Apparently the web3_auth_api_t structure is not defined. I guess it should have been defined in the api.h header, which is currently empty.

I guess I can mock something, but ideally you should add it with your own copyright and customizations. Please advise how to proceed. In the meantime, I've reverted the packaging and prevented the module from compiling.

[OfficeRon]

Thank you so much for the feedback. Ill implement both the full xml and this "web3_auth_api_t not defined" error as soon as possible. Once I do, I will make a new PR. Thank you