# Module Netmech_digest_http.Digest

    module Digest: Nethttp.HTTP_CLIENT_MECHANISM

This is the standard HTTP digest authentication mechanism (see RFCs 2069, 2617, 7616). The hash functions MD5 and SHA-256 are supported, in server preference.

This version does not include mutual authentication, i.e. it does not matter what the server responds in the Authentication-Info header.

There is no support for the "auth-int" level of protection.

How to use with `Nethttp_client`: The handlers `Nethttp_client.unified_auth_handler` and `Nethttp_client.digest_auth_handler` wrap this mechanism already. Additionally, there is also the option of plugging in this module directly. For this, you need the adapter `Nethttp_client.generic_auth_handler`, e.g.

      let m = ( module Netmech_digest_http.Digest )
      let h = new Nethttp_client.generic_auth_handler key_ring [ m ]
      http_pipeline # add_auth_handler h

Get `key_ring` by instantiating `Nethttp_client.key_ring`.

Note that the key ring must use UTF-8 encoding (although the Digest protocol might need to recode to ISO-8859-1 - note that authentication will fail if this is not possible).

    val mechanism_name : string

    val available : unit -> bool

Whether the mechanism is available, in particular whether the required crypto support is linked in

    val restart_supported : bool

Whether the mechanism supports quick restarts (re-authentication)

    type credentials

    val init_credentials : (string * string * (string * string) list) list ->
           credentials

Supply the mechanism with credentials. These are given as list `(type,value,params)`. The mechanism may pick any element of this list which are considered as equivalent.

Types are defined per mechanism. All mechanisms understand the "password" type, which is just the cleartext password, e.g.

                [ "password", "ThE sEcReT", [] ]

The password is encoded in UTF-8. However, note that not all protocols are able to transmit all of UTF-8. If a non-transmittable character is found, the authentication will fail.

The password can have parameters:

- "realm": the password is only applicable to this realm. The realm parameter should only occur once.
- "domain-uri": the password is only applicable to this URI space. The URI must include the protocol scheme, the host name, and "/" as path. The port number is optional. Example: "http://localhost/". The domain-uri parameter can occur several times.

    val client_match : params:(string * string * bool) list ->
           Nethttp.Header.auth_challenge -> Nethttp.match_result

Checks whether this mechanism can accept the initial authentication challenge (i.e. the first challenge sent from the server to the client. The `params` are as for `create_client_session`. On success, returns ``Accept(realm,id_opt)`. On failure, returns ``Reject`. This function usually does not raise exceptions.

If the mechanism does not support the notion of realms, a dummy realm should be returned.

The `id_opt` is the session ID (if supported). Session IDs can be used to bind reauthentications to the original session.

The challenge is from a `www-authenticate` or a `proxy-authenticate` header.

There is also the result ``Reroute(realm, trans_id)`, meaning that the request would be acceptable if it came over the transport identified by `trans_id`. ``Accept_reroute` is the combination of accepting and rerouting, i.e. the auth protocol can start, but the second request should go over the other transport. Both ``Reroute` and ``Accept_reroute` are only allowed for initial challenges.

    type client_session

    val client_state : client_session ->
           Netsys_sasl_types.client_state

    val create_client_session : user:string ->
           creds:credentials ->
           params:(string * string * bool) list ->
           unit -> client_session

The new client session authenticate as `user`. The credentials are `creds`.

`user` must be encoded in UTF-8.

The parameters are given as list `(name,value,critical)`. Critical parameters must be interpreted by the mechanism, and unknown critical parameters must be rejected by a `Failure` exception. Non-critical parameters are ignored if they are unknown to the mechanism.

Available parameters:

- "realm"
- "id" (if `client_match` returns a session ID)
- "trans_id": the `Nethttp_client.transport_layer_id` of the current HTTP request
- "conn_id": an identifier for the TCP connection
- "https": is set to "true" if the current connection is TLS-secured
- "target-host": the hostname from the HTTP request
- "target-uri": the URL from the HTTP request

    val client_configure_channel_binding : client_session ->
           Netsys_sasl_types.cb -> client_session

Configure GS2-style channel binding

    val client_restart : params:(string * string * bool) list ->
           client_session ->
           client_session

Restart the session for another authentication round. The session must be in state ``OK`. After the restart the session will be in state ``Emit`.

The params are the same as for `create_client_session`, but updated where needed.

    val client_process_challenge : client_session ->
           string ->
           string ->
           #Nethttp.http_header_ro ->
           Nethttp.Header.auth_challenge -> client_session

`client_process_challenge cs method uri header challenge`:

Process the challenge from the server. The state must be ``Wait`. As an exception, this function can also be called for the initial challenge from the server, even if the state is ``Emit`.

`method` is the request method. `uri` is the request URI

    val client_emit_response : client_session ->
           string ->
           string ->
           #Nethttp.http_header_ro ->
           client_session *
           Nethttp.Header.auth_credentials * (string * string) list

`let (creds,new_headers) = client_emit_response cs method uri header`:

Emit a new response as a pair `(creds,new_headers)`. The state must be ``Emit`. The `creds` either go into the `authorization` or `proxy-authorization` header. The `new_headers` are additional headers to modify.

    val client_channel_binding : client_session -> Netsys_sasl_types.cb

Whether the client suggests or demands channel binding

    val client_user_name : client_session -> string

The user name

    val client_stash_session : client_session -> string

Serializes the session as string

    val client_resume_session : string -> client_session

Unserializes the session

    val client_session_id : client_session -> string option

Optionally return a string that can be used to identify the client session. Not all mechanisms support this.

    val client_domain : client_session -> string list

After successful authentication, this function may return the URIs defining the authentication space.

    val client_prop : client_session -> string -> string

Get a mechanism-specific property of the session. Commonly supported keys:

- "realm"
- "domain-uri"

    val client_gssapi_props : client_session -> Netsys_gssapi.client_props

Returns the GSSAPI props if available, or raise `Not_found`