Функция AcceptSecurityContext (Digest)

Статья
07/04/2024

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

Синтаксис

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 (Digest) с флагом SECPKG_CRED_INBOUND или флагом SECPKG_CRED_BOTH для получения этого дескриптора.

phContext [in, out, optional]

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

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

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

pInput [in, optional]

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

В следующей таблице показана конфигурация буфера для дайджеста HTTP. Первый буфер должен иметь тип SECBUFFER_TOKEN, а остальные должны иметь тип SECBUFFER_PKG_PARAMS. SASL требует только нулевого буфера.

Тип буфера #/buffer	Значение
0 SECBUFFER_TOKEN	Пустой для первого вызова и ответа на вызов, полученный от клиента для второго вызова.
1 SECBUFFER_PKG_PARAMS	Метод. Символы — это формат проводной линии из строки запроса. Однобайтовые символы US ASCII.
2 SECBUFFER_PKG_PARAMS	Зарезервировано.
3 SECBUFFER_PKG_PARAMS	HEntity. Шестнадцатеричное представление H(entity-body). Однобайтовые символы US ASCII.
4 SECBUFFER_PKG_PARAMS	Область. Строка области для задачи. Строка Юникода, которая должна быть представлена в US ASCII.
5 \| SECBUFFER_CHANNEL_BINDINGS SECBUFFER_READONLY	Содержит значение маркера привязки канала. Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: это значение не поддерживается.

fContextReq [in]

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

Значение	Значение
ASC_REQ_ALLOCATE_MEMORY	Дайджест выделяет выходные буферы для вас. Завершив использование выходных буферов, освободите их, вызвав функцию 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_PROXY_BINDINGS	Указывает, что дайджест требует привязки канала. Это значение взаимоисключающее с ASC_REQ_ALLOW_MISSING_BINDINGS. Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: это значение не поддерживается.
ASC_REQ_CONNECTION	Контекст безопасности не будет обрабатывать сообщения форматирования.
ASC_REQ_EXTENDED_ERROR	При возникновении ошибок удаленная сторона будет уведомлена.
ASC_REQ_HTTP (0x10000000)	Используйте дайджест для HTTP. Опустить этот флаг, чтобы использовать Дайджест в качестве механизма SASL.
ASC_REQ_INTEGRITY	Подписывая сообщения и проверяйте подписи.
ASC_REQ_REPLAY_DETECT	Обнаружение повторяемых пакетов.
ASC_REQ_SEQUENCE_DETECT	Обнаружение сообщений, полученных из последовательности.

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

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

TargetDataRep [in]

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

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

phNewContext [in, out, optional]

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

pOutput [in, out, optional]

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

pfContextAttr [out]

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

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

ptsTimeStamp [out, optional]

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

Этот параметр имеет постоянное максимальное время. Нет времени окончания срока действия контекстабезопасности дайджеста или учетных данных или при использовании службы "Дайджест SSP".

Примечание.

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

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

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

Возвращаемый код + значение	Description
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 , недопустим.
SEC_E_OK `0x00000000L`	Функция выполнена успешно. Контекст безопасности, полученный от клиента, был принят. Если выходной маркер был создан функцией, он должен быть отправлен в клиентский процесс.
SEC_E_SECURITY_QOS_FAILED `0x80090332L`	Не удалось выполнить функцию. Недопустимый флаг атрибута контекста был указан в параметре fContextReq .
SEC_I_COMPLETE_AND_CONTINUE `0x00090314L`	Функция выполнена успешно. Сервер должен вызвать CompleteAuthToken и передать выходной маркер клиенту. Затем сервер ожидает возвращаемого маркера от клиента, а затем выполняет еще один вызов AcceptSecurityContext (Digest).
SEC_I_COMPLETE_NEEDED `0x00090313L`	Функция выполнена успешно. Сервер должен завершить сборку сообщения от клиента, а затем вызвать функцию CompleteAuthToken .
SEC_I_CONTINUE_NEEDED `0x00090312L`	Функция выполнена успешно. Сервер должен отправить выходной маркер клиенту и ждать возвращаемого маркера. Возвращаемый маркер должен передаваться в PInput для другого вызова AcceptSecurityContext (Digest).
STATUS_LOGON_FAILURE `0xC000006DL`	Не удалось выполнить функцию. Функция AcceptSecurityContext (Digest) была вызвана после установки указанного контекста.
SEC_E_BAD_BINDINGS `0x80090346L`	Не удалось выполнить функцию. Политика привязки канала не была удовлетворена.

Замечания

Функция AcceptSecurityContext (Digest) — это серверная функция InitializeSecurityContext (Digest).

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

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

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

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

Примечание.

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

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

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

Требования

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

См. также

Функции SSPI

DeleteSecurityContext

InitializeSecurityContext (Digest)

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