Module Netmech_digest_http.Digest

module Digest: Nethttp.HTTP_MECHANISM

This is the standard HTTP digest authentication mechanism (see RFC 2069 and 2617). 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: 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 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

This web site is published by Informatikbüro Gerd Stolpmann

Plasma	GitLab	Archive
Projects	Blog	Knowledge