КриптоПро CSP  

CPSignHash

Функция CPSignHash() возвращает значение электронной цифровой подписи от значения функции хэширования.

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_FLAGSdwFlags параметр отличен от нуля, либо параметр dwKeySpec содержит ошибочную величину.
NTE_BAD_HASHДескриптор хэша ошибочен.
NTE_NO_KEYЗакрытый ключ, указанный dwKeySpec, не существует.
NTE_NO_MEMORYКриптопровайдер во время операции исчерпал память.
ERROR_MORE_DATApbSignature буфер мал для копирования затребованных данных.
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() выполняет следующие внутренние шаги:

При использовании ключей алгоритма ГОСТ Р 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 World Wide Web link ,CryptSignHash в MS CryptoAPI 2.0 World Wide Web link