Plasma GitLab Archive
Projects Blog Knowledge

 Up  

Module type Nethttp.HTTP_MECHANISM

module type HTTP_MECHANISM = sig .. end
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
Powered by Caml