КриптоПро CSP 2.0

127018, Москва, Улица Образцова, 38
Телефон: (095) 933 1168
Факс: (095) 933 1168
http://www.CryptoPro.ru
E-mail: info@CryptoPro.ru

Средство Криптографической Защиты Информации

КриптоПро CSP

Версия 2.0

Руководство программиста

Часть 2. Модуль поддержки сетевой аутентификации КриптоПро TLS

ЖТЯИ.00005-01 90 03

© OOO "Крипто-Про", 2000-2002. Все права защищены.
Авторские права на средство криптографической защиты информации КриптоПро TLS и эксплуатационную документацию зарегистрированы в Российском агентстве по патентам и товарным знакам (Роспатент). Свидетельство об официальной регистрации программ для ЭВМ № 2001610275 от 14 марта 2001 года.
Документ входит в комплект поставки программного обеспечения КриптоПРО TLS, и на него распространяются все условия лицензионного соглашения. Без специального письменного разрешения OOO "Крипто-Про" документ или его часть в электронном или печатном виде не могут быть скопированы и переданы третьим лицам с коммерческой целью.


Введение

КриптоПро CSP 2.0

ЖТЯИ.00005-01 30 01

© OOO "Крипто-Про" 2000-2002

Средство
Криптографической
Защиты
Информации

КриптоПро CSP 2.0

Модуль поддержки сетевой аутентификации КриптоПро TLS

Модуль КриптоПро TLS разработан в соответствии с криптографическим интерфейсом корпорации Microsoft - Security Service Provider Interface (SSPI). Модуль КриптоПро TLS используется с СКЗИ КриптоПро CSP, реализующим российские криптографические алгоритмы. Он встраивается в системы Microsoft в качестве дополнения к стандартному модулю Schannel, реализующему протокол TLS/SSL (RFC 2246) на иностранных алгоритмах.

Область применения

Интеграция модуля КриптоПро TLS с операционной системой Windows позволила использовать технологии Microsoft с российскими криптографическими алгоритмами для аутентификации и защиты каналов связи по протоколу TLS/SSL (RFC 2246) на основе Инфраструктуры Открытых Ключей (Public Key Infrastructure), соответствующей международным рекомендациям X.509, RFC 2459 и Федеральному закону "Об электронной цифровой подписи".

Использование модуля КриптоПро CSP позволяет:

  • Для корпоративных пользователей - обеспечивать возможность использования стандартных и широко используемых приложений корпорации Microsoft с надежной российской криптографией.
  • Для системных интеграторов - обеспечивать возможность создания новых, надежно защищенных приложений с использованием обширного и проверенного временем инструментария корпорации Microsoft.

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

  • Веб-обозреватель - Microsoft Internet Explorer
  • Веб-сервер - Microsoft Internet Information Server
  • Firewall - Microsoft Internet Security and Acceleration Server
  • Электронная почта - Microsoft Outlook
  • Электронная почта - Microsoft Outlook Express

Аннотация

Краткое описание модуля КриптоПро TLS.

Архитектура

Архитектура пакетов безопасности операционной системы Windows (SSPI).

Руководство программиста

Описание функций, структур, переменных модуля КриптоПро TLS.

Обратная связь

Связь с разработчиком.
Поддержка.
Конференция.


СКЗИ Крипто-Про TLS

КриптоПро TLS

Средство криптографической защиты информации КриптоПро CSP версия 2.0

Модуль поддержки сетевой аутентификации КриптоПро TLS

Основные функции, реализуемые модулем КриптоПро TLS

  • Две схемы аутентификации с использованием обмена ключей по алгоритму Диффи-Хэллмана и хэширования в соответствии с ГОСТ Р 34.11-94.
    • односторонняя - анонимный клиент, аутентифициремый сервер;
    • двухстороняя - аутентифициремые клиент и сервер;
    В случае аутентификации клиента на ключе подписи применяются алгоритмы выработки и проверки электронной цифровой подписи в соответствии с ГОСТ Р 34.10-94 или ГОСТ Р 34.10-2001.
  • шифрование соединения в соответствии с ГОСТ 28147-89 ("Системы обработки информации. Защита криптографическая.");
  • имитозащита передаваемых данных в соответствии с ГОСТ 28147-89;

Операционные системы

Модуль КриптоПро TLS функционирует в следующих операционных системах (ОС):

  • Windows 98 с установленным ПО MS Internet Explorer версии 5.0 и выше;
  • Windows 98 SE с установленным ПО MS Internet Explorer версии 5.0 и выше;
  • Windows NT 4.0 SP5 и выше с установленным ПО MS Internet Explorer 5.0 и выше;
  • Windows ME;
  • Windows 2000;
  • Windows XP.

На платформах Microsoft Windows 98/98 SE/ME/NT/2000/XP, используемых с СКЗИ "КриптоПро CSP", должна быть произведена установка следующих двух пакетов обновлений:

  1. Microsoft Security Bulletin MS02-048. Flaw in Certificate Enrollment Control Could Allow Deletion of Digital Certificates (Q323172). August 28, 2002. Доступ по адресу: http://www.microsoft.com/technet/treeview/default.asp?url=/technet/ security/bulletin/MS02-048.asp

  2. Microsoft Security Bulletin MS02-050. Certificate Validation Flaw Could Enable Identity Spoofing (Q328145). September 09, 2002. Доступен по адресу: http://www.microsoft.com/technet/treeview/default.asp?url=/technet/ security/bulletin/MS02-050.asp

Примечание 1. Полный перечень операционных систем и дополнительные требования, необходимые для функционирования СКЗИ приведены в документе "КриптоПро CSP. Описание реализации", ЖТЯИ.00005-01 90 01.

Примечание 2. Порядок и сроки эксплуатации операционных систем, в среде которых функционирует СКЗИ КриптоПро TLS v. 2.0, определяются производителями операционных систем.

