AcquireCredentialsHandle

The AcquireCredentialsHandle function acquires a handle to pre-existing credentials associated with the user on whose behalf the call is made. These pre-existing credentials are established through a system logon that is not described here.

Note  This is not a "login to the network" and does not imply gathering of credentials.

SECURITY_STATUS AcquireCredentialsHandle(
  SEC_CHAR *pszPrincipal,   // name of principal
  SEC_CHAR *pszPackage,     // name of package
  ULONG fCredentialUse,     // flags indicating use
  PLUID pvLogonID,          // pointer to logon identifier
  PVOID pAuthData,          // package-specific data
  PVOID pGetKeyFn,          // pointer to GetKey function
  PVOID pvGetKeyArgument,   // value to pass to GetKey
  PCredHandle phCredential, // credential handle
  PTimeStamp ptsExpiry      // lifetime of the returned credentials
);

Parameters

pszPrincipal

[in] Pointer to a NULL-terminated string that specifies the name of the principal whose credentials the handle will reference.

Note  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 a NULL-terminated string specifying the name of the security package with which these credentials will be used. This is a security package name returned in the Name member of a SecPkgInfo structure returned by the EnumerateSecurityPackages function. After a context is established, QueryContextAttributes can be called with ulAttribute set to SECPKG_ATTR_PACKAGE_INFO to return information on the security package in use.

fCredentialUse

[in] Flag indicating how these credentials will be used. This parameter can be one of the following values.

Value	Meaning
SECPKG_CRED_INBOUND	Used to validate an incoming credential.
SECPKG_CRED_OUTBOUND	Use to use a local credential to prepare an outgoing token.
SECPKG_CRED_BOTH	Validate an incoming credential or use a local credential to prepare an outgoing token.

pvLogonID

[in] Pointer to a Microsoft® Windows NT®/Microsoft® Windows® 2000–style locally unique identifier (LUID) used to identify the user. 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 must be used. To use supplied credentials, pass a SEC_WINNT_AUTH_IDENTITY structure that includes those credentials in this parameter. The RPC run time passes whatever was provided in RpcBindingSetAuthInfo or RpcServerRegisterAuthInfo.

pGetKeyFn

[in] Pointer to a SEC_GET_KEY_FN function that retrieves the key for the function. The security package can call this function, as provided by the RPC run-time transport application. This parameter can be NULL if the transport application does not support callbacks to retrieve credentials.

pvGetKeyArgument

[in] Specifies the pointer argument that the security package must pass to the GetKey function. This parameter can be NULL.

phCredential

[out] Pointer to a CredHandle structure that receives the credential handle.

ptsExpiry

[out] Pointer to a TimeStamp structure that receives the time at which the returned credentials expire. The value returned in this TimeStamp structure depends on the security package. The security package must return this value in local time.

Return Values

If the function succeeds, the return value is SEC_E_OK.

If the function fails, the return value can be one of the following error codes.

Remarks

The AcquireCredentialsHandle function returns a handle to the credentials of a principal (such as a user or client) as used by a specific security package. The handle returned can be used in subsequent calls to the AcceptSecurityContext and InitializeSecurityContext functions.

AcquireCredentialsHandle does 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.

AcquireCredentialsHandle 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 returning the credentials. If only one is provided, the function returns 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 may 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 you no longer need the returned credentials, call the FreeCredentialsHandle function to free the memory used by the credentials.

The prototype for this function can be found in Sspi.h.

Requirements

  Windows NT/2000: Requires Windows NT 3.51 or later.
  Windows 95/98: Requires Windows 95 or later.
  Header: Declared in Sspi.h; include Security.h.
  Library: Use Secur32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

AcceptSecurityContext, InitializeSecurityContext, FreeCredentialsHandle