Функция InitializeSecurityContext (General)

Статья
03/18/2023

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

Как правило, функция InitializeSecurityContext (General) вызывается в цикле до тех пор, пока не будет установлен достаточный контекст безопасности.

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

Статья	Описание
InitializeSecurityContext (CredSSP)	Инициирует клиентская сторона, исходящий контекст безопасности из дескриптора учетных данных с помощью пакета безопасности поставщика поддержки учетных данных (CredSSP).
InitializeSecurityContext (Digest)	Инициирует клиентский контекст безопасности исходящего трафика из дескриптора учетных данных с помощью пакета безопасности Digest.
InitializeSecurityContext (Kerberos)	Инициирует клиентский контекст безопасности исходящего трафика из дескриптора учетных данных с помощью пакета безопасности Kerberos.
InitializeSecurityContext (Negotiate)	Инициирует клиентская сторона, исходящий контекст безопасности из дескриптора учетных данных с помощью пакета безопасности "Согласование".
InitializeSecurityContext (NTLM)	Инициирует клиентский контекст безопасности исходящего трафика из дескриптора учетных данных с помощью пакета безопасности NTLM.
InitializeSecurityContext (Schannel)	Инициирует клиентский контекст безопасности исходящего трафика из дескриптора учетных данных с помощью пакета безопасности Schannel.

Синтаксис

SECURITY_STATUS SEC_Entry InitializeSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _In_opt_    PCtxtHandle    phContext,
  _In_opt_    SEC_CHAR       *pszTargetName,
  _In_        ULONG          fContextReq,
  _In_        ULONG          Reserved1,
  _In_        ULONG          TargetDataRep,
  _In_opt_    PSecBufferDesc pInput,
  _In_        ULONG          Reserved2,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Inout_opt_ PSecBufferDesc pOutput,
  _Out_       PULONG         pfContextAttr,
  _Out_opt_   PTimeStamp     ptsExpiry
);

Параметры

phCredential[in, optional]

Дескриптор учетных данных, возвращаемых AcquireCredentialsHandle (General). Этот дескриптор используется для создания контекста безопасности. Для функции InitializeSecurityContext (General) требуется по крайней мере OU ТБ OUND учетных данных.

phContext[in, optional]

Указатель на структуру CtxtHandle . При первом вызове InitializeSecurityContext (General) этот указатель имеется NULL. Во втором вызове этот параметр является указателем на дескриптор частично сформированного контекста, возвращаемого в параметре phNewContext первым вызовом.

Этот параметр является необязательным для поставщика служб Microsoft Digest SSP и может иметь значение NULL.

При использовании Schannel SSP при первом вызове InitializeSecurityContext (General) укажите NULL. В будущих вызовах укажите маркер, полученный в параметре phNewContext после первого вызова этой функции.

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

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

pTargetName[in, optional]

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

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

fContextReq[in]

Битовые флаги, указывающие запросы контекста. Не все пакеты могут поддерживать все требования. Флаги, используемые для этого параметра, префиксируются ISC_REQ_, например ISC_REQ_DELEGATE. Этот параметр может быть одним или несколькими из следующих флагов атрибутов.

Значение	Значение
ISC_REQ_ALLOCATE_MEMORY	Пакет безопасности выделяет выходные буферы для вас. Завершив использование выходных буферов, освободите их, вызвав функцию FreeContextBuffer .
ISC_REQ_CONFIDENTIALITY	Шифрование сообщений с помощью функции EncryptMessage .
ISC_REQ_CONNECTION	Контекст безопасности не будет обрабатывать сообщения форматирования. Это значение по умолчанию для ограниченного делегированияKerberos, Negotiate и NTLM.
ISC_REQ_DELEGATE	Сервер может использовать контекст для проверки подлинности на других серверах в качестве клиента. Для работы этого флага необходимо задать флаг ISC_REQ_MUTUAL_AUTH . Допустимо для Kerberos. Игнорировать этот флаг для ограниченного делегирования.
ISC_REQ_EXTENDED_ERROR	При возникновении ошибок удаленная сторона будет уведомлена.
ISC_REQ_HTTP	Используйте дайджест для HTTP. Опустить этот флаг, чтобы использовать Дайджест в качестве механизма SASL.
ISC_REQ_INTEGRITY	Подписывая сообщения и проверяйте подписи с помощью функций EncryptMessage и MakeSignature .
ISC_REQ_MANUAL_CRED_VALIDATION	Schannel не должен выполнять автоматическую проверку подлинности сервера.
ISC_REQ_MUTUAL_AUTH	Будет удовлетворена политика взаимной проверки подлинности службы. ВНИМАНИЕ. Это не обязательно означает, что выполняется взаимная проверка подлинности, только то, что политика проверки подлинности службы удовлетворена. Чтобы обеспечить выполнение взаимной проверки подлинности, вызовите функцию QueryContextAttributes (General).
ISC_REQ_NO_INTEGRITY	Если этот флаг задан, флаг ISC_REQ_INTEGRITY игнорируется. Это значение поддерживается только ограниченной делегированиемKerberos и согласованием.
ISC_REQ_REPLAY_DETECT	Обнаружение повторяющихся сообщений, закодированных с помощью функций EncryptMessage или MakeSignature .
ISC_REQ_SEQUENCE_DETECT	Обнаружение сообщений, полученных из последовательности.
ISC_REQ_STREAM	Поддержка потокового подключения.
ISC_REQ_USE_SESSION_KEY	Необходимо согласовать новый ключ сеанса. Это значение поддерживается только ограниченной делегированием Kerberos.
ISC_REQ_USE_SUPPLIED_CREDS	Schannel не должен пытаться предоставить учетные данные для клиента автоматически.

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

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

