Функция CPEncrypt() производит зашифрование данных. Одновременно может быть произведено их хэширование.

BOOL WINAPI CPEncrypt(
  HCRYPTPROV hProv,
  HCRYPTKEY hKey,
  HCRYPTHASH hHash,
  BOOL Final,
  DWORD dwFlags,
  BYTE * pbData,
  DWORD * pdwDataLen,
  DWORD dwBufLen
);

Аргументы

hProv

[in] Дескриптор криптопровайдера. Получается при помощи функции CPAcquireContext().

hKey

[in] Дескриптор ключа сессии, используемого для зашифрования данных.

hHash

[in] Дескриптор объекта функции хэширования. Если значение хэш-функции не вычисляется, этот параметр равен нулю.

Final

[in] Булева величина. Определяет, является ли переданный функции блок последним зашифрованным блоком данных. Она должна быть установлена TRUE, если это последний (или единственный) блок, и FALSE – в противном случае. При установке флага Final == TRUE, состояние усложнения ключа возвращается в первоначальное, а начальное значение синхропосылки устанавливается в случайное значение.

dwFlags

[in] Значения флагов. Параметр определяет способ обработки фрагмента данных в потоке. Нулевое значение соответствует шифрованию фрагмента данных потока, ненулевое значение соответствует обработке пакета данных. См. Шифрование и хэширование пакета .

pbData

[in/out] Если значение dwFlags нулевое, указатель на буфер, содержащий данные для зашифрования. Если установлен флаг CP_CRYPT_HASH_PACKET - указатель на буфер, содержащий пакет. См. Шифрование и хэширование пакета . Если установлены флаги CP_CRYPT_HASH_PACKET и CP_CRYPT_DATA_IOVEC, указатель на массив структур CSP_iovec, задающий пакет. См. Вектор ввода вывода . После шифрования данные помещаются в этот же буфер или передаются через массив структуру CSP_iovec. Если установлены флаги CP_CRYPT_HASH_PACKET и CP_CHP_MULTIPACKET, указатель на массив структур CSP_Multipacket_ENC, задающий массив пакетов для параллельной обработки на платформах, поддерживающих SIMD архитектуру SSE_x, SSSE_x, AVX. См. Мультипакетная обработка .

pdwDataLen

[in/out] Если значение dwFlags нулевое, указатель на буфер, содержащий длину данных. Параметр dwDataLen определяет число байтов открытого текста в буфере pbData. Через этот параметр функция возвращает указатель на число байтов шифртекста, помещённого в буфер pbData. Если установлен флаг CP_CRYPT_HASH_PACKET, указатель на буфер, содержащий длину пакета. Если установлены флаги CP_CRYPT_HASH_PACKET и CP_CHP_STARTMIX, по указателю pdwDataLen передаётся и возвращается длина пакета включая блоб диверсификации ключей. Если установлены флаги CP_CRYPT_HASH_PACKET,CP_CRYPT_DATA_IOVEC и CP_CHP_STARTMIX, по указателю pdwDataLen передаётся и возвращается общая длина элементов вектора включая блоб диверсификации ключей (в этом варианте использования, блоб диверсификации должен передаваться отдельным первым элементом). Если установлены флаги CP_CRYPT_HASH_PACKET и CP_CHP_MULTIPACKET, указатель на количество структур CSP_Multipacket_ENC.

dwBufLen

[in] Если значение dwFlags нулевое, размер буфера pbData в байтах при условии возможности помещения в буфер зашифрованных данных. Если установлен флаг CP_CRYPT_HASH_PACKET, размер буфера pbData в байтах. Если установлены флаги CP_CRYPT_HASH_PACKET и CP_CRYPT_DATA_IOVEC, число элементов массива CSP_iovec. Если установлены флаги CP_CRYPT_HASH_PACKET, CP_CHP_MULTIPACKET, данный параметр должен иметь нулевое значение.

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

При успешном завершении функция возвращает TRUE, в противном случае возвращается FALSE. Если возвращается FALSE, соответствующий код ошибки (см. таблицу) может быть получен через функцию GetLastError().

Примечания

Шифрование в AEAD-режиме (CRYPT_MODE_MGM) может осуществляться следующим образом. При работе с потоком данных (параметр dwFlags = 0) непосредственно шифрование производится обычным образом. Обработка дополнительных нешифруемых данных осуществляется путём вызова функции CPSetKeyParam() с параметром KP_AUTH_DATA. Тэг аутентификации может быть получен путём вызова функции CPGetKeyParam() с параметром KP_AUTH_TAG.

	    
 CRYPT_DATA_BLOB cdbAdditionalData;
 CPSetKeyParam(hProv, hKey, KP_AUTH_DATA, (BYTE*)&cdbAdditionalData, 0);
 CPEncrypt(hProv, hKey, 0, TRUE, 0, pbData, &dwDataLen, dwBufLen);
 CPGetKeyParam(hProv, hKey, KP_AUTH_TAG, pbAuthTag, &cbAuthTag, 0);
	

При наличии дополнительных нешифруемых данных и отсутствии шифруемых данных тэг аутентификации может быть финализирован и получен путём вызова функции CPGetKeyParam() с параметром KP_AUTH_TAG.

	    
 CRYPT_DATA_BLOB cdbAdditionalData;
 CPSetKeyParam(hCSP, hProv, hKey, KP_AUTH_DATA, (BYTE*)&cdbAdditionalData, 0);
 CPGetKeyParam(hCSP, hProv, hKey, KP_AUTH_TAG, pbAuthTag, &cbAuthTag, 0);
	

Работа в пакетном режиме поддерживается как с линейными пакетами, так и через IOVEC'и. И обработка дополнительных данных, и непосредственно шифрование, и получение тэга аутентификации производятся единым вызовом CPCEncrypt(). Дополнительные данные должны располагаться в начале пакета, затем следует открытый текст, за которым должно находиться место для тэга аутентификации.

	    
 DWORD dwBlockLen; // Длиня тэга аутентификации.
 DWORD dwAddAuthDataLen; // Длина дополнительных данных.
 DWORD dwBaseFlags = BASE_AEAD_FLAGS | CP_CHP_HASH_ENCRYPT; // допускается и CP_CHP_ENCRYPT_HASH;
 DWORD dwFlags = CP_CHP(dwBaseFlags, dwAddAuthDataLen, 0, dwBlockLen / sizeof(DWORD))
 CPEncrypt(hProv, hKey, dwFlags, TRUE, 0, pbData, *pdwDataLen, dwBufLen);
	

Требования:

AIX: 6/7.
FreeBSD: 11/12, pfSense 2.x.
Linux: LSB 4.x (RHEL 5/6/7/8, SuSE 11SP4/12/15, Oracle Linux 5/6/7/8, CentOS 6/7/8, Ubuntu 14.04/16.04/18.04/19.10, Linux Mint 18/19, Fedora 28/29/30/31, Debian 8/9/10 и др.).
Solaris: 10/11.
Mac OS X: 10.9/10.10/10.11/10.12/10.13/10.14/10.15.
iOS: 8/9/10/11/12/13.
Sailfish: 2/3.
Windows: 7/8/8.1/10, Server 2008/2008R2/2012/2012R2/2016/2019.
Файл описания: Прототип описан в файле wincsp.h.
Ядро ОС: Вместо неё используется аналогичная функция CPCEncrypt .

См. также

CPDecrypt() ,CPGenKey() ,CPEncrypt в MS CSP ,CryptEncrypt в MS CryptoAPI 2.0