LSA_ADD_CREDENTIAL callback function (ntsecpkg.h)

Article
10/13/2021

[AddCredential is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in subsequent versions. Applications should use the LsaCallAuthenticationPackage function with KerbAddExtraCredentialsMessage specified as the message type. KerbAddExtraCredentialsMessage is a KERB_PROTOCOL_MESSAGE_TYPE enumeration value.]

Adds credentials to a logon session. These credentials can later be referenced through a call to the GetCredentials function.

Syntax

LSA_ADD_CREDENTIAL LsaAddCredential;

NTSTATUS LsaAddCredential(
  [in] PLUID LogonId,
  [in] ULONG AuthenticationPackage,
  [in] PLSA_STRING PrimaryKeyValue,
  [in] PLSA_STRING Credentials
)
{...}

Parameters

[in] LogonId

A pointer to an LUID that contains the session ID of the logon session to which credentials are to be added.

[in] AuthenticationPackage

The authentication package ID of the calling authentication package. This value is received in the LsaApInitializePackage call during DLL initialization.

[in] PrimaryKeyValue

A string that contains a value that the authentication package will later need to reference as a primary key of the credential data. This can be used, for example, to keep the name of the domain or server the credentials are related to. The format and meaning of this string are specific to the authentication package. Note that the string value does not have to be unique, even for the specified logon session. For example, there can be two passwords for the same domain, each with the passwords stored as credentials and the domain name stored as the primary key.

[in] Credentials

A string that represents the user credentials. The format and meaning of this string are specific to the authentication package.

Return value

If the function succeeds, the function returns STATUS_SUCCESS.

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

Return code	Description
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.

Remarks

The body of the credential string must be self-relative; that is, it must contain no pointers to memory outside the credentials. Credentials are copied, and any pointers outside the credentials themselves will no longer be valid in the copy. In particular, strings referred to in credentials should have both the UNICODE_STRING header and body placed in the credential buffer. Pointers to strings in the body of credentials should be changed to offsets.

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