CHALLENGE_AUTHENTICATION

The address of this structure is passed to application software when the media engine’s authentication mechanism is enabled. Applications enable authentication events by calling the SetChallengeAuthenticationState API procedure. Once this is done, then SipIncomingAuthentication authentication events will be sent to the application along with the address of this structure for further processing.

typedef struct

{

AUTHENTICATE_OPERATION Operation;

AUTHENTICATE_MESSAGE_TYPE MesageType;

CHALLENGE_MODE ChallengeMode;

CHALLENGE_TYPE ChallengeType;

CHALLENGE_ALGORITHM Algorithm;

char ChallengeUserName[MAX_CHALLENGE_USER_NAME_LENGTH + 1];

char ChallengeRealm[MAX_CHALLENGE_REALM_NAME_LENGTH + 1];

SIPHANDLE hStateMachine;

CHALLENGE_HANDLE hChallenge;

BOOL AuthorizationGranted;

char ErrorMessage[MAX_CHALLENGE_ERROR_MSG_LENGTH + 1];

}CHALLENGE_AUTHENTICATION;

Identifies the authentication operation to be performed. It will be set to one of the following values: AUTHENTICATE_INCOMING_MESSAGE, AUTHENTICATE_VERIFY_CREDENTIALS, or AUTHENTICATE_BAD_CREDENTIALS_RECEIVED.

If the Operation member is set to AUTHENTICATE_INCOMING_MESSAGE then this member will contain the protocol message type that was received. The application can use this value to determine if it wants to challenge the incoming protocol message.

If the Operation member is set to AUTHENTICATE_INCOMING_MESSAGE and the application wants to challenge an incoming request, it can perform WWW authentication or Proxy authentication. This value must be set to either CHALLENGE_MODE_WWW_AUTHENTICATE or CHALLENGE_MODE_PROXY_AUTHENTICATE.

If the Operation member is set to AUTHENTICATE_INCOMING_MESSAGE, this member can be used to specify the challenge type the application is requesting of the far end. Currently the media engine supports Digest authentication using the MD5 algorithm. This member must be set to CHALLENGE_TYPE_DIGEST.

If the Operation member is set to AUTHENTICATE_INCOMING_MESSAGE, this member can be used to specify the challenge algorithm used when challenging the far end. Currently the media engine supports Digest authentication using the MD5 algorithm. This member must be set to CHALLENGE_ALGORITHM_MD5.

If the Operation member is set to AUTHENTICATE_INCOMING_MESSAGE, this member can be used to specify the challenge user name for the request.

If the Operation member is set to AUTHENTICATE_INCOMING_MESSAGE, this member can be used to specify the challenge realm for the request.

This member is a handle to the media engine. It can be used with any of the supporting authentication API procedures.

If the Operation member is set to AUTHENTICATE_VERIFY_CREDENTIALS, this member is used as the handle to far end authorization information. This handle gets passed as a parameter to the VerifyChallengeResponse API procedure when performing challenge response credential verification.

If the Operation member is set to AUTHENTICATE_VERIFY_CREDENTIALS, this member is used to inform the media engine that authorization is being granted to the incoming protocol request. It should be set to a non zero value only if the VerifyChallengeResponse API procedure returns the SipSuccess status.

If the Operation member is set to AUTHENTICATE_BAD_CREDENTIALS_RECEIVED, this member is used to inform the application of the possible cause of the error.