Функция AcceptSecurityContext (General)

Статья
03/18/2023

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

Сведения об использовании этой функции с определенным поставщиком поддержки безопасности (SSP) см. в следующих разделах.

Раздел	Описание
AcceptSecurityContext (CredSSP)	Позволяет компоненту сервера транспортного приложения устанавливать контекст безопасности между сервером и удаленным клиентом с помощью поставщика поддержки безопасности учетных данных (CredSSP).
AcceptSecurityContext (digest)	Позволяет компоненту сервера транспортного приложения установить контекст безопасности между сервером и удаленным клиентом, использующим дайджест.
AcceptSecurityContext (Kerberos)	Позволяет компоненту сервера транспортного приложения установить контекст безопасности между сервером и удаленным клиентом, использующим Kerberos.
AcceptSecurityContext (Negotiate)	Позволяет компоненту сервера транспортного приложения установить контекст безопасности между сервером и удаленным клиентом, использующим Negotiate.
AcceptSecurityContext (NTLM)	Позволяет компоненту сервера транспортного приложения установить контекст безопасности между сервером и удаленным клиентом, использующим NTLM.
AcceptSecurityContext (Schannel)	Позволяет компоненту сервера транспортного приложения установить контекст безопасности между сервером и удаленным клиентом, использующим 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     ptsExpiry
);

Параметры

phCredential[in, optional]

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

phContext[in, out]

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

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

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

pInput[in, optional]

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

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

При использовании SSP Negotiate, Kerberos или NTLM можно указать сведения о привязке каналов, передав структуру SecBuffer типа SECBUFFER_CHANNEL_BINDINGS в дополнение к буферам, созданным вызовом функции InitializeSecurityContext (General). Сведения о привязке канала для буфера привязки канала можно получить, вызвав функцию QueryContextAttributes (Schannel) в контексте Schannel, который клиент использовал для проверки подлинности.

fContextReq[in]

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

Значение	Значение
ASC_REQ_ALLOCATE_MEMORY	Дайджест и Schannel выделят буферы вывода. Завершив использование буферов вывода, освободите их, вызвав функцию FreeContextBuffer .
ASC_REQ_ALLOW_MISSING_BINDINGS	Указывает, что для дайджеста не требуются привязки каналов как для внутренних, так и для внешних каналов. Это значение используется для обеспечения обратной совместимости, если поддержка привязки канала конечной точки неизвестна. Это значение является взаимоисключающим с ASC_REQ_PROXY_BINDINGS. Это значение поддерживается только поставщиком дайджест-служб. Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Это значение не поддерживается.
ASC_REQ_CONFIDENTIALITY	Шифрование и расшифровка сообщений. Дайджест-поставщик общих служб поддерживает этот флаг только для SASL.
ASC_REQ_CONNECTION	Контекст безопасности не будет обрабатывать сообщения форматирования.
ASC_REQ_DELEGATE	Серверу разрешено олицетворять клиента. Допустимо для Kerberos. Игнорируйте этот флаг для ограниченного делегирования.
ASC_REQ_EXTENDED_ERROR	При возникновении ошибок удаленная сторона будет уведомлена.
ASC_REQ_HTTP (0x10000000)	Используйте дайджест для HTTP. Опустите этот флаг, чтобы использовать дайджест в качестве механизма SASL.
ASC_REQ_INTEGRITY	Подписывая сообщения и проверяя подписи. Schannel не поддерживает этот флаг.
ASC_REQ_MUTUAL_AUTH	Клиент должен предоставить сертификат, который будет использоваться для проверки подлинности клиента. Этот флаг поддерживается только Schannel.
ASC_REQ_PROXY_BINDINGS	Указывает, что для дайджеста требуется привязка канала. Это значение является взаимоисключающим с ASC_REQ_ALLOW_MISSING_BINDINGS. Это значение поддерживается только поставщиком дайджест-служб. Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Это значение не поддерживается.
ASC_REQ_REPLAY_DETECT	Обнаружение воспроизводимых пакетов.
ASC_REQ_SEQUENCE_DETECT	Обнаружение сообщений, полученных вне последовательности.
ASC_REQ_STREAM	Поддержка потокового подключения. Этот флаг поддерживается только Schannel.

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

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

TargetDataRep[in]

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

Этот параметр не используется с Schannel или Дайджест-SSP. При использовании Schannel или Digest SSP укажите ноль для этого параметра.

phNewContext[in, out, optional]

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

pOutput[in, out, optional]

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

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

pfContextAttr[out]

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

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

ptsTimeStamp[out, optional]

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

Для этого параметра задано постоянное максимальное время. Срок действия для контекста безопасностиdigest или учетных данных, а также для использования дайджест-SSP не истекает.

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

Примечание

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

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

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

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

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

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

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

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

Примечание

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

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

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

Требования

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

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

Функции SSPI

DeleteSecurityContext

InitializeSecurityContext (General)

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

Функция AcceptSecurityContext (General)

Синтаксис

Параметры

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

Комментарии

Требования

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

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

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