Функция AcceptSecurityContext (Schannel)

Статья
03/18/2023

Функция AcceptSecurityContext (Schannel) позволяет компоненту сервера транспортного приложения устанавливать контекст безопасности между сервером и удаленным клиентом. Удаленный клиент использует функцию InitializeSecurityContext (Schannel) для запуска процесса создания контекста безопасности. Сервер может потребовать один или несколько маркеров ответа от удаленного клиента для завершения установки контекста безопасности.

Синтаксис

SECURITY_STATUS SEC_Entry AcceptSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _Inout_opt_ PCtxtHandle    phContext,
  _In_opt_    PSecBufferDesc pInput,
  _In_        ULONG          fContextReq,
  _In_        ULONG          TargetDataRep,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Inout_opt_ PSecBufferDesc pOutput,
  _Out_       PULONG         pfContextAttr,
  _Out_opt_   PTimeStamp     ptsTimeStamp
);

Параметры

phCredential[in, optional]

Дескриптор учетных данных сервера. Сервер вызывает функцию AcquireCredentialsHandle (Schannel) с флагом SECPKG_CRED_INBOUND или SECPKG_CRED_BOTH, установленным для получения этого дескриптора.

phContext[in, out, optional]

Указатель на структуру CtxtHandle . При первом вызове AcceptSecurityContext (Schannel) этот указатель имеет значение NULL. При последующих вызовах phContext — это дескриптор частично сформированного контекста, который был возвращен в параметре phNewContext при первом вызове.

Предупреждение

Не используйте один и тот же дескриптор контекста в параллельных вызовах AcceptSecurityContext (Schannel). Реализация API в поставщиках служб безопасности не является потокобезопасной.

pInput[in, optional]

Указатель на структуру SecBufferDesc , созданную вызовом клиента Метода InitializeSecurityContext (Schannel), который содержит дескриптор входного буфера.

При использовании поставщика поддержки безопасности Schannel первый буфер должен иметь тип SECBUFFER_TOKEN и содержать маркер безопасности, полученный от клиента. Второй буфер должен иметь тип SECBUFFER_EMPTY.

fContextReq[in]

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

Значение	Значение
ASC_REQ_ALLOCATE_MEMORY	Дайджест и Schannel выделят выходные буферы. Завершив использование выходных буферов, освободите их, вызвав функцию FreeContextBuffer .
ASC_REQ_CONFIDENTIALITY	Шифрование и расшифровка сообщений. Дайджест SSP поддерживает этот флаг только для SASL.
ASC_REQ_CONNECTION	Контекст безопасности не будет обрабатывать сообщения форматирования.
ASC_REQ_EXTENDED_ERROR	При возникновении ошибок удаленная сторона будет уведомлена.
ASC_REQ_MUTUAL_AUTH	Клиент должен предоставить сертификат, используемый для проверки подлинности клиента.
ASC_REQ_REPLAY_DETECT	Обнаружение повторно воспроизводимых пакетов.
ASC_REQ_SEQUENCE_DETECT	Обнаружение сообщений, полученных вне последовательности.
ASC_REQ_STREAM	Поддержка потокового подключения. Этот флаг поддерживается только Schannel.

Возможные флаги атрибутов и их значения см. в разделе Требования к контексту. Флаги, используемые для этого параметра, имеют префикс ASC_REQ, например ASC_REQ_DELEGATE.

Запрошенные атрибуты могут не поддерживаться клиентом. Дополнительные сведения см. в параметре pfContextAttr .

TargetDataRep[in]

Этот параметр не используется в Schannel. Укажите ноль для этого параметра.

phNewContext[in, out, optional]

Указатель на структуру CtxtHandle . При первом вызове AcceptSecurityContext (Schannel) этот указатель получает новый дескриптор контекста. При последующих вызовах phNewContext может совпадать с дескриптором, указанным в параметре phContext . PhNewContext никогда не должен иметь значение NULL.

pOutput[in, out, optional]

Указатель на структуру SecBufferDesc , содержащую дескриптор выходного буфера. Этот буфер отправляется клиенту для ввода в дополнительные вызовы InitializeSecurityContext (Schannel). Выходной буфер может быть создан, даже если функция возвращает SEC_E_OK. Любой созданный буфер должен быть отправлен обратно в клиентское приложение.

В выходных данных этот буфер получает маркер для контекста безопасности. Маркер должен быть отправлен клиенту. Функция также может возвращать буфер типа SECBUFFER_EXTRA. Кроме того, вызывающий объект должен передавать буфер типа SECBUFFER_ALERT. В выходных данных, если создается оповещение, этот буфер содержит сведения об этом оповещении, и функция завершается сбоем.

pfContextAttr[out]

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

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

ptsTimeStamp[out, optional]

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

Это необязательно при использовании Schannel SSP. Когда удаленная сторона предоставила сертификат, используемый для проверки подлинности, этот параметр получает срок действия этого сертификата. Если сертификат не был предоставлен, возвращается максимальное значение времени.

Примечание

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

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

Эта функция возвращает одно из следующих значений.

