The VoipMediaEngine..::.CHALLENGE_AUTHENTICATION type exposes the following members.

Fields

  NameDescription
Algorithm
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.
AuthorizationGranted
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(UInt32, String, String) API procedure returns the SipSuccess status.
ChallengeMode
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.
ChallengeRealm
If the Operation member is set to AUTHENTICATE_INCOMING_MESSAGE, this member can be used to specify the challenge realm for the request.

Note:

Direction: Media Engine to Application

The media engine uses this member to inform the application about the user name of the challenge. Each incoming SIP message that contains challenge credentials has a user name specified. The application can use this value to look up the appropriate authorization password for the specified user. This way an application can support multiple authenticated users.

ChallengeType
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.
ChallengeUserName
If the Operation member is set to AUTHENTICATE_INCOMING_MESSAGE, this member can be used to specify the challenge user name for the request.

Note:

Direction: Media Engine to Application

The media engine uses this member to inform the application about the user name of the challenge. Each incoming SIP message that contains challenge credentials has a user name specified. The application can use this value to look up the appropriate authorization password for the specified user. This way an application can support multiple authenticated users.

ErrorMessage
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.
hChallenge
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(UInt32, String, String) API procedure when performing challenge response credential verification.
MediaEngine
The instance of the media engine.
MesageType
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.
Operation
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.

Note:

Direction: Media Engine to Application

This value is set by the media engine to inform your app of one of the the following:

An incoming SIP mesage was received and the media engine wants to know if your app wants to challenge the message. In this case, the value of this member will be set to AUTHENTICATE_INCOMING_MESSAGE and the message type received will be specified by the MesageType member. If your app wants to challenge the SIP message, it should set the ChallengeMode and ChallengeType members to the appropriate values for your application. If your app does not want to challenge the SIP message, it should set the ChallengeMode to either WWW or proxy authentication, ChallengeType to CHALLENGE_TYPE_NONE. If your app challenges the SIP message, it also must specify a challenge algoritm that will be used by the media engine. It is recommended that the Algorithm member be set to CHALLENGE_ALGORITHM_MD5. The far end also requires a realm to challenge so your app must also set the ChallengeRealm member.

- OR -

An incoming SIP mesage was received that contains authorization credentials and the media engine is asking your application to validate the credentials. In this case, the value of this member will be set to AUTHENTICATE_VERIFY_CREDENTIALS. The ChallengeRealm member will contain the authorization realm the far end device specified and the hChallenge member will be a handle to internal challenge information the far end specified.

See Also