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

Статья
03/08/2023

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

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

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

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

Синтаксис

SECURITY_STATUS SEC_ENTRY InitializeSecurityContextA(
  [in, optional]      PCredHandle    phCredential,
  [in, optional]      PCtxtHandle    phContext,
                      SEC_CHAR       *pszTargetName,
  [in]                unsigned long  fContextReq,
  [in]                unsigned long  Reserved1,
  [in]                unsigned long  TargetDataRep,
  [in, optional]      PSecBufferDesc pInput,
  [in]                unsigned long  Reserved2,
  [in, out, optional] PCtxtHandle    phNewContext,
  [in, out, optional] PSecBufferDesc pOutput,
  [out]               unsigned long  *pfContextAttr,
  [out, optional]     PTimeStamp     ptsExpiry
);

Параметры

[in, optional] phCredential

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

[in, optional] phContext

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

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

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

pszTargetName

TBD

[in] fContextReq

Битовые флаги, указывающие запросы для контекста. Не все пакеты могут поддерживать все требования. Флаги, используемые для этого параметра, имеют префикс 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. Опустите этот флаг, чтобы использовать digest в качестве механизма 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 игнорируется. Это значение поддерживается только пакетами безопасности Negotiate и 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 .

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

[in] Reserved1

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

[in] TargetDataRep

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

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

[in, optional] pInput

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

[in] Reserved2

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

[in, out, optional] phNewContext

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

При использовании Schannel SSP при вызовах после первого вызова передайте возвращенный сюда дескриптор в качестве параметра phContext и укажите ЗНАЧЕНИЕ NULL для phNewContext.

[in, out, optional] pOutput

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

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

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

[out] pfContextAttr

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

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

Список допустимых значений см. в параметре fContextReq .

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

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

[out, optional] ptsExpiry

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

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

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

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

Код возврата	Описание
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 с элементом BufferTypeSECBUFFER_MISSING. Элемент cbBufferэлемента SecBuffer содержит значение, указывающее количество дополнительных байтов, которые функция должна считывать у клиента перед выполнением этой функции. Хотя это число не всегда является точным, его использование может помочь повысить производительность, избегая нескольких вызовов этой функции.
SEC_E_OK	Контекст безопасности успешно инициализирован. Другой вызов InitializeSecurityContext (General) не требуется. Если функция возвращает выходной маркер, т. е. если SECBUFFER_TOKEN в pOutput имеет ненулевое значение длины, этот маркер должен быть отправлен на сервер.

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

Код возврата	Описание
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) используется клиентом для инициализации исходящего контекста.

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

Клиент вызывает функцию с параметром phContext , имеющим значение NULL , и заполняет дескриптор буфера входным сообщением.
Пакет безопасности проверяет параметры и создает непрозрачный маркер, помещая его в элемент 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 .

Если сервер успешно ответил, пакет безопасности возвращает 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 (Общий) не будет выполняться, а ответ от сервера не ожидается. Если код возврата 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 .

Примечание

Заголовок sspi.h определяет InitializeSecurityContext как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

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