tfHttpcUserBuildAuthResponse

Jump to: navigation, search

Table of Contents >> Application Reference >> Web Client


#include <trsocket.h>


int tfHttpcUserBuildAuthResponse (
ttHttpcUserConHandle conHandle,
char TM_FAR * outputPtr,
char TM_FAR * TM_FAR * inputArrayPtr,
int inputArrayCount
);


Function Description

This function provides a wrapper for the MD5 cryptographic hash algorithm to help the user build the response for a Digest Authentication challenge. The user supplies the authentication values (e.g. username, password) and this function inputs the strings into the MD5 digest and automatically inserts an ASCII ':' character between each value, as required.

The caller is responsible for collecting the necessary parameters and making sure the parameters are in the correct order, based on the rules specified in RFC 2617, section 3.2. Note that some digest input values are digest outputs from other input sequences.

A simple example with no QOP or algorithm parameters ('+' denotes string concatenation):

  request-digest = KD(H(A1), nonce + ":" + H(A2))
                 = H(H(A1) + ":" + nonce + ":" + H(A2))
     A1 = username + ":" + realm + ":" + password
     A2 = method + ":" + digest-uri
  Compute A1:
     char hashA1buf[TM_HTTPC_AUTH_DIGEST_ALLOC];
     inData[0] = username;
     inData[1] = realm;     /* from the WWW-Authenticate header */
     inData[2] = password;
     errorCode = tfHttpcUserBuildAuthResponse(conHandle, hashA1buf, inData, 3);
  Compute A2:
     char hashA2buf[TM_HTTPC_AUTH_DIGEST_ALLOC];
     inData[0] = method;    /* e.g. GET or POST */
     inData[1] = uri;       /* from the request line, e.g. "/blogs/joe.html" */
     errorCode = tfHttpcUserBuildAuthResponse(conHandle, hashA2buf, inData, 2);
  Compute request-digest:
     char digestOut[TM_HTTPC_AUTH_DIGEST_ALLOC];
     inData[0] = hashA1buf;
     inData[1] = nonce;     /* from the WWW-Authenticate header */
     inData[2] = hashA2buf;
     errorCode = tfHttpcUserBuildAuthResponse(conHandle, digestOut, inData, 3);
  Format the Authorization header to send:
     sprintf(buf, "Digest username=%s, realm=%s, nonce=%s, uri=%s, response=%s",
             username, realm, nonce, uri, digestOut);

Call tfHttpcUserGetResponseAuthParams() to get the nonce, realm and any other necessary parameters from the server's WWW-Authenticate header. The Web client sends the challenge response in the TM_HTTP_HEADER_AUTHORIZATION header when calling tfHttpcUserSendRequestHeaders().

This function will be present, unless you have uncommented the TM_DISABLE_HTTPC_DIGEST_AUTH macro in your trsystem.h.


Parameters

  • conHandle
    The HTTP client connection handle.
  • outputPtr
    Pointer to a buffer to receive the digest result. The buffer must be large enough to hold TM_HTTPC_AUTH_DIGEST_ALLOC characters (TM_HTTPC_AUTH_DIGEST_ALLOC includes room for the string terminating '\0' character).
  • inputArrayPtr
    Pointer to an array of pointers to authentication parameter strings ('\0' terminated) for input into the digest algorithm.
  • inputArrayCount
    The number of elements in the inputArrayPtr array.


Returns

  • TM_ENOERROR
    Success.
  • TM_EINVAL
    Invalid parameter value.
  • TM_ENOBUFS
    Insufficient memory.
  • TM_ENOENT
    Internal error; crypto engine missing.
  • other
    from crypto engine processing.


Table of Contents >> Application Reference >> Web Client