The Web3 Auth Module

The following modules must be loaded before this module:

External libraries or applications:

The module supports ENS (Ethereum Name Service) authentication with the following features:

The following table compares the authentication functions:

The module implements standard ENS resolution with automatic Name Wrapper detection:

This follows the standard ENS resolution pattern (EIP-137) and supports both wrapped and unwrapped domains across all Ethereum networks.

Common Issues:

Debug Information:

Enable debug mode to see which RPC is used for each call:

modparam("auth_web3", "web3_contract_debug_mode", 1)
            

Look for log messages indicating network usage:

Performs Web3-based authentication for WWW-Authenticate challenges. Verifies SIP digest authentication through blockchain contracts and ENS resolution.

This function extracts digest parameters from the Authorization header, resolves ENS names to wallet addresses, and verifies the digest response on the blockchain.

Parameters:

Return value:

Example:

# REGISTER authentication
if (is_method("REGISTER")) {
    if (!$hdr(Authorization)) {
        www_challenge("$td", "0");
        exit;
    }
    if (web3_www_authenticate("$td", "REGISTER")) {
        # Authentication successful
        save("location");
        exit;
    } else {
        send_reply(401, "Unauthorized");
        exit;
    }
}
            

Performs Web3-based authentication for Proxy-Authenticate challenges. Similar to web3_www_authenticate but for proxy authentication scenarios.

This function works identically to web3_www_authenticate but is designed for proxy authentication flows where Proxy-Authorization headers are used.

Parameters:

Return value:

Example:

# INVITE authentication with proxy auth
if (is_method("INVITE")) {
    if (!$hdr(Authorization)) {
        www_challenge("$fd", "0");
        exit;
    }
    if (web3_proxy_authenticate("$fd", "INVITE")) {
        # Authentication successful
    } else {
        send_reply(407, "Proxy Authentication Required");
        exit;
    }
}
            

RPC URL for the blockchain network (e.g., Oasis Sapphire testnet or mainnet). This parameter specifies the endpoint for blockchain communication.

Default value: None (must be configured)

Example:

modparam("auth_web3", "authentication_rpc_url", "https://testnet.sapphire.oasis.dev")
            

Address of the smart contract that handles authentication verification. This contract must implement the authenticateUser function for digest verification.

Default value: None (must be configured)

Example:

modparam("auth_web3", "authentication_contract_address", "0xE773BB79689379d32Ad1Db839868b6756B493aea")
            

RPC URL for the Ethereum network used for ENS resolution. This should point to an Ethereum mainnet RPC endpoint for ENS name resolution.

Default value: None (must be configured)

Example:

modparam("auth_web3", "ens_rpc_url", "https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY")
            

Address of the ENS registry contract on Ethereum mainnet. This is used for resolving ENS names to wallet addresses.

Default value: 0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e (ENS Registry)

Example:

modparam("auth_web3", "ens_registry_address", "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e")
            

Enable debug logging for blockchain contract interactions. When enabled, detailed logs are generated for debugging purposes.

Default value: 0 (disabled)

Example:

modparam("auth_web3", "contract_debug_mode", 1)
            

Timeout in seconds for blockchain RPC calls. This parameter controls how long to wait for blockchain responses.

Default value: 10 seconds

Example:

modparam("auth_web3", "rpc_timeout", 15)
            

Binds the Web3 authentication API to a module interface structure. This allows other modules to use Web3 authentication functions directly.

Parameters:

Return value:

Example:

#include "web3_auth_api.h"

web3_auth_api_t web3_api;

if (bind_web3_auth(&web3_api) < 0) {
    LM_ERR("Failed to bind Web3 auth API");
    return -1;
}

// Use web3_api.web3_digest_authenticate(...)