Примечание 3. При выборе ОС необходимо учитывать следующие сроки поддержки и окончания эксплуатации операционных систем (по данным фирмы Microsoft на 03.07.2002 г. http://www.microsoft.com/windows/lifecycle.mspx):

ОС | Поддержка | Окончание эксплуатации
Microsoft Windows 98 | 30 июня 2002 г. | 30 июня 2003 г.
Microsoft Windows 98 SE | 30 июня 2002 г. | 30 июня 2003 г
Microsoft Windows NT 4/xx | 30 июня 2002 г. | 30 июня 2003 г
Microsoft Windows 2000 | 31 марта 2003 г. |
Microsoft Windows ME | 31 декабря 2003 г. |

Интеграция с прикладным программным обеспечением

О способах использования модуля КриптоПро TLS смотрите в разделе Работа с пакетами безопасности операционной системы Windows.


СКЗИ Крипто-Про CSP

Работа с пакетами безопасности Windows

Работа с пакетами безопасности Windows

При разработке модуля КриптоПро TLS учитывалась существующая в операционной системе Windows архитектура пакетов безопасности. В соответствии с этой архитектурой протоколы защищенного обмена реализуются через специфицированный Microsoft интерфейс - Security Service Provider Interface (SSPI) (См. http://msdn.microsoft.com/library/en-us/security/security/sspi.asp).

В соответствии с существующей в операционной системе Windows архитектуре использования пакетов безопасности модуль КриптоПро TLS возможно использовать как в стандартном программном обеспечении Microsoft, так и встраивать в разрабатываемое прикладное программное обеспечение.

Использование в программном обеспечении Microsoft

  • Электронная почта - Microsoft Outlook 98, 2000, XP (http://www.microsoft.com/technet/security/outlksec.asp);
  • Электронная почта - Microsoft Outlook Express, входящая в состав Internet Explorer версии 5.0 или выше (http://www.microsoft.com/TechNet/win2000/pubkeyox.asp);
  • Защищенный доступ к Web - Internet Explorer версии 5.0 или выше.
  • Защищенный Web-сервер - Internet Information Service 5.0(4.0).

Встраивание модуля КриптоПро TLS

Кроме использования протокола TLS в интерфейсе Internet Explorer, прикладное программное обеспечение может использовать протокол TLS для аутентификации и защиты данных, передаваемых по собственным протоколам на основе TCP/IP и HTTPS.

Примеры встраивания имеются в тестовом ПО разработки ООО "Крипто-Про" (http://www.cryptopro.ru/CryptoPro/test/sample.zip и http://www.cryptopro.ru/CryptoPro/product14.html, файлы WebClient.c, WebServer.c, tls.c), а также в составе Microsoft Platform SDK (\Samples\WinBase\Security\SSL).

Инициализация библиотеки SSP

Производится загрузка библиотеки Secur32.dll, Security.dll при работе с операционными системами Windows NT 4.0, Windows 2000, Windows ХР; библиотеки schannel.dll - при работе с операционными системами Windows 95, Windows 95 OSR2, Windows 98, Windows 98 SE, Windows ME.

С помощью функции GetProcAddress получается указатель на функцию InitSecurityInterfaceA (InitSecurityInterfaceW в случае компиляции с Unicode).

Вызовом функции InitSecurityInterfaceA (InitSecurityInterfaceW в случае компиляции с Unicode) получается таблица функций SSPI.

Заполняется структура SCHANNEL_CRED. Поля этой структуры должны быть нулевыми, кроме:

SchannelCred.dwVersion = SCHANNEL_CRED_VERSION;
SchannelCred.dwFlags = SCH_CRED_NO_DEFAULT_CREDS | SCH_CRED_MANUAL_CRED_VALIDATION;
Для сервера и не анонимного клиента заполняются также поля:
SchannelCred.cCreds     = 1;
SchannelCred.paCred     = &pCertContext.

Примечание. Контекст сертификата pCertContext должен содержать ссылку на секретный ключ.

Производится вызов функции создания Credentials: AcquireCredentialsHandle с передачей ей структуры SCHANNEL_CRED и имени пакета - UNISP_NAME ("Microsoft Unified Security Protocol Provider").

Инициализация соединения клиентом производится вызовом InitializeSecurityContext без входного буфера и сервером - вызовом AcceptSecurityContext, после чего идет обычный цикл Handshake.

После установления соединения, но до начала передачи данных, приложение должно выполнить проверку параметров соединения и сертификата удаленной стороны.

Для получения сертификата удаленной стороны вызывается функция QueryContextAttributes с аргументом SECPKG_ATTR_REMOTE_CERT_CONTEXT.

Для построения цепочки сертификатов рекомендуется использование функции CertGetCertificateChain, описанную в MSDN/Platform SDK/Security, (с флагами проверки, соответствующими выбранному уровню безопасности. Рекомендуется использовать флаг CERT_CHAIN_CACHE_END_CERT | CERT_CHAIN_REVOCATION_CHECK_CHAIN.

Цепочка сертификатов проверяется функцией CertVerifyCertificateChainPolicy, описанной там же, с аргументом pszPolicy, равным OIDCERT_CHAIN_POLICY_SSL, и аргументом pPolicyPara, заполненным следующим образом:

    ZeroMemory(&polHttps, sizeof(HTTPSPolicyCallbackData));
    polHttps.cbStruct           = sizeof(HTTPSPolicyCallbackData);
    polHttps.dwAuthType         = AUTHTYPE_SERVER;
    polHttps.fdwChecks          = 0;
    polHttps.pwszServerName     = pwszServerName;
    memset(&PolicyPara, 0, sizeof(PolicyPara));
    PolicyPara.cbSize            = sizeof(PolicyPara);
    PolicyPara.pvExtraPolicyPara = &polHttps;
Необходимо, чтобы для каждого сертификата в цепочке pCertContext->pCertInfo->SubjectPublickeyInfo->Algoritm->pszObjId заканчивалась на szOID_GR3410.

Вызывается функция QueryContextAttributes с аргументом ulAttribute, равным SECPKG_ATTR_CONNECTION_INFO, для получения параметров соединения и их проверки на выполнение условий:

ConnectionInfo.dwProtocol == SP_PROT_TLS1_CLIENT
ConnectionInfo.aiCipher == CALG_G28147
ConnectionInfo.aiHash == CALG_GR3411
ConnectionInfo.aiExch == CALG_DH_EX_EPHEM || ConnectionInfo.aiExch == CALG_DH_EX_SF || ConnectionInfo.aiExch == CALG_DH_EL_EPHEM || ConnectionInfo.aiExch == CALG_DH_EL_SF
Цикл шифрования/рас Для получения параметров соединения шифрования данных реализуется с помощью функций EncryptMessage/DecryptMessage.

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

Завершение сессии

Корректное завершение сессии осуществляется вызовом функции ApplyControlToken.

Требование безопасности

Применение модуля КриптоПро TLS допускается только при использовании открытых ключей сервера и клиента, сертифицированных доверенным центром сертификации.


Функции КриптоПро TLS

Этот набор функций соответствует интерфейсу SSPI.

Группы | Описание
Функции работы с пакетами безопасности | Функции работы с пакетами безопасности используются при выборе и инициализации пакета.
Функции работы с удостоверениями | Функции работы с удостоверениями обеспечивают операции с удостоверениями субъектов безопасности.
Функции установления соединения | Функции установления соединения предназначены для инициализации нового соединения или обновления параметров старого.
Функции передачи данных | Функции передачи данных предназначены для выполнения операций шифрования и расшифрования потока данных, а также контроля его целостности.
Служебные функции SSPI | Служебные функции, например, обеспечивающие распределение памяти.
Заглушки - неподдерживаемые функции SSPI | При обращении к этим функциям всегда возвращается код ошибки.
Последние изменения: 25 окт 2002


Функции работы с пакетами безопасности

Функции работы с пакетами безопасности используются при выборе и инициализации пакета.
Функции | Описание
SECURITY_STATUS EnumerateSecurityPackages ( PULONG pcPackages, PSecPkgInfo *ppPackageInfo ) | Функция EnumerateSecurityPackages().
PSecurityFunctionTable InitSecurityInterface ( void) | Функция InitSecurityInterface().
SECURITY_STATUS QuerySecurityPackageInfo ( SEC_CHAR *pszPackageName, PSecPkgInfo *ppPackageInfo ) | Функция QuerySecurityPackageInfo().


EnumerateSecurityPackages

Функция EnumerateSecurityPackages().

Возвращает таблицу структур SecPkgInfo, состоящую из одного элемента, описывающего данный SSP.

SECURITY_STATUS EnumerateSecurityPackages (
  PULONG pcPackages,
  PSecPkgInfo * ppPackageInfo
);

Параметры:

pcPackages
[out] Указатель на ULONG, получает количество SSP (1 в случае данной библиотеки).
ppPackageInfo
[out] Указатель на переменную, которая получает адрес таблицы структур SecPkgInfo. Каждая структура описывает один SSP.

Возвращает:

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

Примечание:

Структура SecPkgInfo содержит информацию о SSP.

Для освобождения буфера, возвращенного в ppPackageInfo, надо вызвать функцию FreeContextBuffer().

Требования:

Windows NT/2000/XP: Необходимо Windows NT 4.0 SP5 или старше с Internet Explorer 5.0 или старше.
Windows 98/ME: Необходимо Windows 95 OSR2 или старше с Internet Explorer 5.0 или старше.
Файл описания: Прототип описан в файле Sspi.h.

См. также:

FreeContextBuffer() , SecPkgInfo()


InitSecurityInterface

Функция InitSecurityInterface().

Возвращает указатель на таблицу функций данного SSP. Это позволяет приложениям использовать SSPI без линковки с его конкретной реализацией.

PSecurityFunctionTable InitSecurityInterface (
  void
);

Возвращает:

При успешном завершении функция возвращает указатель на структуру SecurityFunctionTable.

В противном случае функция возвращает NULL.

Требования:

Windows NT/2000/XP: Необходимо Windows NT 4.0 SP5 или старше с Internet Explorer 5.0 или старше.
Windows 98/ME: Необходимо Windows 95 OSR2 или старше с Internet Explorer 5.0 или старше.
Файл описания: Прототип описан в файле Sspi.h.

См. также:

SecurityFunctionTable()


QuerySecurityPackageInfo

Функция QuerySecurityPackageInfo().

Возвращает информацию о данном SSP.

SECURITY_STATUS QuerySecurityPackageInfo (
  SEC_CHAR * pszPackageName,
  PSecPkgInfo * ppPackageInfo
);

Параметры:

pszPackageName
[in] Имя SSP, о котором запрашивается информация.
ppPackageInfo
[out] Указатель на переменную, которая получает адрес структуры SecPkgInfo.

Возвращает:

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

Примечание:

Для освобождения буфера, возвращенного в ppPackageInfo, надо вызвать функцию FreeContextBuffer().

Требования:

Windows NT/2000/XP: Необходимо Windows NT 4.0 SP5 или старше с Internet Explorer 5.0 или старше.
Windows 98/ME: Необходимо Windows 95 OSR2 или старше с Internet Explorer 5.0 или старше.
Файл описания: Прототип описан в файле Sspi.h.

См. также:

FreeContextBuffer() , SecPkgInfo()


Функции работы с удостоверениями

Функции работы с удостоверениями обеспечивают операции с удостоверениями субъектов безопасности.
Функции | Описание
SECURITY_STATUS AcquireCredentialsHandle ( SEC_CHAR *pszPrincipal, SEC_CHAR *pszPackage, ULONG fCredentialUse, PLUID pvLogonID, PVOID pAuthData, PVOID pGetKeyFn, PVOID pvGetKeyArgument, PCredHandle phCredential, PTimeStamp ptsExpiry ) | Функция AcquireCredentialsHandle().
SECURITY_STATUS FreeCredentialsHandle ( PCredHandle phCredential ) | Функция FreeCredentialsHandle().
SECURITY_STATUS QueryCredentialsAttributes ( PCredHandle phCredential, unsigned long ulAttribute, void SEC_FAR *pBuffer ) | Функция QueryCredentialsAttributes().


AcquireCredentialsHandle

Функция AcquireCredentialsHandle().

Cоздает дескриптор удостоверения субъекта безопасности, требуемый для функций InitializeSecurityContext() и AcceptSecurityContext().

SECURITY_STATUS AcquireCredentialsHandle (
  SEC_CHAR * pszPrincipal,
  SEC_CHAR * pszPackage,
  ULONG fCredentialUse,
  PLUID pvLogonID,
  PVOID pAuthData,
  PVOID pGetKeyFn,
  PVOID pvGetKeyArgument,
  PCredHandle phCredential,
  PTimeStamp ptsExpiry
);

Параметры:

pszPrincipal
[in] Параметр зарезервирован для будущего использования и должен быть NULL.
pszPackage
[in] Для SSL/TLS укажите UNISP_NAME (макрос, имеющий значение "Microsoft Unified Security Protocol Provider")
phContext
[in] Дескриптор контекста соединения, установленного с получателем сообщения.
fCredentialUse
[in/out] Флаг возможного использования удостоверения:
Флаг | Смысл
SECPKG_CRED_INBOUND | Удостоверение сервера
SECPKG_CRED_OUTBOUND | Удостоверение клиента
pvLogonID
[in] Параметр зарезервирован для будущего использования и должен быть NULL.
pAuthData
[in] Структура SCHANNEL_CRED, содержащая все настройки, в том числе (опционально) сертификат субъекта.
pGetKeyFn
[in] Параметр зарезервирован для будущего использования и должен быть NULL.
pvGetKeyArgument
[in] Параметр зарезервирован для будущего использования и должен быть NULL.
phCredential
[out] Указатель на CredHandle. Сюда будет записан дескриптор удостоверения.
ptsExpiry
[out] Опционален. Указатель на TimeStamp. Параметр зарезервирован для будущего использования и должен быть NULL.

Возвращает:

Если функция завершается успешно, то возвращается SEC_E_OK. Иначе функция возвращает одно из следующих значений:
Возвращаемые значения | Описание
SEC_E_UNKNOWN_CREDENTIALS | Параметр pAuthData содержал неподдерживаемое удостоверение.
SEC_E_NO_CREDENTIALS | Параметр fCredentialUse имеет неправильное значение.

Примечание:

Когда удостоверение больше не используется, освободите его вызовом FreeCredentialsHandle().

Требования:

Windows NT/2000/XP: Необходимо Windows NT 4.0 SP5 или старше с Internet Explorer 5.0 или старше.
Windows 98/ME: Необходимо Windows 95 OSR2 или старше с Internet Explorer 5.0 или старше.
Файл описания: Прототип описан в файле Sspi.h.

См. также:

FreeCredentialsHandle() , AcceptSecurityContext() , InitializeSecurityContext()


FreeCredentialsHandle

Функция FreeCredentialsHandle().

Уведомляет систему о том, что удостоверение больше не используется. Когда все ссылки на него будут удалены, будет удалено и само удостоверение.

SECURITY_STATUS FreeCredentialsHandle (
  PCredHandle phCredential
);

Параметры:

phCredential
[in] Освобождаемый дескриптор.

Возвращает:

Если функция завершается успешно, то возвращается SEC_E_OK. Иначе функция возвращает одно из следующих значений:
Возвращаемые значения | Описание
SEC_E_INVALID_HANDLE | Параметр phCredential не является дескриптором удостоверения.

Примечание:

Эта функция позволяет системе освободить все ресурсы, связанные с удостоверением.

Требования:

Windows NT/2000/XP: Необходимо Windows NT 4.0 SP5 или старше с Internet Explorer 5.0 или старше.
Windows 98/ME: Необходимо Windows 95 OSR2 или старше с Internet Explorer 5.0 или старше.
Файл описания: Прототип описан в файле Sspi.h.

См. также:

AcquireCredentialsHandle()


QueryCredentialsAttributes

Функция QueryCredentialsAttributes().

Возвращает информацию о свойствах данного удостоверения. Эта информация является общей для всех соединений, созданных с этим удостоверением.

SECURITY_STATUS QueryCredentialsAttributes (
  PCredHandle phCredential,
  unsigned long ulAttribute,
  void SEC_FAR * pBuffer
);

Параметры:

phCredential
[in] Дескриптор интересующего удостоверения.
ulAttribute
[in] Указывает, какой атрибут запрашивается. Допустимые аттибуты перечислены в следующей таблице:
Значение | Возвращаемая информация | Тип структуры pBuffer
SECPKG_ATTR_SUPPORTED_ALGS | Поддерживаемые криптографические алгоритмы | SecPkgCred_SupportedAlgs
SECPKG_ATTR_CIPHER_STRENGTHS | Длина ключа в битах | SecPkgCred_CipherStrengths
SECPKG_ATTR_SUPPORTED_PROTOCOLS | Поддерживаемые протоколы | SecPkgCred_SupportedProtocols

pBuffer
[in/out] Указатель на структуру, куда будет помещен атрибут. Тип структуры зависит от параметра ulAttribute.

Возвращает:

При успешном завершении функция возвращает SEC_E_OK.

В случае ошибки функция возвращает одно из следующих значений:
Возвращаемые значения | Описание
SEC_E_INVALID_HANDLE | Параметр phContext содержит недействительный дескриптор контекста.
SEC_E_UNSUPPORTED_FUNCTION | Параметр ulAttribute содержит неподдерживаемый атрибут.

Примечание:

Изначально атрибуты соединения задаются в структуре SCHANNEL_CRED при вызове AcquireCredentialsHandle().

Память для структуры, указанной в pBuffer, отводит приложение, а память для динамических элементов этой структуры отводит SSP, и ее необходимо освободить с помощью FreeContextBuffer().

Требования:

Windows NT/2000/XP: Необходимо Windows NT 4.0 SP5 или старше с Internet Explorer 5.0 или старше.
Windows 98/ME: Необходимо Windows 95 OSR2 или старше с Internet Explorer 5.0 или старше.
Файл описания: Прототип описан в файле Sspi.h.

См. также:

AcquireCredentialsHandle() , FreeContextBuffer() , SCHANNEL_CRED() , SecPkgCred_CipherStrengths()


Функции установления соединения

Функции установления соединения предназначены для инициализации нового соединения или обновления параметров старого.
Функции | Описание
SECURITY_STATUS AcceptSecurityContext ( PCredHandle phCredential, PCtxtHandle phContext, PSecBufferDesc pInput, ULONG fContextReq, ULONG TargetDataRep, PCtxtHandle phNewContext, PSecBufferDesc pOutput, PULONG pfContextAttr, PTimeStamp ptsExpiry ) | Функция AcceptSecurityContext().
SECURITY_STATUS ApplyControlToken ( PCtxtHandle phContext, PSecBufferDesc pInput ) | Функция ApplyControlToken().
SECURITY_STATUS DeleteSecurityContext ( PCtxtHandle phContext ) | Функция DeleteSecurityContext().
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 ) | Функция InitializeSecurityContext().
SECURITY_STATUS QueryContextAttributes ( PCtxtHandle phContext, ULONG ulAttribute, PVOID pBuffer ) | Функция QueryContextAttributes().
SECURITY_STATUS QuerySecurityContextToken ( PCtxtHandle phContext, HANDLE *phToken ) | Функция QuerySecurityContextToken().


AcceptSecurityContext

Функция AcceptSecurityContext().

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

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

SECURITY_STATUS AcceptSecurityContext (
  PCredHandle phCredential,
  PCtxtHandle phContext,
  PSecBufferDesc pInput,
  ULONG fContextReq,
  ULONG TargetDataRep,
  PCtxtHandle phNewContext,
  PSecBufferDesc pOutput,
  PULONG pfContextAttr,
  PTimeStamp ptsExpiry
);

Параметры:

phCredential
[in] Указатель на дескриптор удостоверения сервера. Указанный дескриптор получается через запрос к функции AcquireCredentialsHandle().
phContext
[in] Указатель на CtxtHandle. При первом вызове, укажите NULL. При последующих - указатель на дескриптор, возвращенный в phNewContext после первого вызова к этой функции.
pInput
[in] указатель на структуру SecBufferDesc, содержащую две структуры SecBuffer. Первый буфер должен иметь тип SECBUFFER_TOKEN, и содержать пакет, полученый от клиента. Второй буфер должен иметь тип SECBUFFER_EMPTY
fContextReq
[in] Показывает, какой набор свойств должен поддерживать контекст. Допустимые флаги перечислены в следующей таблице:
Флаг | Описание
ASC_REQ_REPLAY_DETECT | Защита от навязывания повторных пакетов
ASC_REQ_SEQUENCE_DETECT | Защита от навязывания перестановок пакетов
ASC_REQ_CONFIDENTIALITY | Конциденциальность (шифрование)
ASC_REQ_STREAM | Соединение потокового типа
ASC_REQ_ALLOCATE_MEMORY | SSP отводит память для буферов. Ее необходимо освободить вызовом FreeContextBuffer()
ASC_REQ_EXTENDED_ERROR | Уведомлять другую сторону об ошибках (SSL alerts)
ASC_REQ_CONNECTION | Неформатированные сообщения
ASC_REQ_MUTUAL_AUTH | Взаимная аутентификация
ASC_REQ_USE_SUPPLIED_CREDS | SSP не будет пытаться искать удостоверение, если оно не предоставлено приложением
ASC_REQ_MANUAL_CRED_VALIDATION | SSP не будет проверять удостоверение другой стороны
Может оказаться так, что клиент поддерживает не все из запрошенных параметров. Дальнейшие детали смотрите в описании параметра pfContextAttr
TargetDataRep
[in] Параметр зарезервирован для будущего использования и должен быть 0.
phNewContext
[in/out] Указатель на CtxtHandle. При первом вызове сюда будет помещен дескриптор нового контекста. При последующих вызовах полученный дескриптор следует передавать через параметр phContext, а в phNewContext передавать NULL
pOutput
[in] Указатель на структуру SecBufferDesc, содержащую SecBuffer с типом SECBUFFER_TOKEN. На выходе в этот буфер будет помещен пакет, который нужно переслать клиенту. Функция может дополнительно вернуть буфер с типом SECBUFFER_EXTRA.
pfContextAttr
[out] Указатель на ULONG, куда будут записаны флаги, описывающие свойства устанавливаемого контекста. Список возможных значений приведен в описании параметра fContextReq. pfContextAttr получает тот же набор флагов, с заменой префикса ASC_REQ на ASC_RET.
Warning Атрибуты безопасности не следует проверять до последнего вызова функции, возвращающего SEC_E_OK. Остальные атрибуты, такие как ASC_RET_ALLOCATED_MEMORY можно использовать после первого же вызова.
ptsExpiry
[out] Опционален. Указатель на структуру TimeStamp. Gри наличии сертификата клиента, этот параметр получает время истечения этого сертификата. Иначе возвращается максимальное возможное значение времени.

Возвращает:

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

Возвращает:

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

Примечание:

На стороне клиента для создания контекста используется парная функция InitializeSecurityContext().
При получении кода ошибки SEC_E_INSUFFICIENT_MEMORY, укажите атрибут ASC_REQ_ALLOCATE_MEMORY в fContextReq.
Вызывающее приложение должно определить допустимость атрибутов установленного контекста. Например, если конфиденциальность соединения была запрошена, но не была достигнута, некоторые приложения должны принять решение немедленно прекратить соединение. Если контекст не смог быть установлен, сервер должен удалить частично созданный контекст вызовом DeleteSecurityContext().
После установления контекста, серверное приложение может с помощью функции QuerySecurityContextToken получить дескриптор пользователя, которому сопоставлен сертификат клиента, и использовать его для имперсонализации пользователя.

Требования:

Windows NT/2000/XP: Необходимо Windows NT 4.0 SP5 или старше с Internet Explorer 5.0 или старше.
Windows 98/ME: Необходимо Windows 95 OSR2 или старше с Internet Explorer 5.0 или старше.
Файл описания: Прототип описан в файле Sspi.h.

См. также:

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


ApplyControlToken

Функция ApplyControlToken().

Используется для управления соединением. В настоящее время реализована только команда shutdown.

SECURITY_STATUS ApplyControlToken (
  PCtxtHandle phContext,
  PSecBufferDesc pInput
);

Параметры:

phContext
[in] Дескриптор контекста.
pInput
[in] Структура SecBufferDesc, состоящая из единственной структуры SecBuffer. Буфер должен иметь тип SECBUFFER_TOKEN, длину sizeof(DWORD), и значение - DWORD, содержащий управляющую команду. Допустимые аттибуты перечислены в следующей таблице:
Значение | Операция
SCHANNEL_SHUTDOWN | Нормальное завершение соединения с уведомлением другой стороны.

Возвращает:

При успешном завершении функция возвращает SEC_E_OK.
В противном случае функция возвращает ненулевой код ошибки.

Примечание:

За описанием того, как SSP уведомляет приложение на другой стороне о закрытии соединения командой SCHANNEL_SHUTDOWN см. заметки к DecryptMessage().

Требования:

Windows NT/2000/XP: Необходимо Windows NT 4.0 SP5 или старше с Internet Explorer 5.0 или старше.
Windows 98/ME: Необходимо Windows 95 OSR2 или старше с Internet Explorer 5.0 или старше.
Файл описания: Прототип описан в файле Sspi.h.

См. также:

DecryptMessage() , SecBuffer() , SecBufferDesc()


DeleteSecurityContext

Функция DeleteSecurityContext().

Освобождает структуры данных, связанные с данным соединением.

SECURITY_STATUS DeleteSecurityContext (
  PCtxtHandle phContext
);

Параметры:

phContext
[in] Дескриптор удаляемого контекста соединения.

Возвращает:

Если функция завершается успешно, то возвращается SEC_E_OK. Иначе функция возвращает одно из следующих значений:
Возвращаемые значения | Описание
SEC_E_INVALID_HANDLE | Параметр phContext содержит недействительный дескриптор контекста.

Примечание:

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

Требования:

Windows NT/2000/XP: Необходимо Windows NT 4.0 SP5 или старше с Internet Explorer 5.0 или старше.
Windows 98/ME: Необходимо Windows 95 OSR2 или старше с Internet Explorer 5.0 или старше.
Файл описания: Прототип описан в файле Sspi.h.


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. При первом вызове, укажите 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
TargetDataRep
[in] Параметр зарезервирован для будущего использования и должен быть 0.
pInput
[in] указатель на структуру SecBufferDesc. При первом вызове должен быть NULL. При последующих вызовах должен состоять из двух структур SecBuffer. Первый буфер должен иметь тип SECBUFFER_TOKEN, и содержать пакет, полученый от сервера. Второй буфер должен иметь тип SECBUFFER_EMPTY. В него в случае необходимости будут помещены оставшиеся необработанные входные данные.
phNewContext
[in/out] Указатель на CtxtHandle. При первом вызове сюда будет помещен дескриптор нового контекста. При последующих вызовах полученный дескриптор следует передавать через параметр phContext, а в phNewContext передавать NULL
pOutput
[in] Указатель на структуру SecBufferDesc, содержащую SecBuffer с типом 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. Gри наличии сертификата клиента, этот параметр получает время истечения этого сертификата. Иначе возвращается максимальное возможное значение времени.

Возвращает:

При успешном завершении функция возвращает одно из следующих значений:
Возвращаемые значения | Описание
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().

Требования:

Windows NT/2000/XP: Необходимо Windows NT 4.0 SP5 или старше с Internet Explorer 5.0 или старше.
Windows 98/ME: Необходимо Windows 95 OSR2 или старше с Internet Explorer 5.0 или старше.
Файл описания: Прототип описан в файле Sspi.h.

См. также:

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


QueryContextAttributes

Функция QueryContextAttributes().

Возвращает информацию о свойствах данного контекста.

SECURITY_STATUS QueryContextAttributes (
  PCtxtHandle phContext,
  ULONG ulAttribute,
  PVOID pBuffer
);

Параметры:

phContext
[in] Дескриптор интересующего контекста.
ulAttribute
[in] Указывает, какой атрибут запрашивается. Допустимые аттибуты перечислены в следующей таблице:
Значение | Возвращаемая информация | Тип структуры pBuffer
SECPKG_ATTR_CONNECTION_INFO | Протокол и используемые крипт. алгоритмы. | SecPkgContext_ConnectionInfo
SECPKG_ATTR_ISSUER_LIST_EX | Список доверенных центров сертификации. | SecPkgContext_IssuerListInfoEx
SECPKG_ATTR_LIFESPAN | Время истечения соединения. | SecPkgContext_Lifespan
SECPKG_ATTR_NAMES | Subject из сертификата удаленной стороны. | SecPkgContext_Names
SECPKG_ATTR_REMOTE_CERT_CONTEXT | Сертификат удаленной стороны. | CERT_CONTEXT. См. заметки.
SECPKG_ATTR_STREAM_SIZES | Размеры буферов для заголовка, блока данных и трейлера при шифровании. | SecPkgContext_StreamSizes

pBuffer
[in/out] Указатель на структуру, куда будет помещен атрибут. Тип структуры зависит от параметра ulAttribute. См. Заметки.

Возвращает:

При успешном завершении функция возвращает SEC_E_OK.

В противном случае функция возвращает ненулевой код ошибки.

Примечание:

Память для структуры, указанной в pBuffer, отводит приложение, а память для динамических элементов этой структуры отводит SSP, и ее необходимо освободить с помощью FreeContextBuffer().

Аттрибут SECPKG_ATTR_REMOTE_CERT_CONTEXT возвращает структуру CERT_CONTEXT. Ее необходимо освободить с помощью CertFreeCertificateContext.

Требования:

Windows NT/2000/XP: Необходимо Windows NT 4.0 SP5 или старше с Internet Explorer 5.0 или старше.
Windows 98/ME: Необходимо Windows 95 OSR2 или старше с Internet Explorer 5.0 или старше.
Файл описания: Прототип описан в файле Sspi.h.


QuerySecurityContextToken

Функция QuerySecurityContextToken().

Возвращает Windows NT/Windows 2000/Windows XP access token, соответсвующий удаленному пользователю.

SECURITY_STATUS QuerySecurityContextToken (
  PCtxtHandle phContext,
  HANDLE * phToken
);

Параметры:

phContext
[in] Дескриптор интересующего контекста.
phToken
[out] Указатель, куда помещается token.

Возвращает:

При успешном завершении функция возвращает SEC_E_OK.

Иначе функция возвращает одно из следующих значений:
Возвращаемые значения | Описание
SEC_E_INVALID_HANDLE | Параметр phContext содержит недействительный дескриптор контекста.

Примечание:

Эта функция вызывается приложением для имперсонализации пользователя. По окончании использования возвращенный дескриптор должен быть освобожден вызовом CloseHandle.

Требования:

Windows NT/2000/XP: Необходимо Windows NT 4.0 SP5 или старше с Internet Explorer 5.0 или старше.
Windows 98/ME: Необходимо Windows 95 OSR2 или старше с Internet Explorer 5.0 или старше.
Файл описания: Прототип описан в файле Sspi.h.


Функции передачи данных

Функции передачи данных предназначены для выполнения операций шифрования и расшифрования потока данных, а также контроля его целостности.
Функции | Описание
SECURITY_STATUS DecryptMessage ( PCtxtHandle phContext, PSecBufferDesc pMessage, ULONG MessageSeqNo, PULONG pfQOP ) | Функция DecryptMessage().
SECURITY_STATUS EncryptMessage ( PCtxtHandle phContext, ULONG fQOP, PSecBufferDesc pMessage, ULONG MessageSeqNo ) | Функция EncryptMessage().


DecryptMessage

Функция DecryptMessage().

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

SECURITY_STATUS DecryptMessage (
  PCtxtHandle phContext,
  PSecBufferDesc pMessage,
  ULONG MessageSeqNo,
  PULONG pfQOP
);

Примечание:

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

Параметры:

phContext
[in] Дескриптор контекста соединения, установленного с отправителем сообщения.
pMessage
[in/out] Указатель на структуру SecBufferDesc, содержащую 4 буфера SecBuffer. Ровно один из них должен иметь тип SECBUFFER_DATA, и содержать зашифрованные данные, которые будут расшифрованы на месте. Остальные буферы должны иметь тип SECBUFFER_EMPTY.
MessageSeqNo
[in] Параметр зарезервирован для будущего использования и должен быть 0.
pfQOP
[in] Параметр зарезервирован для будущего использования и должен быть NULL.

Возвращает:

Если функция завершается успешно, и другая сторона не запросила изменения состояния соединения (renegotiation или shutdown), то возвращается SEC_E_OK. Иначе функция возвращает одно из следующих значений:
Возвращаемые значения | Описание
SEC_E_INVALID_HANDLE | Параметр phContext содержит недействительный дескриптор контекста.
SEC_E_INVALID_TOKEN | Параметр pInput содержит неправильные входные данные.
SEC_E_INCOMPLETE_MESSAGE | Данные во входном буфере неполны. Приложение должно прочитать остальные данные, и повторить вызов.
SEC_I_RENEGOTIATE | Другая сторона запросила renegotiate. См. заметки.
SEC_I_CONTEXT_EXPIRED | Другая сторона закрыла соединение. См. заметки.

Примечание:

Функция возвращает SEC_I_CONTEXT_EXPIRED, когда отправитель завершил соединение. После получения этого сообщения нужно:

  1. Вызвать EncryptMessage() с пустым входным буфером.
  2. Отправить полученный вывод.
  3. Удалить контекст вызовом DeleteSecurityContext()

Код возврата SEC_I_RENEGOTIATE означает, что отправитель хочет переустановить соединение. В этом случае необходимо вызвать AcceptSecurityContext (для сервера) или InitializeSecurityContext (для клиента), передав пустой входной буфер. После этого первого вызова, повторяется та же цепочка действий, что и при первоначальном создании контекста.

Требования:

Windows NT/2000/XP: Необходимо Windows NT 4.0 SP5 или старше с Internet Explorer 5.0 или старше.
Windows 98/ME: Необходимо Windows 95 OSR2 или старше с Internet Explorer 5.0 или старше.
Файл описания: Прототип описан в файле Sspi.h.

См. также:

AcceptSecurityContext() , InitializeSecurityContext() , DeleteSecurityContext() , EncryptMessage() , SecBuffer() , SecBufferDesc()


EncryptMessage

Функция EncryptMessage().

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

SECURITY_STATUS EncryptMessage (
  PCtxtHandle phContext,
  ULONG fQOP,
  PSecBufferDesc pMessage,
  ULONG MessageSeqNo
);

Примечание:

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

Параметры:

phContext
[in] Дескриптор контекста соединения, установленного с получателем сообщения.
fQOP
[in] Параметр зарезервирован для будущего использования и должен быть 0.
pMessage
[in/out] Указатель на структуру SecBufferDesc, содержащую 4 буфера SecBuffer.
Тип | Заполнение
SECBUFFER_STREAM_HEADER | Можно не инициализировать
SECBUFFER_DATA | Должен содержать данные, которые будут зашифрованы, и их длину
SECBUFFER_STREAM_TRAILER | Можно не инициализировать
SECBUFFER_EMPTY | Пустой
Размеры буферов могут быть получены вызовом QueryContextAttributes с параметром SECPKG_ATTR_STREAM_SIZES. Она возвращает структуру SecPkgContext_StreamSizes, поля которой cbHeader, cbMaximumMessage и cbTrailer содержат размеры соответственно первого, второго и третьего буферов.

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

Возвращает:

Если функция завершается успешно, то возвращается SEC_E_OK. Иначе функция возвращает одно из следующих значений:
Возвращаемые значения | Описание
SEC_E_INVALID_HANDLE | Параметр phContext содержит недействительный дескриптор контекста.
SEC_E_INVALID_TOKEN | Параметр pInput содержит неправильные входные данные.
SEC_E_CONTEXT_EXPIRED | Другая сторона закрыла соединение. См. заметки.

Примечание:

Приложение должно отправить получателю все три полученные буфера - header, data и trailer.

Функция возвращает SEC_E_CONTEXT_EXPIRED, если получатель завершил соединение. После получения этого сообщения нужно:

  1. Отправить полученный вывод.
  2. Удалить контекст вызовом DeleteSecurityContext()

Требования:

Windows NT/2000/XP: Необходимо Windows NT 4.0 SP5 или старше с Internet Explorer 5.0 или старше.
Windows 98/ME: Необходимо Windows 95 OSR2 или старше с Internet Explorer 5.0 или старше.
Файл описания: Прототип описан в файле Sspi.h.

См. также:

QueryContextAttributes() , SecPkgContext_StreamSizes() , SecBuffer() , SecBufferDesc()


Служебные функции SSPI

Служебные функции, например, обеспечивающие распределение памяти.
Функции | Описание
SECURITY_STATUS FreeContextBuffer ( PVOID pvContextBuffer ) | Функция FreeContextBuffer().


FreeContextBuffer

Функция FreeContextBuffer().

Освобождает память, отведенную SSP, например, буфер, отведенный функцией InitializeSecurityContext() для выходных данных.

SECURITY_STATUS FreeContextBuffer (
  PVOID pvContextBuffer
);

Возвращает:

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

Примечание:

Функция может освободить любую память, отведенную SSP.

Требования:

Windows NT/2000/XP: Необходимо Windows NT 4.0 SP5 или старше с Internet Explorer 5.0 или старше.
Windows 98/ME: Необходимо Windows 95 OSR2 или старше с Internet Explorer 5.0 или старше.
Файл описания: Прототип описан в файле Sspi.h.

См. также:

InitializeSecurityContext()


Заглушки - неподдерживаемые функции SSPI

При обращении к этим функциям всегда возвращается код ошибки.
Функции | Описание
SECURITY_STATUS CompleteAuthToken ( PCtxtHandle phContext, PSecBufferDesc pToken ) | Функция CPCompleteAuthToken().
SECURITY_STATUS ExportSecurityContext ( PCtxtHandle phContext, ULONG fFlags, PSecBuffer pPackedContext, void SEC_FAR *pToken ) | Функция CPExportSecurityContext().
SECURITY_STATUS ImpersonateSecurityContext ( PCtxtHandle phContext ) | Функция CPImpersonateSecurityContext().
SECURITY_STATUS ImportSecurityContext ( SEC_CHAR SEC_FAR *pszPackage, PSecBuffer pPackedContext, void SEC_FAR *pToken, PCtxtHandle phContext ) | Функция CPImportSecurityContextA().
SECURITY_STATUS MakeSignature ( PCtxtHandle phContext, ULONG fQOP, PSecBufferDesc pMessage, ULONG MessageSeqNo ) | Функция CPMakeSignature().
SECURITY_STATUS RevertSecurityContext ( PCtxtHandle phContext ) | Функция CPRevertSecurityContext().
SECURITY_STATUS VerifySignature ( PCtxtHandle phContext, PSecBufferDesc pMessage, ULONG MessageSeqNo, PULONG pfQOP ) | Функция VerifySignature().


CompleteAuthToken

Функция CPCompleteAuthToken().

Завершает аутентификацию пакета. Используется, в частности, протоколом DCE.

SECURITY_STATUS CompleteAuthToken (
  PCtxtHandle phContext,
  PSecBufferDesc pToken
);

Возвращает:

Всегда возвращает SEC_E_INTERNAL_ERROR.


ExportSecurityContext

Функция CPExportSecurityContext().

Cохраняет контекст в буфере.

SECURITY_STATUS ExportSecurityContext (
  PCtxtHandle phContext,
  ULONG fFlags,
  PSecBuffer pPackedContext,
  void SEC_FAR * pToken
);

Возвращает:

Всегда возвращает SEC_E_INTERNAL_ERROR.


ImpersonateSecurityContext

Функция CPImpersonateSecurityContext().

Позволяет серверу выступать от лица клиента при всех проверках прав доступа.

SECURITY_STATUS ImpersonateSecurityContext (
  PCtxtHandle phContext
);

Возвращает:

Всегда возвращает SEC_E_INTERNAL_ERROR.


ImportSecurityContext

Функция CPImportSecurityContextA().

Считывает контекст из буфера.

SECURITY_STATUS ImportSecurityContext (
  SEC_CHAR SEC_FAR * pszPackage,
  PSecBuffer pPackedContext,
  void SEC_FAR * pToken,
  PCtxtHandle phContext
);

Возвращает:

Всегда возвращает SEC_E_INTERNAL_ERROR.


MakeSignature

Функция CPMakeSignature().

Функция подписи сообщения. Эта функция интерфейса SSPI не поддерживается данным SSP, так как используются функция EncryptMessage, осуществляющая шифрование и подпись сообщения.

SECURITY_STATUS MakeSignature (
  PCtxtHandle phContext,
  ULONG fQOP,
  PSecBufferDesc pMessage,
  ULONG MessageSeqNo
);

Возвращает:

Всегда возвращает SEC_E_INTERNAL_ERROR.


RevertSecurityContext

Функция CPRevertSecurityContext().

Запрещает серверу выступать от лица клиента при всех проверках прав доступa.

SECURITY_STATUS RevertSecurityContext (
  PCtxtHandle phContext
);

Возвращает:

Всегда возвращает SEC_E_INTERNAL_ERROR.


VerifySignature

Функция VerifySignature().

Осуществляет проверку подписи сообщения. Эта функция интерфейса SSPI не поддерживается данным SSP, так как используется функция DecryptMessage, осуществляющая расшифрование и проверку подписи сообщения.

SECURITY_STATUS VerifySignature (
  PCtxtHandle phContext,
  PSecBufferDesc pMessage,
  ULONG MessageSeqNo,
  PULONG pfQOP
);

Возвращает:

Всегда возвращает SEC_E_INTERNAL_ERROR.


Main Index

КриптоПро TLS

КриптоПро TLS Описание

Последние изменения: 25 окт 2002