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

Возвращает handshake-сообщения, которые клиент должен передать серверу, и обрабатывает ответные handshake-сообщения.

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

Аргументы

phCredential

[in] Указатель на дескриптор удостоверения клиента. Указанный дескриптор получается через запрос к функции AcquireCredentialsHandle.

phContext

[in] Указатель на CtxtHandle . При первом вызове, укажите NULL. При последующих - указатель на дескриптор, возвращенный в phNewContext после первого вызова к этой функции.

pszTargetName

[in] Строка, являющаяся уникальным идентификатором сервера. Используется при поиске сессии в кеше сессий при восстановлении соединения.

fContextReq

[in] Показывает, какой набор свойств должен поддерживать контекст. Допустимые флаги перечислены в следующей таблице:

Флаг	Описание
ISC_REQ_REPLAY_DETECT	Защита от навязывания повторных пакетов
ISC_REQ_SEQUENCE_DETECT	Защита от навязывания перестановок пакетов
ISC_REQ_CONFIDENTIALITY	Конфиденциальность (шифрование)
ISC_REQ_STREAM	Соединение потокового типа
ISC_REQ_ALLOCATE_MEMORY	SSP отводит память для буферов. Ее необходимо освободить вызовом FreeContextBuffer
ISC_REQ_EXTENDED_ERROR	Уведомлять другую сторону об ошибках (SSL alerts)
ISC_REQ_CONNECTION	Неформатированные сообщения
ISC_REQ_MUTUAL_AUTH	Взаимная аутентификация
ISC_REQ_USE_SUPPLIED_CREDS	SSP не будет пытаться искать удостоверение, если оно не предоставлено приложением
ISC_REQ_MANUAL_CRED_VALIDATION	SSP не будет проверять удостоверение другой стороны

Может оказаться так, что клиент поддерживает не все из запрошенных параметров. Дальнейшие детали смотрите в описании параметра pfContextAttr

Reserved1

[in] Зарезервирован. Должен быть 0.

TargetDataRep

[in] Параметр зарезервирован для будущего использования и должен быть 0.

pInput

[in] указатель на структуру SecBufferDesc . При первом вызове должен быть NULL, но может содержать структуру SecBuffer типа SECBUFFER_APPLICATION_PROTOCOLS с протоколами уровня приложений, используемых для согласования Application-Layer Protocol Negotiation Protocol Negotiation; данные в буфере должны содержать упакованную структуру SEC_APPLICATION_PROTOCOLS. При последующих вызовах pInput должен состоять из двух структур SecBuffer . Первый буфер должен иметь тип SECBUFFER_TOKEN, и содержать пакет, полученный от сервера. Второй буфер должен иметь тип SECBUFFER_EMPTY. В него в случае необходимости будут помещены оставшиеся необработанные входные данные с типом SECBUFFER_EXTRA, или, eсли полученное сообщение неполно (SEC_E_INCOMPLETE_MESSAGE), во втором буфере типа SECBUFFER_MISSING будет возвращен ожидаемый размер входных данных.

Reserved2

[in] Зарезервирован. Должен быть 0.

phNewContext

[in/out] Указатель на CtxtHandle . При первом вызове сюда будет помещен дескриптор нового контекста. При последующих вызовах полученный дескриптор следует передавать через параметр phContext, а в phNewContext передавать NULL

pOutput

[in] Указатель на структуру SecBufferDesc , содержащую SecBuffer с типом SECBUFFER_TOKEN. На выходе в этот буфер будет помещен пакет, который нужно переслать серверу. При наличии флага ISC_REQ_ALLOCATE_MEMORY этот буфер будет выделен SSPI и должен быть освобожден с помощью функции FreeContextBuffer.

pfContextAttr

[out] Указатель на ULONG, куда будут записаны флаги, описывающие свойства устанавливаемого контекста. Список возможных значений приведен в описании параметра fContextReq. pfContextAttr получает тот же набор флагов, с заменой префикса ISC_REQ на ISC_RET.
Warning Атрибуты безопасности не следует проверять до последнего вызова функции, возвращающего SEC_E_OK. Остальные атрибуты, такие как ISC_RET_ALLOCATED_MEMORY можно использовать после первого же вызова.

ptsExpiry

[out] Опционален. Указатель на структуру TimeStamp. При наличии сертификата клиента, этот параметр получает время истечения этого сертификата. Иначе возвращается максимальное возможное значение времени. Время возвращается в UTC.

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

При успешном завершении функция возвращает одно из следующих значений:

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

В случае ошибки функция возвращает одно из следующих значений:

Примечания

На стороне сервера для создания контекста используется парная функция AcceptSecurityContext. При получении кода ошибки SEC_E_INSUFFICIENT_MEMORY, укажите атрибут ISC_REQ_ALLOCATE_MEMORY в fContextReq. При получении кода SEC_I_INCOMPLETE_CREDENTIALS, убедитесь, что при вызове AcquireCredentialsHandle был указан действующий сертификат, изданный центром, которому доверяет сервер. Список таких центров может быть получен вызовом QueryContextAttributes с атрибутом SECPKG_ATTR_ISSUER_LIST_EX. Найдя такой сертификат, создайте новое удостоверение вызовом к AcquireCredentialsHandle, и вызовите InitializeSecurityContext еще раз, с новым удостоверением.
Вызывающее приложение должно определить допустимость атрибутов установленного контекста. Например, если конфиденциальность соединения была запрошена, но не была достигнута, некоторые приложения должны принять решение немедленно прекратить соединение. Если контекст не смог быть установлен, сервер должен удалить частично созданный контекст вызовом DeleteSecurityContext.

Требования:

AIX: 5.3 или выше.
FreeBSD: 7 или выше.
Linux: LSB 3.1 (RHEL 4, SuSE 10) или выше.
Solaris: 10 или выше.
Windows 2000 или выше: Необходимо Windows 2000 SP4 или старше с Internet Explorer 6.0 или старше.
Файл описания: Прототип описан в файле sspi.h для Windows и CSP_Sspi.h, CSP_SChannel.h, CpSSP.h для Unix.

См. также

AcquireCredentialsHandle() ,CtxtHandle ,DeleteSecurityContext() ,AcceptSecurityContext() ,SecBuffer ,SecBufferDesc ,FreeContextBuffer() ,TimeStamp