module Digest_mutual:Nethttp.HTTP_CLIENT_MECHANISM
This is the standard HTTP digest authentication mechanism
(see RFCs 2069, 2617, 7616). 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.
You need to explicitly plug in this module into the HTTP client
in order to enable it. See Netmech_digest_http.Digest for details.
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
