INSSUserAuthentication::GetChallenge

The INSSUserAuthentication::GetChallenge method is called by the server to get data from the authenticator to be sent back to the client.

Syntax

HRESULT GetChallenge (
DWORD  *pcbBlob,
BYTE  **pBlob,
LPBSTR pbstrRealm
);

Parameters

[out] pcbBlob

Specifies the size in bytes of the data being sent to the client.

[out] pBlob

Specifies a pointer to the data being sent to the client.

[out] pbstrRealm

Specifies a pointer to the realm for the challenge.

Return Values

This method should return S_OK upon successful completion, or an HRESULT error value.

Remarks

The authenticator determines the format of the returned challenge. In order to work properly with the server, the authenticator should observe the following guideline: If it is not obvious how the server will interpret the format, the authenticator should use the format appropriate for the text-based HTTP-Basic protocol.

If the INSSAuthenticator::Initialize method defines a NULL default realm, the GetChallenge method must return a non-NULL realm string. If the authenticator’s Initialize method specifies a non-NULL default realm, the pbstrRealm must be a NULL pointer. That is, the GetChallenge method should return any realm.

It is possible that the server may issue the GetChallenge method to get a realm and an initial challenge before the authenticator knows anything about the user. In this case, either the realm or the challenge, or both, may be NULL. Authenticators should be prepared to handle such cases so as to avoid unintended interruptions.

This method is called by the server when the result parameter passed to the callback has an NS_AUTH_CONTINUE value.

This method may also be called with an initial challenge to the client is made before the Authenticate method is called. This data may be ignored by the authenticator; however, a valid value should be returned to the server when the initial challenge is issued.

The following sample code demonstrates a skeletal implementation of this method:

HRESULT CUserAuthentication::GetChallenge( 
      DWORD *pcbBlob, 
      BYTE **pBlob )
{
  //
  // Set the blob with the reply data here.
  //
  return( S_OK );
}

See Also

INSSUserAuthentication::Authenticate, INSSAuthenticationCallback::OnAuthenticateComplete