Функция InitializeSecurityContext (CredSSP)

Функция 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
);

Параметры

phКвалификация[in, optional]

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

phКонтекст[in, optional]

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

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

pTargetName[in, optional]

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

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

fContextReq[in]

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

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

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

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

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

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

Целевой файл DataRep[in]

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

pInput[in, out, optional]

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

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

Зарезервировано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 , можно проверить до окончательного возврата.

ptsИстечение срока действия[out, optional]

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

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

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

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

Замечания

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

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

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

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

1. Клиент вызывает функцию с набором phContextNULL и заполняет дескриптор буфера входным сообщением.
2. Пакет безопасности проверяет параметры и создает непрозрачный маркер, помещая его в элемент TOKEN в буферный массив. Если параметр fContextReq включает флаг ISC_REQ_ALLOCATE_MEMORY , пакет безопасности выделяет память и возвращает указатель в элементе TOKEN.
3. Клиент отправляет маркер, возвращенный в буфере pOutput , на целевой сервер. Затем сервер передает маркер в качестве входного аргумента в вызове функции AcceptSecurityContext (CredSSP).
4. 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 .

Требования

См. также

Функции SSPI

AcceptSecurityContext (CredSSP)

AcquireCredentialsHandle (CredSSP)

CompleteAuthToken (Токен CompleteAuth)

DeleteSecurityContext (УдалитьSecurityContext)

FreeContextBuffer (Буфер свободного контекста)

СекБуфер

SecBufferDesc (СекБуферДеск)