LsaCallAuthenticationPackage function (ntsecapi.h)

Article
12/06/2022

The LsaCallAuthenticationPackage function is used by a logon application to communicate with an authentication package.

This function is typically used to access services provided by the authentication package.

Syntax

NTSTATUS LsaCallAuthenticationPackage(
  [in]  HANDLE    LsaHandle,
  [in]  ULONG     AuthenticationPackage,
  [in]  PVOID     ProtocolSubmitBuffer,
  [in]  ULONG     SubmitBufferLength,
  [out] PVOID     *ProtocolReturnBuffer,
  [out] PULONG    ReturnBufferLength,
  [out] PNTSTATUS ProtocolStatus
);

Parameters

[in] LsaHandle

A handle obtained from a previous call to LsaRegisterLogonProcess or LsaConnectUntrusted.

[in] AuthenticationPackage

Supplies the identifier of the authentication package. This value is obtained by calling LsaLookupAuthenticationPackage.

[in] ProtocolSubmitBuffer

An authentication package–specific message buffer passed to the authentication package.

For information about the format and content of this buffer, see the documentation for the individual authentication package.

[in] SubmitBufferLength

Indicates the length, in bytes, of the ProtocolSubmitBuffer buffer.

[out] ProtocolReturnBuffer

A pointer that receives the address of the buffer returned by the authentication package.

For information about the format and content of this buffer, see the documentation for the individual authentication package.

This buffer is allocated by this function. When you have finished using this buffer, free the memory by calling the LsaFreeReturnBuffer function.

[out] ReturnBufferLength

A pointer to a ULONG that receives the length of the returned buffer, in bytes.

[out] ProtocolStatus

If the function succeeds, this parameter receives an NTSTATUS code that indicates the completion status of the authentication package.

Return value

If the function succeeds, the return value is STATUS_SUCCESS. Check the ProtocolStatus parameter to obtain the status returned by the authentication package.

If the function fails, the return value is an NTSTATUS code. The following are possible error codes.

Return code	Description
STATUS_QUOTA_EXCEEDED	The call could not be completed because the client's memory quota is not sufficient to allocate the return buffer.
STATUS_NO_SUCH_PACKAGE	The specified authentication package is not recognized by the LSA.
STATUS_PKINIT_FAILURE	The Kerberos client received a KDC certificate that is not valid. For device logon, strict KDC validation is required, so the KDC must have certificates that use the "Kerberos Authentication" template or equivalent. Also the KDC certificate could be expired, revoked, or the client is under active attack of sending requests to the wrong server.
STATUS_PKINIT_CLIENT_FAILURE	The Kerberos client is using a system certificate that is not valid. For device logon, there must be a DNS name. Also, the system certificate could be expired or the wrong one could be selected.

For more information, see LSA Policy Function Return Values.

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

Remarks

Logon applications can call LsaCallAuthenticationPackage to communicate with an authentication package. There are several reasons why an application may do this:

To implement multiple-message authentication protocols, such as the NTLM Challenge-Response protocol.
To pass state change information to the authentication package. For example, the NTLM might notify the MSV1_0 package that a previously unreachable domain controller is now reachable. The authentication package would then re-logon any users logged on to that domain controller.

Typically, this function is used to exchange information with a custom authentication package. This function is not needed by an application that is using one of the authentication packages supplied with Windows, such as MSV1_0 or Kerberos.

You must call LsaCallAuthenticationPackage to clean up PKINIT device credentials for LOCAL_SYSTEM and NETWORK_SERVICE. When there is no PKINIT device credential, a successful call does no operation. When there is a PKINIT device credential, a successful call cleans up the PKINIT device credential so that only the password credential remains.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	ntsecapi.h
Library	Secur32.lib
DLL	Secur32.dll