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 -> boolWhether the mechanism is available, in particular whether the required crypto support is linked in
val restart_supported : boolWhether the mechanism supports quick restarts (re-authentication)
type
val init_credentials : (string * string * (string * string) list) list ->
credentialsSupply 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:
val client_match : params:(string * string * bool) list ->
Nethttp.Header.auth_challenge -> Nethttp.match_resultChecks 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
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_sessionThe 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:
client_match returns a session ID)Nethttp_client.transport_layer_id of the
current HTTP requestval client_configure_channel_binding : client_session ->
Netsys_sasl_types.cb -> client_sessionConfigure GS2-style channel binding
val client_restart : params:(string * string * bool) list ->
client_session ->
client_sessionRestart 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_sessionclient_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) listlet (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.cbWhether the client suggests or demands channel binding
val client_user_name : client_session -> stringThe user name
val client_stash_session : client_session -> stringSerializes the session as string
val client_resume_session : string -> client_sessionUnserializes the session
val client_session_id : client_session -> string optionOptionally return a string that can be used to identify the client session. Not all mechanisms support this.
val client_domain : client_session -> string listAfter successful authentication, this function may return the URIs defining the authentication space.
val client_prop : client_session -> string -> stringGet a mechanism-specific property of the session. Commonly supported keys:
val client_gssapi_props : client_session -> Netsys_gssapi.client_propsReturns the GSSAPI props if available, or raise Not_found
