AuthResetSetup

4/8/2010

This function wraps the Authentication Reset Component (ARC) setup functionality.

Syntax

HRESULT AuthResetSetup(
  HWND hWndParent,
  const BYTE* pbResetData,
  DWORD cbResetData,
  LPBYTE* ppbRequestData,
  LPDWORD pcbRequestData
);

Parameters

• hWndParent
  [in] Handle to the parent window. Can be NULL.

• pbResetData
  [in] Optional pointer to Reset Data. The meaning, size, and contents of the Reset Data are defined by the caller. The same data will be returned by a successful call to AuthResetRequest. Can be NULL.

• cbResetData
  [in] Size in bytes of the buffer pointed to by pbResetData. If pbResetData is not NULL then this parameter cannot be 0. If pbResetData is NULL then this parameter is ignored.

• ppbRequestData
  [out] Pointer to a BYTE array that receives the data to use during a call to AuthResetRequest. The meaning, size, and contents of the Request Data are defined by the Authentication Reset Component. The caller is responsible for storing this data securely and providing it in subsequents calls to AuthResetReqeust. The buffer for the BYTE array is allocated by this function. The caller is responsible to free this buffer using LocalFree.

• pcbRequestData
  [out] Pointer to a variable that receives the size in bytes of the buffer pointed to by parameter ppbRequestData.

Annotated Function Declaration

HRESULT AuthResetSetup(__in_opt HWND hWndParent, __in_bcount_opt(cbResetData) const BYTE* pbResetData, DWORD cbResetData, __deref_out_bcount (*pcbRequestData) LPBYTE* ppbRequestData, __out LPDWORD pcbRequestData);

Return Value

Returns S_OK if setup steps were completed successfully, otherwise it could return one of the following error codes:

• HRESULT(ERROR_NOT_SUPPORTED)
  Device configuration does not permit Authentication Reset.

• HRESULT(ERROR_TOO_MANY_SESS)
  Another thread is already calling AuthResetSetup or AuthResetRequest.

• HRESULT(WAIT_TIMEOUT)
  The wait timeout has been exceeded.

• E_ACCESSDENIED
  The caller is not trusted.

• E_POINTER
  Invalid pointer. Either ppbRequestData is NULL or pcbRequestData is NULL. Valid pointers for these arguments are required.

• E_INVALIDARG
  Invalid argument. pbResetData is not NULL and cbResetData is 0. This condition is not allowed.

• E_ABORT
  The user canceled the process.

• E_OUTOFMEMORY
  The device is out of memory.

• E_FAIL
  Unspecified error.

Additional error codes may be defined by an Authentication Reset Component (ARC).

Remarks

A LAP should call this API during enrollment if it wants to make Authentication Reset available to the user at a later time. The LAP may supply Reset Data (e.g., an admin key) and must receive Request Data (e.g., a certificate). The method used to process the Request Data and the methods of storing and retrieving Reset Data are at the discretion of the Authentication Reset Component (ARC). Request Data must be securely stored and used when calling AuthResetRequest. If a call to AuthResetRequest is successful and Reset Data were supplied previously, the Reset Data are returned and the LAP should verify that these data match the originally-supplied data.

The Authentication Reset Component may display user interface and may take any amount of time to complete this function.

This function ignores the AuthenticationReset policy.

The default functionality encrypts the Reset Data with a key that is stored on an Exchange Server and returns the encrypted data to the caller as the Request Data.

This API can only be called by trusted processes.

Requirements

See Also

Reference

Authentication Reset System Functions
Authentication Reset System Reference

Concepts

Authentication Reset System