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

Статья
11/20/2024

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

Заметка

Эта функция служит асинхронным аналогом функции InitializeSecurityContext.

Синтаксис

SECURITY_STATUS SspiInitializeSecurityContextAsyncA(
  SspiAsyncContext *AsyncContext,
  PCredHandle      phCredential,
  PCtxtHandle      phContext,
  LPSTR            pszTargetName,
  unsigned long    fContextReq,
  unsigned long    Reserved1,
  unsigned long    TargetDataRep,
  PSecBufferDesc   pInput,
  unsigned long    Reserved2,
  PCtxtHandle      phNewContext,
  PSecBufferDesc   pOutput,
  unsigned long    *pfContextAttr,
  PTimeStamp       ptsExpiry
);

Параметры

AsyncContext

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

phCredential

Дескриптор учетных данных, возвращаемых AcquireCredentialsHandle. Этот дескриптор используется для создания контекста безопасности.

phContext

Указатель на существующую структуру CtxtHandle.

pszTargetName

Указатель на строку, завершающуюся значением NULL, которая указывает целевой объект контекста. Содержимое строки пакет безопасности определенным, как описано в следующей таблице. Этот список не является исчерпывающим. В систему можно добавить дополнительные SSPS системы и сторонние SSPS.

Использование SSP	Значение
дайджест	Строка, завершающаяся значением NULL, которая однозначно идентифицирует URI запрошенного ресурса. Строка должна состоять из символов, которые разрешены в URI и должны представляться набором кода ASCII в США. Кодировка процентов может использоваться для представления символов за пределами набора кода ASCII в США.
Kerberos или согласование	Имя субъекта-службы или контекст безопасности целевого сервера.
NTLM	Имя субъекта-службы или контекст безопасности целевого сервера.
Schannel/SSL	Строка, завершающаяся значением NULL, которая однозначно идентифицирует целевой сервер. Schannel использует это значение для проверки сертификата сервера. Schannel также использует это значение для поиска сеанса в кэше сеансов при повторном развертывании подключения. Кэшированный сеанс используется только в том случае, если выполнены все следующие условия: Имя целевого объекта совпадает. Запись кэша не истекла. Процесс приложения, вызывающий функцию, совпадает. Сеанс входа совпадает. Дескриптор учетных данных совпадает.

fContextReq

Битовые флаги, указывающие запросы контекста.

См. InitializeSecurityContext: fContextReq для списка значений флагов и их значений.

Reserved1

Этот параметр зарезервирован и должен иметь значение нулю.

TargetDataRep

Представление данных, например упорядочение байтов, на целевом объекте. Этот параметр может быть либо SECURITY_NATIVE_DREP, либо SECURITY_NETWORK_DREP.

pInput

Указатель на структуру SecBufferDesc, содержащую указатели на буферы, предоставленные в качестве входных данных в пакет.

Reserved2

Этот параметр зарезервирован и должен иметь значение нулю.

phNewContext

Указатель на структуру CtxtHandle.

pOutput

Указатель на структуру SecBufferDesc, содержащую указатели на структуру SecBuffer, которая получает выходные данные.

pfContextAttr

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

ptsExpiry

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

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

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

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

Возвращаемый код	Описание
SEC_I_COMPLETE_AND_CONTINUE 0x00090314L	Клиент должен вызвать CompleteAuthToken и передать выходной маркер серверу. Затем клиент ожидает возвращенного маркера и передает его в другой вызов SspiInitializeSecurityContextAsyncAsyncA.
SEC_I_COMPLETE_NEEDED 0x00090313L	Клиент должен завершить сборку сообщения с сервера перед вызовом CompleteAuthToken.
SEC_I_CONTINUE_NEEDED 0x00090312L	Клиент должен отправить выходной маркер серверу и ждать возвращаемого маркера. Затем возвращенный маркер передается в другой вызов SspiInitializeSecurityContextAsyncAsyncA. Выходной маркер может быть пустым.
SEC_I_INCOMPLETE_CREDENTIALS	Используйте с Schannel. Сервер запросил проверку подлинности клиента, и предоставленные учетные данные либо не включают сертификат, либо сертификат не был выдан центром сертификации, доверенным сервером.
SEC_E_INCOMPLETE_MESSAGE 0x80090318L	Данные для всего сообщения не считывались из провода. При возврате этого значения буфер pInput содержит структуру SecBuffer с элементом BufferType SECBUFFER_MISSING. Член cbBuffer secBuffer содержит значение, указывающее количество дополнительных байтов, которые функция должна считывать от клиента до успешного выполнения этой функции. Хотя это число не всегда является точным, использование может помочь повысить производительность, избегая нескольких вызовов этой функции.
SEC_E_OK 0x000000000L	Контекст безопасности, полученный от клиента, был принят. Если функция создала выходной маркер, маркер должен быть отправлен на сервер.

Коды неустранимых ошибок

Возвращаемый код	Описание
SEC_E_INSUFFICIENT_MEMORY 0x80090300L	Для выполнения запрошенного действия недостаточно памяти.
SEC_E_INTERNAL_ERROR 0x80090304L	Произошла ошибка, которая не сопоставлялась с кодом ошибки SSPI.
SEC_E_INVALID_HANDLE 0x80100003L	Дескриптор, переданный функции, недопустим.
SEC_E_INVALID_TOKEN 0x80090308L	Ошибка возникает из-за неправильно сформированного входного маркера, например маркера, поврежденного при передаче, маркера неправильного размера или маркера, переданного в неправильный пакет безопасности. Передача маркера в неправильный пакет может произойти, если клиент и сервер не согласовывали правильный пакет безопасности.
SEC_E_LOGON_DENIED 0x8009030CL	Сбой входа.
SEC_E_NO_AUTHENTICATING_AUTHORITY 0x80090311L	Для проверки подлинности не удается связаться с центром. Доменное имя стороны проверки подлинности может быть неправильно, домен может быть недоступен или может произойти сбой связи доверия.
SEC_E_NO_CREDENTIALS 0x8009030EL	Учетные данные в пакете безопасности недоступны.
SEC_E_TARGET_UNKNOWN	Целевой объект не распознался.
SEC_E_UNSUPPORTED_FUNCTION 0x80090302L	Недопустимый флаг атрибута контекста (ISC_REQ_DELEGATE или ISC_REQ_PROMPT_FOR_CREDS) был указан в параметре fContextReq.
SEC_E_WRONG_PRINCIPAL	Субъект, полученный запрос на проверку подлинности, не совпадает с тем, который был передан в параметр pszTargetName. Это означает сбой взаимной проверки подлинности.

Замечания

Полные замечания см. в InitializeSecurityContext.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 10 версии 1607 [только драйверы в режиме ядра]
минимальный поддерживаемый сервер	Windows Server 2016 [только драйверы в режиме ядра]
заголовка	sspi.h

См. также

SspiAcceptSecurityContextAsync

SspiAcquireCredentialsHandleAsync

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