Функция AcquireCredentialsHandleA (sspi.h)

Статья
08/26/2023

Функция AcquireCredentialsHandle (CredSSP) получает дескриптор учетных данных субъекта безопасности . Этот дескриптор требуется и Функции AcceptSecurityContext (CredSSP) и AcceptSecurityContext (CredSSP). Они могут быть либо предварительно учетных данных, которые устанавливаются с помощью системного входа, который не описан здесь, либо вызывающий может предоставить альтернативные учетные данные.

Примечание Это не "вход в сеть" и не подразумевает сбор учетных данных.

Синтаксис

SECURITY_STATUS SEC_ENTRY AcquireCredentialsHandleA(
  [in, optional]  LPSTR          pszPrincipal,
  [in]            LPSTR          pszPackage,
  [in]            unsigned long  fCredentialUse,
  [in, optional]  void           *pvLogonId,
  [in, optional]  void           *pAuthData,
  [in, optional]  SEC_GET_KEY_FN pGetKeyFn,
  [in, optional]  void           *pvGetKeyArgument,
  [out]           PCredHandle    phCredential,
  [out, optional] PTimeStamp     ptsExpiry
);

Параметры

[in, optional] pszPrincipal

Указатель на строку, завершающуюся значением NULL, которая указывает имя субъекта, учетные данные которого будут ссылаться на дескриптор.

Примечание Если процесс, запрашивающий дескриптор, не имеет доступа к учетным данным, функция возвращает ошибку. Строка NULL указывает, что для процесса требуется дескриптор учетных данных пользователя, контекст безопасности которого выполняется.

[in] pszPackage

Указатель на строку, завершающую значение NULL, которая указывает имя пакета безопасности , с которыми будут использоваться эти учетные данные. Это имя пакета безопасности, возвращаемое в элементе имени структуры SecPkgInfo, возвращаемой функцией ListeSecurityPackages. После установки контекста QueryContextAttributes (CredSSP) можно вызывать с помощью ulAttribute SECPKG_ATTR_PACKAGE_INFO для возврата сведений об используемом пакете безопасности.

[in] fCredentialUse

Флаг, указывающий, как будут использоваться эти учетные данные. Этот параметр может быть одним из следующих значений.

Ценность	Значение
SECPKG_CRED_INBOUND 0x1	Проверка учетных данных входящего сервера. Входящие учетные данные могут быть проверены с помощью центра проверки подлинности при вызове InitializeSecurityContext (CredSSP) или AcceptSecurityContext (CredSSP). Если такой центр недоступен, функция завершится ошибкой и возвратит SEC_E_NO_AUTHENTICATING_AUTHORITY. Проверка зависит от пакета.
SECPKG_CRED_OUTBOUND 0x2	Разрешить локальным учетным данным клиента подготовить исходящий маркер.

Ценность

Значение

SECPKG_CRED_INBOUND
0x1

Проверка учетных данных входящего сервера. Входящие учетные данные могут быть проверены с помощью центра проверки подлинности при вызове InitializeSecurityContext (CredSSP) или AcceptSecurityContext (CredSSP). Если такой центр недоступен, функция завершится ошибкой и возвратит SEC_E_NO_AUTHENTICATING_AUTHORITY. Проверка зависит от пакета.

SECPKG_CRED_OUTBOUND
0x2

Разрешить локальным учетным данным клиента подготовить исходящий маркер.

[in, optional] pvLogonId

Указатель на локально уникальный идентификатор (LUID), который идентифицирует пользователя. Этот параметр предоставляется для процессов файловой системы, таких как сетевые перенаправления. Этот параметр может быть NULL.

[in, optional] pAuthData

Указатель на структуру CREDSSP_CRED, указывающую данные проверки подлинности для пакетов Schannel и Negotiate.

[in, optional] pGetKeyFn

Скрытный. Этот параметр не используется и должен иметь значение NULL.

[in, optional] pvGetKeyArgument

Скрытный. Этот параметр должен иметь значение NULL.

[out] phCredential

Указатель на структуру CredHandle, которая получит дескриптор учетных данных.

[out, optional] ptsExpiry

Указатель на структуру TimeStamp, которая получает время истечения срока действия возвращаемых учетных данных. Полученное значение структуры зависит от пакета безопасности, который должен указывать значение в локальном времени.

Возвращаемое значение

Если функция успешно выполнена, она возвращает SEC_E_OK.

Если функция завершается ошибкой, она возвращает один из следующих кодов ошибок.

Возвращаемый код	Описание
SEC_E_INSUFFICIENT_MEMORY	Для выполнения запрошенного действия недостаточно памяти.
SEC_E_INTERNAL_ERROR	Произошла ошибка, которая не сопоставлялась с кодом ошибки SSPI.
SEC_E_NO_CREDENTIALS	Учетные данные недоступны впакета безопасности .
SEC_E_NOT_OWNER	Вызывающий объект функции не имеет необходимых учетных данных.
SEC_E_SECPKG_NOT_FOUND	Запрошенный пакет безопасности не существует.
SEC_E_UNKNOWN_CREDENTIALS	Учетные данные, предоставленные пакету, не распознаны.

Замечания

Функция AcquireCredentialsHandle (CredSSP) возвращает дескриптор учетных данных субъекта, например пользователя или клиента, как используется определенным пакетом безопасности . Функция может вернуть дескриптор в предварительно созданные учетные данные или только что созданные учетные данные и вернуть его. Этот дескриптор можно использовать в последующих вызовах функций AcceptSecurityContext (CredSSP) и InitializeSecurityContext (CredSSP).

Как правило, AcquireCredentialsHandle (CredSSP) не предоставляет учетные данные других пользователей, вошедшего на тот же компьютер. Однако вызывающий объект с привилегиями SE_TCB_NAME может получить учетные данные существующего сеанса входа, указав идентификатор входа (LUID) этого сеанса. Как правило, это используется модулями в режиме ядра, которые должны действовать от имени пользователя, вошедшего в систему.

Пакет может вызывать функцию в pGetKeyFn, предоставляемой транспортом времени выполнения RPC. Если транспорт не поддерживает понятие обратного вызова для получения учетных данных, этот параметр должен быть NULL.

Для вызывающих вызовов в режиме ядра необходимо отметить следующие различия:

Два строковых параметра должны быть строки Юникода.
Значения буфера должны быть выделены в виртуальной памяти процесса, а не из пула.

После завершения использования возвращенных учетных данных освободите память, используемую учетными данными, вызвав функцию FreeCredentialsHandle.

Заметка

Заголовок sspi.h определяет AcquireCredentialsHandle как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2008 [только классические приложения]
целевая платформа	Виндоус
заголовка	sspi.h (include Security.h)
библиотеки	Secur32.lib
DLL	Secur32.dll

См. также

AcceptSecurityContext (CredSSP)

FreeCredentialsHandle

InitializeSecurityContext (CredSSP)

функций SSPI

Поделиться через