<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
%docentities;
]>

<chapter>
    <title>Frequently Asked Questions</title>

    <qandaset defaultlabel="number">
        <qandaentry>
            <question>
                <para>How does ENS-based authentication work?</para>
            </question>
            <answer>
                <para>
                    The module uses cryptographic signatures to verify ENS domain ownership. 
                    Clients sign a message containing a UUID and timestamp with their private key, 
                    then the module recovers the signer's address and verifies it matches the 
                    current owner of the specified ENS domain.
                </para>
            </answer>
        </qandaentry>

        <qandaentry>
            <question>
                <para>What networks are supported?</para>
            </question>
            <answer>
                <para>
                    <emphasis>Primary Network:</emphasis> Polygon mainnet (default configuration)
                </para>
                <para>
                    <emphasis>Other Supported Networks:</emphasis> Ethereum mainnet, Ethereum Sepolia testnet, 
                    or any EVM-compatible network with ENS contracts deployed.
                </para>
                <para>
                    <emphasis>Configuration:</emphasis> Set the appropriate RPC URL and contract addresses 
                    for your target network in the module parameters.
                </para>
            </answer>
        </qandaentry>

        <qandaentry>
            <question>
                <para>What are the X-Data and X-Sign headers?</para>
            </question>
            <answer>
                <para>
                    <emphasis>X-Data:</emphasis> Contains authentication data in format "UUID:TIMESTAMP" 
                    where UUID is a unique identifier and TIMESTAMP is Unix timestamp when the signature was created.
                </para>
                <para>
                    <emphasis>X-Sign:</emphasis> Contains the Ethereum ECDSA signature of the X-Data value, 
                    signed with the private key corresponding to the ENS domain owner's address.
                </para>
                <para>
                    Example: X-Data: "550e8400-e29b-41d4-a716-446655440000:1640995200", 
                    X-Sign: "0x1b2c3d4e5f6789abcdef..."
                </para>
            </answer>
        </qandaentry>

        <qandaentry>
            <question>
                <para>How does the module handle wrapped ENS domains?</para>
            </question>
            <answer>
                <para>
                    The module automatically detects wrapped ENS domains by first querying the ENS Registry. 
                    If the owner is the Name Wrapper contract address, it then queries the Name Wrapper 
                    contract to find the actual NFT owner. This ensures compatibility with both traditional 
                    and wrapped ENS domains.
                </para>
            </answer>
        </qandaentry>

        <qandaentry>
            <question>
                <para>What happens if the blockchain network is unavailable?</para>
            </question>
            <answer>
                <para>
                    Authentication will fail if the RPC endpoint is unreachable or returns errors. 
                    For production deployments, use reliable RPC providers and consider implementing 
                    fallback authentication mechanisms. The module logs detailed error information 
                    when debug mode is enabled.
                </para>
            </answer>
        </qandaentry>

        <qandaentry>
            <question>
                <para>Do SIP clients need special modifications?</para>
            </question>
            <answer>
                <para>
                    Yes, clients need to be modified to generate the required X-Data and X-Sign headers. 
                    Clients must implement Ethereum message signing functionality and include the 
                    cryptographic signature in SIP requests. Standard SIP digest authentication is not used.
                </para>
            </answer>
        </qandaentry>

        <qandaentry>
            <question>
                <para>How do I troubleshoot authentication failures?</para>
            </question>
            <answer>
                <para>
                    <orderedlist>
                        <listitem><para>Enable debug mode: modparam("auth_arnacon", "debug_mode", 1)</para></listitem>
                        <listitem><para>Check Kamailio logs for detailed error information</para></listitem>
                        <listitem><para>Verify ENS domain ownership on blockchain explorer</para></listitem>
                        <listitem><para>Test RPC endpoint connectivity and response times</para></listitem>
                        <listitem><para>Verify contract addresses are correct for your network</para></listitem>
                        <listitem><para>Check signature format and timestamp validity</para></listitem>
                    </orderedlist>
                </para>
            </answer>
        </qandaentry>

        <qandaentry>
            <question>
                <para>What are the signature timeout considerations?</para>
            </question>
            <answer>
                <para>
                    The signature timeout prevents replay attacks by rejecting signatures older than 
                    the configured timeout (default 30 seconds). Consider network latency and client 
                    clock synchronization when setting this value. Shorter timeouts provide better 
                    security but may cause issues with slow networks or unsynchronized clocks.
                </para>
            </answer>
        </qandaentry>

        <qandaentry>
            <question>
                <para>Is this suitable for production use?</para>
            </question>
            <answer>
                <para>
                    Yes, but consider these factors: blockchain network reliability (use enterprise RPC providers), 
                    latency (blockchain calls add 100-500ms), client implementation complexity (requires 
                    cryptographic capabilities), and monitoring (implement comprehensive health checks).
                </para>
                <para>
                    <emphasis>Security Considerations:</emphasis> Ensure clients securely manage private keys, 
                    use HTTPS for all RPC endpoints, implement proper timestamp validation, and consider 
                    backup authentication for critical services.
                </para>
            </answer>
        </qandaentry>

        <qandaentry>
            <question>
                <para>What are the performance implications?</para>
            </question>
            <answer>
                <para>
                    Each authentication requires 1-2 blockchain RPC calls (ENS Registry + potentially Name Wrapper), 
                    adding 100-500ms latency compared to database authentication. The module performs cryptographic 
                    operations locally (signature verification) which adds minimal overhead. Use connection pooling 
                    and reliable RPC providers to minimize network impact.
                </para>
            </answer>
        </qandaentry>

        <qandaentry>
            <question>
                <para>Can I use free RPC providers?</para>
            </question>
            <answer>
                <para>
                    Free providers work for development and testing but have rate limits and no SLA guarantees. 
                    For production, use paid providers (Infura, Alchemy, QuickNode) for better reliability, 
                    higher rate limits, and support. Polygon mainnet has several reliable free options for 
                    low-volume production use.
                </para>
                <para>
                    <emphasis>Recommended Providers:</emphasis>
                </para>
                <para>
                    <emphasis>Polygon Mainnet:</emphasis> https://polygon-rpc.com (free), https://rpc.ankr.com/polygon (free)
                </para>
                <para>
                    <emphasis>Ethereum Mainnet:</emphasis> https://mainnet.infura.io/v3/YOUR_KEY (paid), https://eth.drpc.org (free tier)
                </para>
            </answer>
        </qandaentry>

    </qandaset>

</chapter> 
