INSSUserAuthentication::GetChallenge

Called by the server to get data from the authenticator that is 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 must return S_OK upon successful completion, or an HRESULT error code.

Remarks

The authenticator determines the format of the returned challenge.

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 is a NULL pointer. That is, the GetChallenge method must not return any realm and use SysAllocString to allocate a realm string.

The server can issue the GetChallenge method to get a realm and an initial challenge before the authenticator has any information about the user. In this case, either the realm or the challenge, or both, can be NULL. To avoid unintended interruptions, authenticators must be prepared to handle such cases.

The server also calls this method when the result parameter passed to the callback has an NS_AUTH_CONTINUE value.

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

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

See Also

INSSUserAuthentication::Authenticate, INSSAuthenticationCallback::OnAuthenticateComplete