AuthResetRequest

  • Article

4/8/2010

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

Syntax

HRESULT AuthResetRequest(
  HWND hWndParent,
  const BYTE* pbRequestData,
  DWORD cbRequestData,
    LPBYTE* ppbResetData,
  LPDWORD pcbResetData
);

Parameters

  • hWndParent
    [in] Handle to the parent window. Can be NULL.
  • pbRequestData
    [in] Pointer to the Request Data. To successfully complete Authentication Reset, this must be the same data returned by a successful call to AuthResetSetup. The meaning, size, and contents of the Request Data are defined by the Authentication Reset Component (ARC).
  • cbRequestData
    [in] Size in bytes of the buffer pointed to by pbRequestData.
  • ppbResetData
    [out] Pointer to a BYTE array that contains the Reset Data set during a call to AuthResetSetup, if available. The caller should verify that the contents of this buffer match the originally supplied Reset Data before continuing Authentication Reset steps. The buffer for the BYTE array will be allocated by this function. The caller is responsible to free this buffer using LocalFree. If no Reset Data are available, this argument will point to NULL.
  • pcbResetData
    [out] Size in bytes of the ppbResetData buffer. If no Reset Data are available, pcbResetData will equal zero.

Annotated Function Declaration

HRESULT AuthResetRequest(__in_opt HWND hWndParent, __in_bcount(cbResetData) const BYTE* pbRequestData, DWORD cbRequestData, __deref_out_bcount_opt(*pcbResetData) LPBYTE* ppbResetData, __out LPDWORD pcbResetData);

Return Value

Returns S_OK if Authentication Reset is allowed to proceed. In this case, pbRequestData has been verified and ppbResetData contains the originally-supplied Reset Data. The LAP should perform any additional authentication necessary before continuing Authentication Reset steps. If Authentication Reset cannot proceed, an error code is returned:

  • HRESULT(ERROR_PRIVILEGE_NOT_HELD)
    The Authentication Reset request is denied.
  • HRESULT(ERROR_NOT_SUPPORTED)
    Device policy and/or configuration does not permit Authentication Reset.
  • HRESULT(ERROR_TOO_MANY_CMDS)
    The number of Authentication Reset request attempts has been exceeded.
  • HRESULT(ERROR_TOO_MANY_SESS)
    Another thread is already calling AuthResetSetup or AuthResetRequest.
  • HRESULT(WAIT_TIMEOUT)
    The wait timeout has been exceeded.
  • E_PENDING
    The Authentication Reset could not be completed at this time. The user may be requested to wait or perform some action, then try again.
  • E_ACCESSDENIED
    The caller is not trusted.
  • E_POINTER
    Invalid pointer. Either ppbResetData is NULL or pcbResetData is NULL. Valid pointers for these arguments are required.
  • E_INVALIDARG
    Invalid argument. pbRequestData is NULL or cbResetData is 0. Non-zero values for these arguments are required.
  • E_ABORT
    The user canceled the process.
  • E_OUTOFMEMORY
    The device is out of memory.
  • E_FAIL
    Unspecified error.

Remarks

A LAP should call this API if a user requests to reset an authentication token (e.g., they have lost or forgotten a password, card, etc). This function will determine if the user is allowed to perform an Authentication Reset. It will also retrieve associated Reset Data if any were stored using AuthResetSetup. 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 LAP should also perform any additional authentication necessary before continuing Authentication Reset steps. The method used to determine if the user is allowed to perform Authentication Reset and the methods of storing and retrieving Reset Data are at the discretion of the Authentication Reset Component.

This function will fail if the AuthenticationReset policy is set to 0 (Authentication Reset is not allowed).

The default functionality prompts the user for a recovery password that can be obtained from a system administrator.

This API can only be called by trusted processes.

If a DeviceWipeThreshold has been set on the device, this API will limit the number of failed Authentication Reset attempts. When the threshold has been reached, this function will always return HRESULT_FROM_WIN32(ERROR_TOO_MANY_CMDS).

Requirements

Header aygshell.h
Library Aygshell.dll
Windows Mobile Windows Mobile 6 Classic and later, Windows Mobile 6 Professional and later, Windows Mobile 6 Standard and later

See Also

Reference

Authentication Reset System Functions
Authentication Reset System Reference

Concepts

Authentication Reset System