Зарезервировано1[in]

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

TargetDataRep[in]

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

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

pInput[in, optional]

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

Зарезервировано 2[in]

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

phNewContext[in, out, optional]

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

pOutput[in, out, optional]

Указатель на структуру SecBufferDesc, содержащую указатели на структуру SecBuffer, которая получает выходные данные. Если буфер был введен как SEC_READWRITE во входных данных, он будет находиться в выходных данных. Система выделяет буфер для маркера безопасности при запросе (через ISC_REQ_ALLOCATE_MEMORY) и заполняет адрес дескриптором буфера для маркера безопасности.

При использовании поставщика SSP Microsoft Digest этот параметр получает ответ на вызов, который должен быть отправлен на сервер.

При использовании Schannel SSP, если указан флаг ISC_REQ_ALLOCATE_MEMORY, Schannel SSP выделяет память для буфера и помещает соответствующие сведения в SecBufferDesc. Кроме того, вызывающий объект должен передать буфер типа SECBUFFER_ALERT. Если создается оповещение, этот буфер содержит сведения об этом оповещении, а функция завершается ошибкой.

pfContextAttr[out]

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

Флаги, используемые для этого параметра, префиксируются ISC_RET, например ISC_RET_DELEGATE. Список допустимых значений см. в параметре fContextReq .

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

Примечание.

Определенные атрибуты контекста могут изменяться во время согласования с удаленным одноранговым узлом.

ptsExpiry[out, optional]

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

Срок действия контекстабезопасности или учетных данных microsoft Digest SSP отсутствует.

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

Если функция выполнена успешно, функция возвращает один из следующих кодов успешного выполнения.

Код возврата	Description
SEC_I_COMPLETE_AND_CONTINUE	Клиент должен вызвать CompleteAuthToken , а затем передать выходные данные серверу. Затем клиент ожидает возвращаемого маркера и передает его в другом вызове в InitializeSecurityContext (General).
SEC_I_COMPLETE_NEEDED	Клиент должен завершить сборку сообщения, а затем вызвать функцию CompleteAuthToken .
SEC_I_CONTINUE_NEEDED	Клиент должен отправить выходной маркер серверу и ждать возвращаемого маркера. Затем возвращенный маркер передается в другой вызов InitializeSecurityContext (General). Выходной маркер может быть пустым.
SEC_I_INCOMPLETE_CREDENTIALS	Используйте с Schannel. Сервер запросил проверку подлинности клиента, и предоставленные учетные данные либо не включают сертификат, либо сертификат не был выдан центром сертификации, доверенным сервером. Дополнительные сведения см. в подразделе "Примечания".
SEC_E_INCOMPLETE_MESSAGE	Используйте с Schannel. Данные для всего сообщения не считывались из провода. При возврате этого значения буфер pInput содержит структуру SecBuffer с элементом BufferType SECBUFFER_MISSING. Член cbBuffer secBuffer содержит значение, указывающее количество дополнительных байтов, которые функция должна считывать от клиента до успешного выполнения этой функции. Хотя это число не всегда является точным, использование может помочь повысить производительность, избегая нескольких вызовов этой функции.
SEC_E_OK	Контекст безопасности успешно инициализирован. Для другого вызова InitializeSecurityContext (General) не требуется. Если функция возвращает выходной маркер, то есть если SECBUFFER_TOKEN в pOutput имеет ненулевое значение, этот маркер должен быть отправлен на сервер.

Если функция завершается ошибкой, функция возвращает один из следующих кодов ошибок.

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

