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

  • Статья

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

Примечание

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

Синтаксис

SECURITY_STATUS SspiInitializeSecurityContextAsyncW(
  SspiAsyncContext *AsyncContext,
  PCredHandle      phCredential,
  PCtxtHandle      phContext,
  PSECURITY_STRING 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, которая указывает целевой объект контекста. Содержимое строки зависит от пакета безопасности , как описано в следующей таблице. Этот список не является исчерпывающим. В систему можно добавить дополнительные системные SSP и сторонние поставщики SSP.

Используется поставщик общих служб Значение
Digest (дайджест) Строка, завершающаяся null, однозначно идентифицирующая универсальный код ресурса (URI) запрошенного ресурса. Строка должна состоять из символов, допустимых в URI, и должна быть представлена набором кода US ASCII. Кодировка в процентах может использоваться для представления символов за пределами набора кода US ASCII.
Kerberos или Negotiate Имя субъекта-службы (SPN) или контекст безопасности целевого сервера.
NTLM Имя субъекта-службы (SPN) или контекст безопасности целевого сервера.
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 и передать выходной маркер серверу. Затем клиент ожидает возвращенного маркера и передает его в другом вызове В SspiInitializeSecurityContextAsyncA.
SEC_I_COMPLETE_NEEDED
0x00090313L		 Клиент должен завершить сборку сообщения с сервера перед вызовом CompleteAuthToken.
SEC_I_CONTINUE_NEEDED
0x00090312L		 Клиент должен отправить выходной маркер на сервер и дождаться возврата маркера. Затем возвращенный маркер передается в другом вызове SspiInitializeSecurityContextAsyncA. Выходной маркер может быть пустым.
SEC_I_INCOMPLETE_CREDENTIALS Используйте со Schannel. Сервер запросил проверку подлинности клиента, и предоставленные учетные данные либо не включают сертификат, либо сертификат не был выдан центром сертификации, которому доверяет сервер.
SEC_E_INCOMPLETE_MESSAGE
0x80090318L		 Данные для всего сообщения не были считаны из провода. При возврате этого значения буфер pInput содержит структуру SecBuffer с элементом BufferType SECBUFFER_MISSING. Член cbBuffer элемента SecBuffer содержит значение, указывающее количество дополнительных байтов, которые функция должна считывать у клиента, прежде чем эта функция будет успешно выполнена. Хотя это число не всегда является точным, его использование может помочь повысить производительность, избегая нескольких вызовов этой функции.
SEC_E_OK
0x00000000L		 Контекст безопасности, полученный от клиента, был принят. Если функция сгенерировала выходной маркер, маркер должен быть отправлен на сервер.

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

Код возврата
Описание
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