BOOL WINAPI CPSignHash( HCRYPTPROV hProv, HCRYPTHASH hHash, DWORD dwKeySpec, LPCWSTR sDescription, DWORD dwFlags, BYTE * pbSignature, DWORD * pdwSigLen );
Аргументы
- hProv
- [in] Дескриптор криптопровайдера. Получается при помощи функции CPAcquireContext().
- hHash
- [in] Дескриптор объекта функции хэширования, который будет подписан.
Для хэш с алгоритмами CALG_MD5, CALG_SHA1, CALG_SHA_256, CALG_SHA_384, CALG_SHA_512 функция может отработать успешно, но значение подписи всегда будет неопределённым. - dwKeySpec
- [in] Тип ключевой пары, использующейся при подписи значения функции хэширования. Могут быть использованы следующие значения:
Значение Описание AT_KEYEXCHANGE Ключевая пара обмена AT_SIGNATURE Ключевая пара цифровой подписи - sDescription
- [in] Описание подписываемых данных, добавляемых к объекту hash перед тем, как будет произведена подпись. При проверке подписи функцией CPVerifySignature() необходимо использовать то же описание подписанных данных. Это гарантирует, что подписывающая сторона и проверяющая знают то, что подписывается или проверяется. Если описание не включается в подпись, этот параметр устанавливается в NULL.
Параметр сохранён для совместимости со спецификацией Microsoft Cryptographic Service Provider. С целью предотвращения уязвимости безопасности ЭП использовать этот параметр не рекомендуется. Он должен быть установлен в NULL. - dwFlags
- [in] Значения флагов. Параметр зарезервирован для будущего использования и должен быть нулём.
- pbSignature
- [in] Указатель на буфер, через который возвращается значение подписи. Если через этот параметр передаётся NULL, то подпись не вычисляется. В этом случае требуемый размер буфера (в байтах) возвращается через параметр pdwSigLen.
- pdwSigLen
- [in/out] Указатель на буфер, содержащий длину данных подписи. При вызове функции указанный параметр должен содержать число байтов в буфере pbSignature. После её исполнения параметр будет установлен числом байтов данных, скопированных в буфер pbSignature. Если буфер, соответствующий pbSignature, недостаточно большой, чтобы в него копировать подпись, будет возвращён код ошибки ERROR_MORE_DATA через функцию SetLastError(). В этом случае требуемый размер буфера возвращается в pdwSigLen. Если эта функция завершается с кодом ошибки, отличным от ERROR_MORE_DATA, в этом параметре возвращается ноль. Подпись для ключей ГОСТ Р 34.10-2001 возвращается как описано CPPK (RFC 4491), но в обратном порядке байт. Например, подпись сертификата п. 4.2 будет возвращена:
{ 0xE2, 0xDE, 0x33, 0x1C, 0xB5, 0xD5, 0x31, 0xB1, 0xDA, 0xF4, 0x20, 0x62, 0x17, 0x89, 0x89, 0x68, 0x77, 0x55, 0x93, 0x36, 0xDD, 0xF3, 0x93, 0xB5, 0x71, 0xEC, 0x1B, 0x8D, 0x6E, 0x17, 0xDE, 0xC1, 0xDD, 0x3F, 0x54, 0xBC, 0x4F, 0x45, 0x16, 0x31, 0xED, 0xDE, 0x2E, 0x44, 0x7C, 0x64, 0xAA, 0xC3, 0xD2, 0x6D, 0x53, 0xFB, 0xE9, 0xD5, 0xA7, 0xEC, 0xA9, 0x27, 0xB7, 0x44, 0x09, 0xC9, 0x2F, 0x3C }
Возвращаемые значения
При успешном завершении функция возвращает TRUE, в противном случае возвращается FALSE. Если возвращается FALSE, соответствующий код ошибки (см. таблицу) может быть получен через функцию GetLastError().| Коды возврата | Описание |
|---|---|
| ERROR_INVALID_PARAMETER | Один из параметров содержит некорректное значение. Чаще всего это некорректный указатель. |
| NTE_BAD_ALGID | Дескриптор hHash определяет алгоритм, который данный криптопровайдер не поддерживает. |
| NTE_BAD_FLAGS | dwFlags параметр отличен от нуля, либо параметр dwKeySpec содержит ошибочную величину. |
| NTE_BAD_HASH | Дескриптор хэша ошибочен. |
| NTE_NO_KEY | Закрытый ключ, указанный dwKeySpec, не существует. |
| NTE_NO_MEMORY | Криптопровайдер во время операции исчерпал память. |
| ERROR_MORE_DATA | pbSignature буфер мал для копирования затребованных данных. |
| NTE_FAIL | Нарушение целостности ключей в ОЗУ. см. Дополнительные параметры и определения . |
| SCARD_W_CANCELLED_BY_USER | Пользователь прервал операцию нажатием клавиши Cancel |
| SCARD_W_WRONG_CHV | Пользователь ввёл неправильный пароль или пароль, установленный функцией SetProvParam(), неправильный |
| SCARD_E_INVALID_CHV | Пользователь ввёл пароль с нарушением формата или пароль, установленный функцией SetProvParam(), имеет неправильный формат. Например, пароль имеет недопустимую длину или содержит недопустимые символы. |
| SCARD_W_CHV_BLOCKED | Ввод Pin-кода был заблокирован смарт-картой, т.к. исчерпалось количество попыток, разрешенное картой для ввода. |
| NTE_SILENT_CONTEXT | Операция не может быть выполнена без пользовательского интерфейса. |
| SCARD_W_REMOVED_CARD | Носитель контейнера был удален из считывателя |
Примечания
Перед вызовом функции CPSignHash() необходимо получить дескриптор объекта хэширования при помощи функции CPCreateHash(). После этого используется функция CPHashData() или CPHashSessionKey() чтобы добавить данные или ключи сессии к объекту хэширования.
Функция CPSignHash() выполняет следующие внутренние шаги:
- объект функции хэширования "закрывается”; извлекается значение функции хэширования;
- значение функции хэширования дополняется, как это требуется алгоритмом подписи;
- вычисляется фактическое значение подписи.
После того, как объект функции хэширования подписан, приложение не может добавлять к нему новые данные. Поэтому вызовы функций CPHashData() или CPHashSessionKey() приведут к ошибке. Однако, дополнительные вызовы функций CPDeriveKey(), CPGetHashParam(), CPSignHash() и CPVerifySignature() будут успешными. Эти функции будут работать с подписанным объектом функции хэширования. Приложение должно удалить объект функции хэширования при помощи функции CPDestroyHash().
При использовании ключей алгоритма ГОСТ Р 34.10-2001 для формирования электронной подписи необходимо использовать алгоритм хэширования ГОСТ Р 34.11-94.
При использовании ключей алгоритма ГОСТ Р 34.10-2012 длины 256 бит для формирования электронной подписи необходимо использовать алгоритм хэширования ГОСТ Р 34.11-2012 (256 бит).
При использовании ключей алгоритма ГОСТ Р 34.10-2012 длины 512 бит для формирования электронной подписи необходимо использовать алгоритм хэширования ГОСТ Р 34.11-2012 (512 бит).
Использование алгоритмов CALG_MD5, CALG_SHA_256, CALG_SHA_384, CALG_SHA_512 не входит в функционал СКЗИ "КриптоПро CSP 4.0", относящийся к действию сертификата ФСБ.
Рекомендуется, по возможности, непосредственно после формирования подписи осуществить ее проверку.
Требования:
AIX: 5/6/7 или выше.
FreeBSD: 7/8/9 или выше.
Linux: LSB 3.1 (RHEL 4, SuSE 10) или выше.
Solaris: 10 или выше.
Mac OSX: 10.7/8 или выше.
iOS: 6/7 или выше.
Windows 2000 или выше: Необходимо Windows 2000 SP4 или старше с Internet Explorer 6.0 или старше.
Файл описания: Прототип описан в файле wincsp.h.
Ядро ОС: Вместо неё используется аналогичная функция CPCSignHash .
См. также
CPCreateHash() ,CPDestroyHash() ,CPHashData() ,CPHashSessionKey() ,CPVerifySignature() ,CPSignHash в MS CSP 
,CryptSignHash в MS CryptoAPI 2.0