Did you know ... Search Documentation:
Pack logtalk -- logtalk-3.101.0/docs/handbook/_sources/libraries/http_digest.rst.txt

.. _library_http_digest:

http_digest

This library provides HTTP Digest authentication helpers on top of the normalized HTTP stack.

This library can be used with backend Prolog systems that support unbound integer arithmetic and the sockets library: ECLiPSe, SICStus Prolog, SWI-Prolog, Trealla Prolog, and XVM.

API documentation

Open the `../../apis/library_index.html#http_digest <../../apis/library_index.html#http_digest>`__ link in a web browser.

Loading

To load the library, load the loader.lgt file:

::

| ?- logtalk_load(http_digest(loader)).

Testing

To test this library, load the tester.lgt file:

::

| ?- logtalk_load(http_digest(tester)).

Usage overview

The library provides these public entities:

  • http_digest_verifier_protocol server-side verifier protocol for looking up stored Digest HA1 values
  • http_digest core Digest parsing, generation, request authorization, request protection, challenge building, and Authentication-Info response decoration
  • http_server_core_digest_handler(_, _, _, _) portable handler wrapper that applies Digest protection and response decoration around another object implementing http_handler_protocol
  • http_router_digest_auth(_, _, _) router companion category that protects routes declaring digest_auth/1 metadata and decorates successful protected responses with Authentication-Info
  • http_client_digest_session stateful client helper that preserves cookies and retries once when the server replies with a 401 Digest challenge

    The library design keeps the Digest core object stateless and deterministic. State is kept only where it is operationally useful: in verifier objects supplied by applications and in the optional client-side session helper used for cookie storage.

    The server-side entities are portable across the backends supported by the normalized HTTP library. The http_client_digest_session helper additionally depends on the socket-backed HTTP client stack and is therefore available on the same backends supported by the http_client and http_socket_transport libraries.

    Use http_digest directly when you need explicit control over Digest challenge parsing and request verification:

    ::

    | ?- http_digest::unauthorized_response(Challenge, Response, [realm('private'), nonce_secret('secret')]).

    Wrap a normal handler with http_server_core_digest_handler(_, _, _, _) when you want a portable middleware-style integration point for Digest verification:

    ::

    | ?- Handler = http_server_core_digest_handler(verifier, app_handler, [realm('private'), nonce_secret('secret')], []).

    Use http_router_digest_auth(_, _, _) in router objects importing http_router when you want per-route protection driven by normal route metadata:

    ::

    authorize_routed_request(Request, Action) :- ^^authorize_digest_auth_request(Request, Action).

    response_middleware(digest_authentication_info, add_digest_authentication_info).

    route_metadata(show_secret, [digest_auth([])]).

    Use http_client_digest_session when you need cookie persistence plus automatic retry after a 401 Digest challenge:

    ::

    | ?- http_client_digest_session::open(Session, 'Mufasa', 'Circle Of Life'), http_client_digest_session::get(Session, 'http://127.0.0.1:8080/protected', Response, []), http_client_digest_session::close(Session).

    The current client helper is reactive: it sends the initial request without an Authorization header and retries automatically only after receiving a Digest challenge. This keeps the helper small and avoids maintaining speculative challenge caches inside the client session state.

    For add_authentication_info/4, the nextnonce option accepts three forms:

  • nextnonce(false) omits the nextnonce field
  • nextnonce(true) generates a fresh nonce using nonce_secret/1
  • nextnonce(Nonce) emits the explicit nonce atom verbatim

Current scope

  • deterministic Digest header parsing and generation for challenges, authorizations, and Authentication-Info
  • auth and auth-int quality-of-protection request and response digest computation, with auth-int hashing transfer-decoded entity-body bytes
  • server-side request protection through explicit verifier objects
  • middleware-style handler wrapping for server integration
  • route-level protection and successful-response Authentication-Info decoration through http_router_digest_auth(_, _, _) plus the authorize_routed_request/2 and response_middleware/2 router hooks
  • client-side Digest retry on top of the existing socket-backed transport and cookie-jar support, including https:// URLs when the selected transport parameterization supports secure schemes
  • MD5, SHA-256, and SHA-512-256 based Digest computations through the hashes and hmac libraries; when no algorithm option is provided, the default challenge algorithm remains sha256

Non-implemented features

  • proactive client-side challenge caching across requests
  • shared or persistent nonce replay stores