AcquireCredentialsHandle (Compact 2013)

  • Article

3/28/2014

This function allows applications to acquire a handle to preexisting credentials associated with the user on whose behalf the call is made. These preexisting credentials are established through a system logon not described here. However, this is different from login to the network and does not imply gathering of credentials.

Syntax

SECURITY_STATUS SEC_ENTRY AcquireCredentialsHandle( 
  SEC_WCHAR SEC_FAR* pszPrincipal, 
  SEC_WCHAR SEC_FAR* pszPackage,
  ULONG fCredentialUse, 
  void SEC_FAR* pvLogonId, 
  void SEC_FAR* pAuthData,
  SEC_GET_KEY_FN pGetKeyFn, 
  void SEC_FAR* pvGetKeyArgument, 
  PCredHandle phCredential,
  PTimeStamp ptsExpiry 
);

Parameters

  • pszPrincipal
    [in] Pointer to the name of the principal for which to acquire a handle to credentials. Note that if the process requesting the handle does not have access to the credentials, the function returns an error. A null string indicates that the process requires a handle to the credentials of the user under whose security context it is executing.
  • pszPackage
    [in] Pointer to the name of the security package with which the credentials will be used. This is a security package name retrieved in the Name member of a SecPkgInfo structure retrieved by the EnumerateSecurityPackages function.

  • fCredentialUse
    [in] Flag that indicates how the credentials will be used. The following list shows the possible values. This parameter can be one of these values:

    • SECPKG_CRED_INBOUND
    • SECPKG_CRED_OUTBOUND
    • SECPKG_CRED_BOTH
    • SECPKG_CRED_DEFAULT
    • SECPKG_CRED_RESERVED

    The credentials created with the CRED_INBOUND option can be used only for validating incoming calls. They cannot be used for accessing objects.

  • pvLogonId
    [in] Pointer to a Windows NT-style logon identifier (LUID). This parameter is provided for file-system processes such as network redirectors. This parameter can be NULL.
  • pAuthData
    [in] Pointer to package-specific data. This parameter can be NULL, indicating that the default credentials for that package should be used. The NTLM Security Support Provider (SSP) accepts a pointer to a SEC_WINNT_AUTH_IDENTITY structure containing the user name, domain name, and password.
  • pGetKeyFn
    [in] Not supported. Set to NULL.
  • pvGetKeyArgument
    [in] Not supported. Set to NULL.
  • phCredential
    [out] Pointer to a CredHandle structure containing the credential handle. See SSPI Handles for information on CredHandle.
  • ptsExpiry
    [out] Optional pointer to the time at which the retrieved credentials expire. This value depends on the security package. The security provider should always retrieve this value in local time.

Return Value

Returns SEC_E_OK to indicate success. The following table shows the possible error values.

Value

Description

SEC_E_UNKNOWN_CREDENTIALS

The credentials supplied to the package were not recognized.

SEC_E_NO_CREDENTIALS

No credentials are available in the security package.

SEC_E_NOT_OWNER

The caller of the function does not own the necessary credentials.

SEC_E_INSUFFICIENT_MEMORY

Not enough memory is available to complete this request.

SEC_E_INTERNAL_ERROR

The Local Security Authority cannot be contacted.

SEC_E_SECPKG_NOT_FOUND

The requested security package does not exist.

Remarks

This function retrieves a handle to the credentials of a principal (user, client) as used by a specific security package. The handle can be used in subsequent calls to the AcceptSecurityContext and InitializeSecurityContext functions.

The AcquireCredentialsHandle function will not let a process obtain a handle to credentials that are not related to the process; in other words, a process cannot get the credentials of another user who is logged on to the same computer. There is no way to determine whether a process is a Trojan horse if it is executed by the user.

This function uses the following algorithm to determine whether to grant the request for a handle to the credentials.

If the caller is a system process with the SE_TCB_NAME privilege (for example, an FSP) and the caller provides both the name and logon identifier, the function verifies that they match before retrieving the credentials. If only one is provided, the function retrieves a handle to that identifier.

A caller that is not a system process can only obtain a handle to the credentials under which it is running. The caller can provide the name or the logon identifier, but it must be for the current session or the request fails.

A package might call the function in pGetKeyFn provided by the RPC run-time transport. If the transport does not support the notion of callback to retrieve credentials, this parameter must be NULL.

For kernel mode callers, the following differences must be noted: The two string parameters are Unicode strings and the buffer values must be allocated in process virtual memory, not from the pool.

When the caller no longer needs the credentials, it should call the FreeCredentialsHandle function.

Requirements

Header

security.h,
sspi.h

Library

secur32.lib

See Also

Reference

Authentication Services Functions
AcceptSecurityContext
EnumerateSecurityPackages
FreeCredentialsHandle
InitializeSecurityContext
SEC_WINNT_AUTH_IDENTITY
SecPkgInfo