# Functions

## `web3_www_authenticate(realm, method)`

Verifies credentials using blockchain-based authentication via Web3 smart contract calls with integrated ENS support. Automatically detects ENS names and performs domain ownership validation when applicable. This function operates on Authorization headers and serves as a drop-in replacement for traditional www_authenticate functions.

Use Case: Standard SIP user authentication scenarios including REGISTER, INVITE, and other direct client-to-server authentication flows.

ENS Integration: For usernames containing "." (dot), performs ENS owner validation by querying ENS Registry, handling wrapped domains, and cross-validating with authentication contract wallet addresses.

Parameters:

- realm (string) - Authentication realm. Use $td for REGISTER, $fd for other methods

- method (string, optional) - SIP method. Defaults to request-line method if not set

Return Type: integer

Return codes:

- Positive value - Authentication successful

- -1 - Generic error

- -2 - Invalid credentials/blockchain verification failed

- -3 - Stale nonce

- -4 - No credentials

- -5 - Network timeout

This function can be used from REQUEST_ROUTE.

### web3_www_authenticate usage

    ...
    # Basic Web3 + ENS authentication
    if (!web3_www_authenticate("$fd", "$rm")) {
        www_challenge("$fd", "0");
        exit;
    }
    ...

    ...
    # Enhanced error handling with specific responses
    if (!web3_www_authenticate("$td", "$rm")) {
        switch ($retcode) {
            case -2:
                xlog("L_INFO", "Auth failed for $fU\n");
                www_challenge("$td", "16"); # stale=true
                break;
            case -5:
                xlog("L_ERR", "Network timeout for $fU\n");
                sl_send_reply("503", "Service Unavailable");
                exit;
            default:
                www_challenge("$td", "0");
        }
        exit;
    }
    ...

    ...
    # Log ENS domain authentication
    if ($(fU{s.contains,"."})) {
        xlog("L_INFO", "ENS domain $fU authenticated\n");
    }
    ...

## `web3_proxy_authenticate(realm, method)`

Verifies credentials using blockchain-based authentication via Web3 smart contract calls with ENS support for proxy authentication scenarios. This function operates on Proxy-Authorization headers instead of Authorization headers, making it suitable for proxy server authentication flows. Includes the same ENS integration capabilities as `web3_www_authenticate` and serves as a drop-in replacement for traditional proxy_authenticate functions.

Use Case: Proxy server authentication scenarios where your Kamailio instance acts as a proxy requiring authentication, or when routing through authenticated proxies.

Technical Note: Both functions use the same core authentication logic but differ in the HTTP header type they process - Authorization vs. Proxy-Authorization headers.

Parameters:

- realm (string) - Authentication realm. Use $td for REGISTER, $fd for other methods

- method (string, optional) - SIP method. Defaults to request-line method if not set

Return Type: integer

Return codes: Identical to `web3_www_authenticate`

This function can be used from REQUEST_ROUTE.

### web3_proxy_authenticate usage

    ...
    # Basic proxy authentication
    if (!web3_proxy_authenticate("proxy.domain.com", "$rm")) {
        proxy_challenge("proxy.domain.com", "0");
        exit;
    }
    ...

    ...
    # Proxy routing with ENS awareness and error handling
    route[RELAY] {
        if (!web3_proxy_authenticate("$fd", "$rm")) {
            switch ($retcode) {
                case -5:
                    sl_send_reply("503", "Service Unavailable");
                    exit;
            }
            proxy_challenge("$fd", "0");
            exit;
        }

        # Log ENS user authentication
        if ($(fU{s.contains,"."})) {
            xlog("L_INFO", "ENS user $fU authenticated via proxy\n");
        }
        t_relay();
    }
    ...

## Authentication Function Comparison

Both `web3_www_authenticate` and `web3_proxy_authenticate` provide identical Web3 blockchain authentication and ENS integration capabilities, but differ in their intended use cases and HTTP header processing:

Aspect | web3_www_authenticate | web3_proxy_authenticate
--- | --- | ---
HTTP Header Type | Authorization | Proxy-Authorization
Challenge Function | www_challenge() | proxy_challenge()
Use Case | Direct client authentication | Proxy server authentication
SIP Methods | REGISTER, INVITE, etc. | Proxy routing scenarios
Implementation | HDR_AUTHORIZATION_T | HDR_PROXYAUTH_T

Note: Both functions share identical parameters, return codes, ENS integration features, and Web3 blockchain authentication logic.

## `bind_web3_auth(api)`

Allows other modules to bind to the Web3 authentication API with integrated ENS support. This function provides programmatic access to Web3 authentication functions for other Kamailio modules. The API structure contains core authentication functions that handle both standard Web3 blockchain authentication and automatic ENS validation internally.

Note: This function is intended for use by other Kamailio modules, not configuration scripts.

Parameters:

- api (web3_auth_api_t*) - Pointer to API structure to be populated

API Functions Available:

- digest_authenticate(msg, realm, hdr_type, method) - Core authentication function with ENS support

  Parameters: msg (sip_msg_t*), realm (str*), hdr_type (hdr_types_t), method (str*)

  Return: int (authentication result code - same as web3_www_authenticate)

- check_response(cred, method) - Low-level credential verification function

  Parameters: cred (dig_cred_t*), method (str*)

  Return: int (verification result code)

Note: ENS validation is automatically integrated within the digest_authenticate function when usernames contain "." (dot) characters. Separate ENS functions are not exposed in the current API.

Return Type: integer

Return codes: Identical to `web3_www_authenticate`

This function can be used from MODULE_INIT.

### API usage in C modules

    ...
    #include "modules/auth_web3/api.h"

    web3_auth_api_t auth_web3_api;

    // Module initialization
    if (web3_auth_load_api(&auth_web3_api) != 0) {
        LM_ERR("cannot bind auth_web3 api\n");
        return -1;
    }

    // Use authentication API for WWW authentication
    result = auth_web3_api.digest_authenticate(msg, &realm,
                                              HDR_AUTHORIZATION_T, &method);

    // Use authentication API for Proxy authentication
    result = auth_web3_api.digest_authenticate(msg, &realm,
                                              HDR_PROXYAUTH_T, &method);

    // Low-level credential checking
    result = auth_web3_api.check_response(&credentials, &method);
    ...