GetCredentials function

Retrieves credentials associated with a logon session.

This function is not used by newer authentication packages, such as Kerberos.

Syntax


NTSTATUS GetCredentials(
  _In_    PLUID       LogonId,
  _In_    ULONG       AuthenticationPackage,
  _Inout_ PULONG      QueryContext,
  _In_    BOOLEAN     RetrieveAllCredentials,
  _Inout_ PLSA_STRING PrimaryKeyValue,
  _Out_   PULONG      PrimaryKeyLength,
  _Out_   PLSA_STRING Credentials
);

Parameters

LogonId [in]

Pointer to an LUID structure containing the session ID of the logon session from which credentials are to be retrieved.

AuthenticationPackage [in]

Authentication package ID of the calling authentication package. Authentication packages should retrieve only their own credentials.

QueryContext [in, out]

Pointer to an unsigned LONG value used across successive calls to retrieve multiple credentials. The first time this function is used, the value pointed to by this argument should be zero. Thereafter, this value will be updated to allow retrieval to continue where it left off. This value should, therefore, not be changed until all credentials of a given query operation have been retrieved.

RetrieveAllCredentials [in]

Indicates whether all credentials for the specified logon session should be retrieved (TRUE), or only those matching the specified PrimaryKeyValue (FALSE).

PrimaryKeyValue [in, out]

This parameter serves two purposes. If the RetrieveAllCredentials parameter is FALSE, this string contains the value to use as a primary lookup key. In this case, only credentials belonging to the correct logon session with a primary lookup key matching this value will be retrieved.

If RetrieveAllCredentials is TRUE, the value of this string on input is ignored and the primary lookup key of each credential retrieved is returned in this string.

PrimaryKeyLength [out]

If the RetrieveAllCredentials parameter is TRUE, this parameter receives the length needed to store the PrimaryKeyValue string.

Credentials [out]

Pointer to a buffer that receives the retrieved credential. Only one credential is retrieved for each call made. The credential is returned in a buffer that the function allocates by calling the AllocateLsaHeap function. It is the caller's responsibility to free the Credentials buffer when it is no longer needed, by calling FreeLsaHeap.

Return value

If the function succeeds, the function returns the NTSTATUS code, STATUS_SUCCESS, indicating that the credentials were successfully retrieved.

If the function fails, the return value is an NTSTATUS code, which can be one of the following values or one of the LSA Policy Function Return Values.

Return codeDescription
ERROR_GEN_FAILURE

No more credentials are available. If this code is returned on the first call, there are no credentials matching the selection criteria.

STATUS_MORE_ENTRIES

The string provided to receive the PrimaryKeyValue was not large enough to hold the data. In this case, no data is retrieved, and the QueryContext value is not modified. This allows the same call to be made again with a larger string buffer.

STATUS_NO_SUCH_LOGON_SESSION

The specified logon session could not be found.

 

The LsaNtStatusToWinError function converts an NTSTATUS code to a Windows error code.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Ntsecpkg.h

See also

LSA_DISPATCH_TABLE
LSA_SECPKG_FUNCTION_TABLE

 

 

Show: