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

Статья
08/26/2023

Функция SspiAcquireCredentialsHandleAsyncW асинхронно получает дескриптор для уже существовающих учетных данных субъекта безопасности.

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

Примечание

Эта функция выступает в качестве асинхронного аналога AcquireCredentialsHandle.

Синтаксис

SECURITY_STATUS SspiAcquireCredentialsHandleAsyncW(
  SspiAsyncContext *AsyncContext,
  PSECURITY_STRING pszPrincipal,
  PSECURITY_STRING pszPackage,
  unsigned long    fCredentialUse,
  void             *pvLogonId,
  void             *pAuthData,
  SEC_GET_KEY_FN   pGetKeyFn,
  void             *pvGetKeyArgument,
  PCredHandle      phCredential,
  PTimeStamp       ptsExpiry
);

Параметры

AsyncContext

Контекст асинхронного вызова.

pszPrincipal

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

Примечание

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

pszPackage

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

fCredentialUse

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

Значение	Значение
SECPKG_CRED_INBOUND	Проверка учетных данных входящего сервера. Входящие учетные данные можно проверить с помощью центра проверки подлинности при вызове SspiInitializeSecurityContextAsync или SspiAcceptSecurityContextAsync . Если такой центр недоступен, функция завершится ошибкой и возвратит SEC_E_NO_AUTHENTICATING_AUTHORITY. Проверка зависит от пакета.
SECPKG_CRED_OUTBOUND	Разрешить учетным данным локального клиента подготовить исходящий маркер.

Значение

SECPKG_CRED_INBOUND

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

SECPKG_CRED_OUTBOUND

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

pvLogonId

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

pAuthData

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

pGetKeyFn

Указатель на функцию GetKey().

pvGetKeyArgument

Передайте в GetKey().

phCredential

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

ptsExpiry

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

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

Возвращает SEC_E_OK , если асинхронный запрос на получение дескриптора учетных данных был успешно поставлен в очередь для выполнения. В противном случае возвращается ошибка, созданная при попытке поместить ее в очередь. Чтобы получить состояние операции, используйте SspiGetAsyncCallStatus.

Если дескриптор был получен, SspiGetAsyncCallStatus возвращает SEC_E_OK. В противном случае он может вернуть SEC_I_ASYNC_CALL_PENDING , если вызов все еще выполняется, или любой из следующих кодов неустранимых ошибок в таблице ниже.

Код возврата	Описание
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	Учетные данные, предоставленные пакету, не распознаны.

Функция SspiAcquireCredentialsHandleAsyncW возвращает дескриптор учетным данным субъекта, например пользователя или клиента, которые используются определенным пакетом безопасности. Функция может возвращать дескриптор либо ранее существовавших учетных данных, либо только что созданным учетным данным и возвращать его. Этот дескриптор можно использовать в последующих вызовах функций SspiAcceptSecurityContextAsync и SspiInitializeSecurityContextAsync .

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

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

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

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

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

Требования


Минимальная версия клиента	Windows 10 версии 1607 [только драйверы в режиме ядра]
Минимальная версия сервера	Windows Server 2016 [только драйверы в режиме ядра]
Верхняя часть	sspi.h

См. также раздел

AcquireCredentialsHandle

SspiAcceptSecurityContextAsync

SspiFreeCredentialsHandleAsync

SspiInitializeSecurityContextAsync

Функции SSPI