Функция InitializeSecurityContext (Digest)

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

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

Синтаксис

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
);

Параметры

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

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

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

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

pszTargetName[in, optional]

Указатель на строку, завершающуюся значением NULL, которая однозначно идентифицирует URI запрошенного ресурса. Строка должна состоять из символов, которые разрешены в URI и должны представляться набором кода ASCII в США. Кодировка процентов может использоваться для представления символов за пределами набора кода ASCII в США.

fContextReq[in]

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

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

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

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

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

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

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

pInput[in, optional]

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

Сведения о конфигурации буфера см. в разделе Входные буферы для ответа на вызов дайджеста.

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

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

phNewContext[in, out, optional]

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

pOutput[in, out, optional]

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

Этот параметр получает ответ на запрос, который должен быть отправлен серверу.

pfContextAttr[out]

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

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

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

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

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

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

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

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

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

Замечания

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

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

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

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

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

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

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

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

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

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

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

Требования

См. также

Функции SSPI

AcceptSecurityContext (Дайджест)

AcquireCredentialsHandle (дайджест)

CompleteAuthToken (Токен CompleteAuth)

DeleteSecurityContext (УдалитьSecurityContext)

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

СекБуфер

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