# Module Netmech_digest_http.Digest_mutual

    module Digest_mutual: Nethttp.HTTP_MECHANISM

This is the standard HTTP digest authentication mechanism (see RFC 2069 and 2617). This version also authenticates the server by checking the Authentication-Info header which must include the correct `rspauth` parameter. This parameter proves that the server actually knew the password.

Note that mutual authentication does generally not prevent that request data is sent to the server before the authentication succeeds. This includes the header and also the request body (for POST and PUT methods). Because of this it is recommended to ensure that requests not carrying any sensitive data precede those requests that need protection.

See `Netmech_digest_http.Digest` for tips how to use this mechanism.

    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 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 -> unit

Configure GS2-style channel binding

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

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 -> unit

`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 ->
           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`