Функция InitializeSecurityContext (CredSSP)

Статья
03/18/2023

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

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

Синтаксис

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

Параметры

phCredential[in, optional]

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

phContext[in, optional]

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

При первом вызове Метода InitializeSecurityContext (CredSSP) укажите NULL. При последующих вызовах укажите токен, полученный в параметре phNewContext после первого вызова этой функции.

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

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

pTargetName[in, optional]

Указатель на строку, завершающуюся значением NULL, которая однозначно идентифицирует целевой сервер. Schannel использует это значение для проверки сертификата сервера. Schannel также использует это значение для поиска сеанса в кэше сеансов при повторном создании подключения. Кэшированный сеанс используется только в том случае, если выполняются все следующие условия:

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

fContextReq[in]

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

Этот параметр может быть одним или несколькими из следующих флагов атрибутов.

Значение	Значение
ISC_REQ_ALLOCATE_MEMORY `0x100`	Пакет безопасности выделяет выходные буферы для вызывающей стороны. Завершив использование буферов вывода, освободите их, вызвав функцию FreeContextBuffer .
ISC_REQ_CONNECTION `0x800`	Контекст безопасности не будет обрабатывать сообщения форматирования.
ISC_REQ_EXTENDED_ERROR `0x4000`	При возникновении ошибок удаленная сторона будет уведомлена.
ISC_REQ_MANUAL_CRED_VALIDATION `0x80000`	Поставщик поддержки безопасности учетных данных (CredSSP) не должен автоматически проверять подлинность сервера. Этот флаг всегда устанавливается при использовании CredSSP.
ISC_REQ_SEQUENCE_DETECT `0x8`	Обнаружение сообщений, полученных вне последовательности.
ISC_REQ_STREAM `0x8000`	Поддержка потокового подключения.
ISC_REQ_USE_SUPPLIED_CREDS `0x80`	CredSSP не должен пытаться автоматически предоставлять учетные данные для клиента.
ISC_REQ_DELEGATE `0x1`	Указывает, что учетные данные пользователя должны быть делегированы серверу. Если этот флаг не указан, серверу делегируется пустой набор учетных данных. Windows Server 2008 и Windows Vista: Этот флаг является обязательным.
ISC_REQ_MUTUAL_AUTH `0x2`	Указывает, что проверка подлинности сервера не требуется. Политики делегирования по-прежнему применяются, если этот флаг не указан. Windows Server 2008 и Windows Vista: Этот флаг игнорируется.

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

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

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

Зарезервировано. Для этого параметра необходимо задать нулевое значение.

TargetDataRep[in]

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

pInput[in, out, optional]

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

При вызове этой функции после первоначального вызова должно быть два буфера. Первый имеет тип SECBUFFER_TOKEN и содержит маркер, полученный от сервера. Второй буфер имеет тип SECBUFFER_EMPTY; Установите для обоих элементов pvBuffer и cbBuffer значение 0.

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

Зарезервировано. Для этого параметра необходимо задать нулевое значение.

phNewContext[in, out, optional]

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

pOutput[out, optional]

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

Если указан флаг ISC_REQ_ALLOCATE_MEMORY , CredSSP выделяет память для буфера и помещает соответствующие сведения в SecBufferDesc.

pfContextAttr[out]

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

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

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

Примечание

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

ptsExpiry[out, optional]

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

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

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

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

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

Код возврата	Описание
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	Недопустимое значение параметра fContextReq . Либо не указан обязательный флаг, либо был указан флаг, который не поддерживается CredSSP.
SEC_E_WRONG_PRINCIPAL	Субъект, получивший запрос проверки подлинности, отличается от субъекта, переданного в параметр pszTargetName . Эта ошибка указывает на сбой во взаимной проверке подлинности.
SEC_E_DELEGATION_POLICY	Политика не поддерживает делегирование учетных данных на целевой сервер.
SEC_E_POLICY_NLTM_ONLY	Делегирование учетных данных на целевой сервер не допускается, если не выполняется взаимная проверка подлинности.
SEC_E_MUTUAL_AUTH_FAILED	Проверка подлинности сервера завершилась сбоем, если флаг ISC_REQ_MUTUAL_AUTH указан в параметре fContextReq .

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

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

Клиент вызывает функцию InitializeSecurityContext (CredSSP) для инициализации исходящего контекста.

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

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

Если сервер успешно ответил, пакет безопасности возвращает 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 (CredSSP) не будет выполняться, а ответ от сервера не ожидается. Если код возврата SEC_I_CONTINUE_NEEDED, клиент ожидает маркер в ответ от сервера и передает его во втором вызове InitializeSecurityContext (CredSSP). Код возврата SEC_I_COMPLETE_NEEDED указывает, что клиент должен завершить сборку сообщения и вызвать функцию CompleteAuthToken . Код SEC_I_COMPLETE_AND_CONTINUE включает в себя оба этих действия.

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

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

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

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

После получения сертификата проверки подлинности от центра сертификации, которому сервер доверяет, клиентское приложение создает новые учетные данные. Для этого вызовите функцию AcquireCredentialsHandle (CredSSP), а затем снова вызовите InitializeSecurityContext (CredSSP), указав новые учетные данные в параметре phCredential .

Требования

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