Замечания

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

Если атрибуты контекста безопасности недостаточно, клиент должен освободить частично созданный контекст, вызвав функцию DeleteSecurityContext.

Функция InitializeSecurityContext (General) используется клиентом для инициализации исходящего контекста.

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

Клиент вызывает функцию с набором phContextNULL и заполняет дескриптор буфера входным сообщением.
Пакет безопасности проверяет параметры и создает непрозрачный маркер, помещая его в элемент TOKEN в буферный массив. Если параметр fContextReq включает флаг ISC_REQ_ALLOCATE_MEMORY, пакет безопасности выделяет память и возвращает указатель в элементе TOKEN.
Клиент отправляет маркер, возвращенный в буфере pOutput , на целевой сервер. Затем сервер передает маркер в качестве входного аргумента в вызове функции AcceptSecurityContext (General).
AcceptSecurityContext (General) может возвращать маркер, который сервер отправляет клиенту для второго вызова InitializeSecurityContext (General), если первый вызов вернулся SEC_I_CONTINUE_NEEDED.

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

Клиент вызывает функцию, как описано ранее, но пакет возвращает код успешного выполнения SEC_I_CONTINUE_NEEDED.
Клиент отправляет выходной маркер серверу и ожидает ответа сервера.
После получения ответа сервера клиент снова вызывает InitializeSecurityContext (General) с параметром phContext для дескриптора, возвращенного из последнего вызова. Маркер, полученный от сервера, предоставляется в параметре pInput .
Не используйте значение phContext в одновременных вызовах InitializeSecurityContext (General). Реализация в поставщиках безопасности не является потокобезопасной.

Если сервер успешно ответил, пакет безопасности возвращает SEC_E_OK и устанавливается безопасный сеанс.

Если функция возвращает один из ответов на ошибки, ответ сервера не принимается, а сеанс не установлен.

Если функция возвращает SEC_I_CONTINUE_NEEDED, SEC_I_COMPLETE_NEEDED или SEC_I_COMPLETE_AND_CONTINUE, шаги 2 и 3 повторяются.

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

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

Если установлен флаг ISC_REQ_USE_SUPPLIED_CREDS, пакет безопасности должен искать тип буфера SECBUFFER_PKG_PARAMS в входном буфере pInput . Это не универсальное решение, но оно позволяет при необходимости связывать пакет безопасности и приложение.

Если был указан ISC_REQ_ALLOCATE_MEMORY, вызывающий объект должен освободить память, вызвав функцию FreeContextBuffer .

Например, входной маркер может быть вызовом диспетчера локальной сети. В этом случае выходной маркер будет зашифрованным в NTLM ответом на проблему.

Действие, которое выполняет клиент, зависит от кода возврата из этой функции. Если код возврата SEC_E_OK, второй вызов InitializeSecurityContext (General) не будет, а ответ от сервера не ожидается. Если код возврата SEC_I_CONTINUE_NEEDED, клиент ожидает маркер в ответ от сервера и передает его во второй вызов InitializeSecurityContext (General). Код возврата SEC_I_COMPLETE_NEEDED указывает, что клиент должен завершить сборку сообщения и вызвать функцию CompleteAuthToken . Код SEC_I_COMPLETE_AND_CONTINUE включает оба этих действия.

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

Клиент может снова вызвать InitializeSecurityContext (General) после успешного завершения. Это указывает на пакет безопасности, который требуется повторной проверки подлинности.

Вызывающие вызовы режима ядра имеют следующие отличия: целевое имя — это строка Юникода , которая должна быть выделена в виртуальной памяти с помощью VirtualAlloc; она не должна быть выделена из пула. Буферы, передаваемые и предоставленные в pInput и pOutput, должны находиться в виртуальной памяти, а не в пуле.

При использовании Schannel SSP, если функция возвращает SEC_I_INCOMPLETE_CREDENTIALS, проверка, которые вы указали действительный и доверенный сертификат в учетных данных. Сертификат указывается при вызове функции AcquireCredentialsHandle (General). Сертификат должен быть сертификатом проверки подлинности клиента, выданным центром сертификации (ЦС), доверенным сервером. Чтобы получить список доверенных ЦС сервера, вызовите функцию QueryContextAttributes (General) и укажите атрибут SECPKG_ATTR_ISSUER_LIST_EX.

При использовании Schannel SSP после получения клиентского приложения сертификата проверки подлинности из ЦС, доверенного сервером, приложение создает новые учетные данные, вызывая функцию AcquireCredentialsHandle (General), а затем снова вызывая initializeSecurityContext (General), указав новые учетные данные в параметре phCredential .

Требования

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