КриптоПро SSPI  

InitializeSecurityContext

Функция 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 World Wide Web link. При первом вызове, укажите NULL. При последующих - указатель на дескриптор, возвращенный в phNewContext после первого вызова к этой функции.
pszTargetName
[in] Строка, являющаяся уникальным идентификатором сервера. Используется при поиске сессии в кеше сессий при восстановлении соединения.
fContextReq
[in] Показывает, какой набор свойств должен поддерживать контекст. Допустимые флаги перечислены в следующей таблице:
ФлагОписание
ISC_REQ_REPLAY_DETECTЗащита от навязывания повторных пакетов
ISC_REQ_SEQUENCE_DETECTЗащита от навязывания перестановок пакетов
ISC_REQ_CONFIDENTIALITYКонциденциальность (шифрование)
ISC_REQ_STREAMСоединение потокового типа
ISC_REQ_ALLOCATE_MEMORYSSP отводит память для буферов. Ее необходимо освободить вызовом FreeContextBuffer
ISC_REQ_EXTENDED_ERRORУведомлять другую сторону об ошибках (SSL alerts)
ISC_REQ_CONNECTIONНеформатированные сообщения
ISC_REQ_MUTUAL_AUTHВзаимная аутентификация
ISC_REQ_USE_SUPPLIED_CREDSSSP не будет пытаться искать удостоверение, если оно не предоставлено приложением
ISC_REQ_MANUAL_CRED_VALIDATIONSSP не будет проверять удостоверение другой стороны
Может оказаться так, что клиент поддерживает не все из запрошенных параметров. Дальнейшие детали смотрите в описании параметра pfContextAttr
Reserved1
[in] Зарезервирован. Должен быть 0.
TargetDataRep
[in] Параметр зарезервирован для будущего использования и должен быть 0.
pInput
[in] указатель на структуру SecBufferDesc World Wide Web link. При первом вызове должен быть NULL. При последующих вызовах должен состоять из двух структур SecBuffer World Wide Web link. Первый буфер должен иметь тип SECBUFFER_TOKEN, и содержать пакет, полученый от сервера. Второй буфер должен иметь тип SECBUFFER_EMPTY. В него в случае необходимости будут помещены оставшиеся необработанные входные данные.
Reserved2
[in] Зарезервирован. Должен быть 0.
phNewContext
[in/out] Указатель на CtxtHandle World Wide Web link. При первом вызове сюда будет помещен дескриптор нового контекста. При последующих вызовах полученный дескриптор следует передавать через параметр phContext, а в phNewContext передавать NULL
pOutput
[in] Указатель на структуру SecBufferDesc World Wide Web link, содержащую SecBuffer World Wide Web link с типом SECBUFFER_TOKEN. На выходе в этот буфер будет помещен пакет, который нужно переслать серверу. При наличии флага ISC_REQ_ALLOCATE_MEMORY этот буфер будет отведен.
pfContextAttr
[out] Указатель на ULONG, куда будут записаны флаги, описывающие свойства устанавливаемого контекста. Список возможных значений приведен в описании параметра fContextReq. pfContextAttr получает тот же набор флагов, с заменой префикса ISC_REQ на ISC_RET.
Warning Атрибуты безопасности не следует проверять до последнего вызова функции, возвращающего SEC_E_OK. Остальные атрибуты, такие как ISC_RET_ALLOCATED_MEMORY можно использовать после первого же вызова.
ptsExpiry
[out] Опционален. Указатель на структуру TimeStamp. При наличии сертификата клиента, этот параметр получает время истечения этого сертификата. Иначе возвращается максимальное возможное значение времени. Врямя возвращается в UTC.

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

При успешном завершении функция возвращает одно из следующих значений:
Коды возвратаОписание
SEC_E_OKКонтекст безопасности был успешно установлен. Дальнейших вызовов к этой функции не требуется. Если функция вернула данные в pOutput, их следует переслать серверу.
SEC_E_INCOMPLETE_MESSAGEДанные во входном буфере неполны. Приложение должно прочитать остальные данные, и снова вызвать InitializeSecurityContext.
SEC_I_INCOMPLETE_CREDENTIALSСервер запросил аутентификацию клиента, а указанное удостоверение не содержит сертификата, или сертификат издан не доверенным центром сертификации.
SEC_I_CONTINUE_NEEDEDКлиент должен послать выходные данные серверу и ждать ответа. Полученный ответ полжен быть передан при следующем вызове в InitializeSecurityContext через параметр pInput.

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

В случае ошибки функция возвращает одно из следующих значений:
Коды возвратаОписание
SEC_E_INVALID_TOKENПараметр pInput содержит неправильные входные данные.
SEC_E_INVALID_HANDLEПараметр phContext содержит недействительный дескриптор контекста.
SEC_E_NO_CREDENTIALSПредоставленное удостоверение недостоверно.
SEC_E_UNSUPPORTED_FUNCTIONПараметр fContextReq содержит неподдерживаемый набор флагов.
SEC_E_INSUFFICIENT_MEMORYОдин из буферов оказался слишком мал. См. заметки.

Примечания

На стороне сервера для создания контекста используется парная функция 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 World Wide Web link ,DeleteSecurityContext() ,AcceptSecurityContext() ,SecBuffer World Wide Web link ,SecBufferDesc World Wide Web link ,FreeContextBuffer() ,TimeStamp World Wide Web link