SpAcquireCredentialsHandleFn callback function (ntsecpkg.h)

Article
10/13/2021

Called to obtain a handle to a principal's credentials. The security package can deny access to the caller if the caller does not have permission to access the credentials.

If the credentials handle is returned to the caller, the package should also specify an expiration time for the handle.

Syntax

SpAcquireCredentialsHandleFn Spacquirecredentialshandlefn;

NTSTATUS Spacquirecredentialshandlefn(
  [in]  PUNICODE_STRING PrincipalName,
  [in]  ULONG CredentialUseFlags,
  [in]  PLUID LogonId,
  [in]  PVOID AuthorizationData,
        PVOID GetKeyFunciton,
  [in]  PVOID GetKeyArgument,
  [out] PLSA_SEC_HANDLE CredentialHandle,
  [out] PTimeStamp ExpirationTime
)
{...}

Parameters

[in] PrincipalName

Optional. Pointer to a UNICODE_STRING structure containing the name of the security principal whose credentials are being requested. If this value is NULL, the caller requests a handle to the credentials of the user in whose security context the caller is executing.

[in] CredentialUseFlags

Flags indicating how the credentials will be used. The following values are valid.

Value	Meaning
SECPKG_CRED_INBOUND	Credentials will be used with the AcceptSecurityContext (General) function.
SECPKG_CRED_OUTBOUND	Credentials will be used with the InitializeSecurityContext (General) function.

[in] LogonId

Optional. Pointer to an LUID containing the logon identifier of the security principal.

[in] AuthorizationData

Optional. Pointer to supplemental authentication data.

GetKeyFunciton

[in] GetKeyArgument

Pointer to the argument used with the GetKeyFunction function.

[out] CredentialHandle

Pointer to an LSA_SEC_HANDLE that receives the credentials. When you have finished using the credentials, free the handle by calling the SpFreeCredentialsHandle function.

[out] ExpirationTime

Pointer to a TimeStamp that receives the time the credentials handle expires.

Return value

If the function succeeds, return STATUS_SUCCESS.

If the function fails, return an NTSTATUS code that indicates the reason it failed. The following table lists common reasons for failure and the error codes that should be returned.

Return code	Description
SEC_E_NOT_OWNER	The caller is denied access.
SEC_E_NO_CREDENTIALS	There are no credentials available for the specified principal.

Remarks

The package can use the Local Security Authority (LSA) support functions to determine whether the caller should be given access to the requested credentials.

Credentials obtained from SpAcquireCredentialsHandle are freed by calling the SpFreeCredentialsHandle function.

SSP/APs must implement the SpAcquireCredentialsHandle function; however, the actual name given to the implementation is up to the developer.

A pointer to the SpAcquireCredentialsHandle function is available in the SECPKG_FUNCTION_TABLE structure received from the SpLsaModeInitialize function.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	ntsecpkg.h