About This File
Encryption / Decryption / Hashing
Purpose
Cryptography API: Next Generation (CNG) is Microsoft's long-term replacement for their CryptoAPI. CNG is designed to be extensible at many levels and cryptography agnostic in behavior. Although the Crypt.au3 UDF that is installed with AutoIt3 still works perfectly, the advapi32.dll functions that it uses have been deprecated. This UDF was created to offer a replacement for the deprecated functions. According to Microsoft, deprecated functions may be removed in future release. Therefore, this UDF will be available when/if that happens.
Description
This UDF implements some of Microsoft's Cryptography API: Next Generation (CNG) Win32 API functions. In its initial release, it implements functions to encrypt text & files, decrypt text and files, generate hashes, and the Password-Based Key Derivation Function 2 (PBKDF2) function. The UDF can implement any of the encryption/decryption algorithms or hashing algorithms that are installed on the PC in which it is running. Most, if not all, of the values that you would commonly use to specify that desired algorithms, key bit lengths, and other magic number type values, are already defined as constants or enums in the UDF file.
To flatten the learning curve, there is an example file that shows examples of all of the major functionality. This example file is not created to be an exhaustive set of how to implement each feature and parameter. It is designed to give you a template or guide to help you hit the ground running in terms of using the functions. I have tried to fully document the headers of all of the functions as well as the code within the functions themselves. As of v1.4.0, there is also a Help file that includes all of the functions, with examples.
Current UDF Functions
- _CryptoNG_3DES_CBC_DecryptData
- _CryptoNG_3DES_CBC_DecryptFile
- _CryptoNG_3DES_CBC_EncryptData
- _CryptoNG_3DES_CBC_EncryptFile
- _CryptoNG_AES_CBC_DecryptData
- _CryptoNG_AES_CBC_DecryptFile
- _CryptoNG_AES_CBC_EncryptData
- _CryptoNG_AES_CBC_EncryptFile
- _CryptoNG_CreateRSAKeyPair
- _CryptoNG_DecryptData
- _CryptoNG_DecryptFile
- _CryptoNG_EncryptData
- _CryptoNG_EncryptFile
- _CryptoNG_EnumAlgorithms
- _CryptoNG_EnumRegisteredProviders
- _CryptoNG_EnumKeyStorageProviders
- _CryptoNG_GenerateRandom
- _CryptoNG_HashData
- _CryptoNG_HashFile
- _CryptoNG_LastErrorMessage
- _CryptoNG_PBKDF2
- _CryptoNG_Version
Related Links
Cryptography API: Next Generation - Main Page
Cryptography API: Next Generation - Reference
Cryptography API: Next Generation - Primitives
Cryptography API: Next Generation - Cryptographic Algorithm Providers
What's New in Version v1.7.0
Released
-
v1.7.0 (2020-11-27)
- Added additional debug logging to startup & shutdown functions.
- Corrected some function headers.
- Added new function: _CryptoNG_EnumKeyStorageProviders.
-
Added new internal function: __CryptoNG_NCryptFreeBuffer.
-
v1.6.2 (2020-07-12)
- Added additional function parameter validation to prevent the issue, reported by RTFC, where passing empty strings to some functions was causing DllStructCreate failures.
-
Reverted all DllStructGetData & DllStructSetData functions back to object-based dot-notation.
-
v1.6.1 (2020-07-11)
-
Reverted all dll struct gets & sets from dot-notation back to DllStructGetData & DllStructSetData. Using dot-notation caused object initialization errors when value was set to an empty string. (Reported by RTFC)
-
Reverted all dll struct gets & sets from dot-notation back to DllStructGetData & DllStructSetData. Using dot-notation caused object initialization errors when value was set to an empty string. (Reported by RTFC)
-
v1.6.0 (2020-07-10)
- Added the ability to handle data that contains multi-byte character sets. (Reported by RTFC)
- Removed all AU3CHECK warnings.
- Added a new example to show the encryption/decryption of strings with multi-byte characters: aes_cbc_encrypt_decrypt_multibyte_example()
- Added multi-byte characters to the example Word .docx so that the example script that encrypts/decrypts a file shows that it can handle multi-byte characters.
- The example scripts used to write their output to the console. The Scite4AutoIt's editor does not display multi-byte characters in the message area. So the example scripts now sends messages to notepad, which does handle multi-byte characters. (Best to use a monospaced font in Notepad, like Consolas, so that the message formatting displays correctly)
-
Removed a few examples whose functionality was duplicated in other example scripts.
-
v1.5.5 (2020-05-11)
- Significant code refactoring.
- Removed internal __CryptoNG_ConvertByteBuffer function. It was no longer needed after code refactoring.
-
Add some new constants and a new structure in preparation for authenticated cipher functions.
-
v1.5.0 (2020-04-23)
-
Begun adding algorithm-specific encryption/decryption functions starting with:
- _CryptoNG_3DES_CBC_DecryptData
- _CryptoNG_3DES_CBC_DecryptFile
- _CryptoNG_3DES_CBC_EncryptData
- _CryptoNG_3DES_CBC_EncryptFile
- _CryptoNG_AES_CBC_DecryptData
- _CryptoNG_AES_CBC_DecryptFile
- _CryptoNG_AES_CBC_EncryptData
- _CryptoNG_AES_CBC_EncryptFile
- Updated the compiled Help file with the new functions and a new page that lists common named-value constants in the appendix.
- Added new internal functions to support the new algorithm-specific functions above.
- Cleaned up a few function headers.
- Added new examples, for the new functions, to the examples file.
- Fixed a small bug in how the size of the IV buffer was being determined when doing block cipher encryption and decryption. The length of the IV should match the algorithm's block size, not its key size. NOTE: The bug did NOT affect the accuracy of the results, just the size of the buffer.
-
Corrected $CNG_KEY_BIT_LENGTH_3DES constant value. The value was changed from 168 to 192. 168 was the usable/logical bit length but the actual bit length is 192.
-
Begun adding algorithm-specific encryption/decryption functions starting with:
-
v1.4.0 (2020-04-03)
- Added a Help file that includes all of the functions, with examples. The look & feel of the help file matches the standard AutoIt help files.
- Updated the _CryptoNG_DecryptFile function to create the output file's path if it doesn't exist.
- Updated the _CryptoNG_EncryptFile function to create the output file's path if it doesn't exist.
-
Cleaned up several of the function headers.
-
v1.3.0 (2020-02-24)
- Added _CryptoNG_GenerateRandom and supporting internal function. (Suggested by PeterPE)
-
Added an example, of how the new _CryptoNG_GenerateRandom function can be implemented, to the CryptoNG_Examples.au3 file.
-
v1.2.0 (2020-01-25)
- Added _CryptoNG_CreateRSAKeyPair and supporting internal functions, constants, and structures. (Suggested by Network_Guy)
-
Added an example of how to create RSA key pairs, using _CryptoNG_CreateRSAKeyPair, to the CryptoNG_Examples.au3 file.
-
v1.1.1 (2019-12-03)
- Corrected the _CryptoNG_PBKDF2 function header. The syntax line was using the syntax for the _CryptoNG_HashData function.
-
Changed variable name in the _CryptoNG_PBKDF2 function from $iKeyBitLength to $iDKeyBitLength to more aptly describe its meaning, desired key bit length.
-
v1.1.0 (2019-12-02)
- Cleaned up the __CryptoNG_Startup & __CryptoNG_Shutdown functions. (Suggested by argumentum)
- Added the ability to specify a desired algorithm provider when encrypting, decrypting, hashing, or using the PBKDF2 function. (Suggested by mLipok)