If the credentials handle is returned to the caller, the package should also specify an expiration time for the handle.
NTSTATUS SpAcquireCredentialsHandle( _In_ PUNICODE_STRING PrincipalName, _In_ ULONG CredentialUseFlags, _In_ PLUID LogonId, _In_ PVOID AuthorizationData, _In_ PVOID GetKeyFunction, _In_ PVOID GetKeyArgument, _Out_ PLSA_SEC_HANDLE CredentialHandle, _Out_ PTimeStamp ExpirationTime );
- PrincipalName [in]
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.
- CredentialUseFlags [in]
Flags indicating how the credentials will be used. The following values are valid.
Credentials will be used with the AcceptSecurityContext (General) function.
Credentials will be used with the InitializeSecurityContext (General) function.
- LogonId [in]
- AuthorizationData [in]
Optional. Pointer to supplemental authentication data.
- GetKeyFunction [in]
Pointer to a function in the caller's address space that generates session keys.
- GetKeyArgument [in]
Pointer to the argument used with the GetKeyFunction function.
- CredentialHandle [out]
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.
- ExpirationTime [out]
Pointer to a TimeStamp that receives the time the credentials handle expires.
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.
The caller is denied access.
There are no credentials available for the specified principal.
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.
Minimum supported client
|Windows XP [desktop apps only]|
Minimum supported server
|Windows Server 2003 [desktop apps only]|
Build date: 1/2/2013