Возвращаемый код или значение	Описание
SEC_E_INCOMPLETE_MESSAGE 0x80090318L	Функция выполнена успешно. Данные во входном буфере являются неполными. Приложение должно считывать дополнительные данные от клиента и снова вызывать [AcceptSecurityContext (Schannel)](acceptsecuritycontext--schannel.md). При возвращении этого значения буфер pInput содержит структуру [SecBuffer](/windows/win32/api/sspi/ns-sspi-secbuffer) с элементом BufferTypeSECBUFFER_MISSING. Член cbBufferэлемента SecBuffer содержит значение, указывающее количество дополнительных байтов, которые функция должна считывать у клиента, прежде чем эта функция будет успешно выполнена. Хотя это число не всегда является точным, его использование может повысить производительность, избегая нескольких вызовов этой функции.
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	Сбой функции. Дескриптор учетных данных, указанный в параметре phCredential , недопустим. Это значение может быть возвращено при использовании дайджеста или Schannel SSP.
SEC_E_OK 0x00000000L	Функция выполнена успешно. [контекст безопасности](.. Был принят параметр /secgloss/s-gly.md), полученный от клиента. Если выходной маркер был создан функцией, он должен быть отправлен в клиентский процесс.
SEC_E_UNSUPPORTED_FUNCTION 0x80090302L	Сбой функции. Недопустимый флаг атрибута контекста (ASC_REQ_DELEGATE или ASC_REQ_PROMPT_FOR_CREDS) был указан в параметре fContextReq .
SEC_E_APPLICATION_PROTOCOL_MISMATCH 0x80090367L	Между клиентом и сервером не существует общего протокола приложения.
SEC_I_COMPLETE_AND_CONTINUE 0x00090314L	Функция выполнена успешно. Сервер должен вызвать [CompleteAuthToken](/windows/win32/api/sspi/nf-sspi-completeauthtoken) и передать выходной маркер клиенту. Затем сервер ожидает возвращаемого маркера от клиента и выполняет еще один вызов [AcceptSecurityContext (Schannel)](acceptsecuritycontext--schannel.md).
SEC_I_COMPLETE_NEEDED 0x00090313L	Функция выполнена успешно. Сервер должен завершить сборку сообщения от клиента, а затем вызвать функцию [CompleteAuthToken](/windows/win32/api/sspi/nf-sspi-completeauthtoken).
SEC_I_CONTINUE_NEEDED 0x00090312L	Функция выполнена успешно. Сервер должен отправить выходной маркер клиенту и дождаться возвращенного маркера. Возвращенный маркер должен быть передан в pInput для другого вызова [AcceptSecurityContext (Schannel)](acceptsecuritycontext--schannel.md).
STATUS_LOGON_FAILURE 0xC000006DL	Сбой функции. Функция [AcceptSecurityContext (Schannel)](acceptsecuritycontext--schannel.md) была вызвана после установки указанного контекста. Это значение можно вернуть при использовании дайджест-поставщика общих служб.

Когда сервер получает запрос от клиента, сервер использует параметр fContextReq , чтобы указать, что требуется для сеанса. Таким образом, сервер может указать, что клиенты должны иметь возможность использовать конфиденциальный сеанс или сеанс проверки целостности, и он может отклонять клиентов, которые не могут удовлетворить эти требования. Кроме того, сервер может ничего не требовать, и все, что клиент может предоставить или требует, возвращается в параметре pfContextAttr .

Для пакета, поддерживающего многоуровневую проверку подлинности, например взаимную проверку подлинности, последовательность вызовов выглядит следующим образом:

Клиент передает маркер серверу.
Сервер впервые вызывает AcceptSecurityContext (Schannel ), который создает маркер ответа, который затем отправляется клиенту.
Клиент получает маркер и передает его в Приложение InitializeSecurityContext (Schannel). Если Функция InitializeSecurityContext (Schannel) возвращает SEC_E_OK, взаимная проверка подлинности завершена и может начаться безопасный сеанс. Если InitializeSecurityContext (Schannel) возвращает код ошибки, согласование взаимной проверки подлинности завершается. В противном случае маркер безопасности, возвращенный InitializeSecurityContext (Schannel), отправляется клиенту, а шаги 2 и 3 повторяются.
Не используйте значение phContext в параллельных вызовах AcceptSecurityContext (Schannel). Реализация в поставщиках безопасности не является потокобезопасной.

Параметры fContextReq и pfContextAttr представляют собой битовые маски, представляющие различные атрибуты контекста. Описание различных атрибутов см. в разделе Требования к контексту.

Примечание

Параметр pfContextAttr действителен при любом успешном возвращении, но только при окончательном успешном возвращении, если вы изучите флаги, относящиеся к аспектам безопасности контекста. Промежуточные возвраты могут задавать, например, флаг ISC_RET_ALLOCATED_MEMORY.

Вызывающий объект отвечает за определение достаточности атрибутов конечного контекста. Например, если была запрошена конфиденциальность (шифрование), но не удалось установить, некоторые приложения могут немедленно завершить подключение. Если не удается установить контекст безопасности , сервер должен освободить частично созданный контекст, вызвав функцию DeleteSecurityContext . Сведения о том, когда следует вызывать функцию DeleteSecurityContext , см. в разделе DeleteSecurityContext.

После установки контекста безопасности серверное приложение может использовать функцию QuerySecurityContextToken , чтобы получить дескриптор учетной записи пользователя, с которой был сопоставлен сертификат клиента. Кроме того, сервер может использовать функцию ImpersonateSecurityContext для олицетворения пользователя.

Требования

Требование	Значение
Минимальная версия клиента	Windows 8.1 [только классические приложения]
Минимальная версия сервера	Windows Server 2012 R2 [только классические приложения]
Заголовок	Sspi.h (включая Security.h)
Библиотека	Secur32.lib
DLL	Secur32.dll

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

Функции SSPI

DeleteSecurityContext

InitializeSecurityContext (Schannel)

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

Функция AcceptSecurityContext (Schannel)

Синтаксис

Параметры

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

Комментарии

Требования

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

Обратная связь

Дополнительные ресурсы