tfHttpcUserGetResponseAuthParams

Table of Contents >> Application Reference >> Web Client

#include <trsocket.h>

int tfHttpcUserGetResponseAuthParams	(
	ttHttpcUserConHandle conHandle,
	ttHttpcAuthArgVectorPtrPtr argVecOutPtr
	);

Function Description

If a web request results in a 401 Unauthorized response, the server must supply a WWW-Authenticate header. After calling tfHttpcUserGetResponseHeaders() to retrieve all the response headers, you can call tfHttpcUserGetResponseAuthParams() to get the names and values of the parameters from the WWW-Authenticate header, if available.

A ttHttpcAuthArgVector structure is allocated to hold all parameters in argv style arrays. If this function returns TM_ENOERROR, the caller is responsible for freeing the structure by calling tfHttpcUserFreeObject() with the pointer returned by tfHttpcUserGetResponseAuthParams().

Parameters are returned in the order encountered. Parameter ids (e.g. TM_HTTPC_AUTH_PARAM_REALM) will be supplied for known parameters. If the parameter is unknown the TM_HTTPC_AUTH_PARAM_UNSPEC id is used. The full list of supported parameters is shown in the Authentication Header Parameter Ids section below.

The Basic and Digest tokens from the WWW-Authenticate header are included in case the server supplies multiple challenges in one WWW-Authenticate header or multiple WWW-Authenticate headers. The respective parameter ids are TM_HTTPC_AUTH_PARAM_BASIC and TM_HTTPC_AUTH_PARAM_DIGEST. These parameters have no values.

For Basic Authentication, the WWW-Authenticate header contains the realm of the resource that the user has requested. The user is then required to supply a valid username and password for the realm in a subsequent request for the same resource. See RFC 2617, section 2. A sample Basic challenge from a 401 server response:

WWW-Authenticate: Basic realm="WallyWorld"

For Digest Authentication, the WWW-Authenticate header contains the realm, nonce and possibly other information pertaining to the requested entity. The user is then required to build and send a valid response by combining the information supplied in the WWW-Authenticate header with a valid username and password. See RFC 2617, section 3.2. A sample Digest challenge from a 401 server response:

WWW-Authenticate: Digest realm="testrealm@host.com", qop="auth,auth-int",
    nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", opaque="5ccc069c403ebaf9f0171e9517f40e41"

Note:

This function requires the WWW-Authenticate header. You must call tfHttpcUserRegisterResponseHeader() with either TM_HTTP_HEADER_WWW_AUTHENTICATE or TM_HTTP_HEADER_ALL.

If the user's request includes the correct authentication information, the server will not return a WWW-Authenticate header in the response and this function will return TM_ENOENT, in this case.

This function will be present, unless you have uncommented both TM_DISABLE_HTTPC_BASIC_AUTH and TM_DISABLE_HTTPC_DIGEST_AUTH macros in your trsystem.h.

Authentication Header Parameter Ids

From ttHttpcAuthParam in trsocket.h, the following identifiers map to selected names of parameters that exist for the WWW-Authenticate header returned by the server in combination with a 401 Unauthorized response. Parameter names can appear alone or with an associated value, e.g. realm="users@treck.com". Parameter names are case-insensitive; parameter values are usually not. An authentication scheme (e.g. Basic or Digest) must be specified by the server and must precede the parameters for the scheme. A WWW-Authenticate header may contain more than one authentication scheme. For further information, see RFC 2617.

Id	Name	Notes
TM_HTTPC_AUTH_PARAM_BASIC	Basic	Authentication scheme; has no value.
TM_HTTPC_AUTH_PARAM_DIGEST	Digest	Authentication scheme; has no value.
TM_HTTPC_AUTH_PARAM_REALM	realm	Required for all authentication schemes. Defines the protection space for the requested resource. This parameter is used to compute the request-digest and must be returned in a Digest response.
TM_HTTPC_AUTH_PARAM_DOMAIN	domain	Optional for Digest. Provides a list of servers that share the same protection space.
TM_HTTPC_AUTH_PARAM_NONCE	nonce	Required for Digest. This parameter is used to compute the request-digest and must be returned in a Digest response.
TM_HTTPC_AUTH_PARAM_OPAQUE	opaque	Optional for Digest. This parameter must be returned in the client's response if it exists in the server's challenge.
TM_HTTPC_AUTH_PARAM_STALE	stale	Optional for Digest. The server specifies a value of true to indicate that you should retry your authorization request with the new nonce value included in the current WWW-Authenticate header.
TM_HTTPC_AUTH_PARAM_ALGORITHM	algorithm	Optional for Digest. The Treck Web Client provides support for the MD5 algorithm.
TM_HTTPC_AUTH_PARAM_QOP	qop	Optional for Digest. The list of Quality of Protection options supported by the server should be present for any server that complies with RFC 2617. Select one option from the list and generate an appropriate response.
TM_HTTPC_AUTH_PARAM_UNSPEC		The parameter name does not have an associated id. You should use strcmp() on the name to identify the parameter.

Parameters

• conHandle

  The HTTP client connection handle.

• argVecOutPtr

  A pointer to a ttHttpcAuthArgVectorPtr variable to receive the parameters. You must call tfHttpcUserFreeObject() to free the object if TM_ENOERROR is returned.

Returns

• TM_ENOERROR

  Success; call tfHttpcUserFreeObject() to free the object pointed to by argVecOutPtr.

• TM_EINVAL

  Invalid parameter.

• TM_ENOBUFS

  Insufficient memory.

• TM_EPERM

  The TM_HTTP_HEADER_WWW_AUTHENTICATE has not been registered or the headers have not been fully received.

• TM_ENOENT

  The server did not include a WWW-Authenticate header (i.e. no further authentication is required).

Table of Contents >> Application Reference >> Web Client