CryptoNG UDF - Cryptography API: Next Gen

[TheXman]

Encryption / Decryption / Hashing / Signing

Purpose

Cryptography API: Next Generation (CNG) is Microsoft's long-term replacement for their CryptoAPI.  Microsoft's CNG is designed to be extensible at many levels and cryptography agnostic in behavior.  Although the Crypt.au3 UDF lib that is installed with AutoIt3 still works well, the advapi32.dll functions that it uses have been deprecated.  In addition the Crypt.au3 UDF lib, as it is currently written, has a very limited ability to decrypt AES data that was not encrypted using Crypt.au3 functions.  That is because Crypt.au3 functions do not allow you to specify an actual key or initialization vector (IV).  It only lets you specify data to be used to derive a key and uses a static IV.  This UDF was created to offer a replacement for the deprecated functions used by Crypt.au3.  According to Microsoft, deprecated functions may be removed in future release.  It was also created to allow more flexibility and functionality in encryption/decryption/hashing/signing and to expand the ability for users to implement cryptography in their scripts.

Description

This UDF implements some of Microsoft's Cryptography API: Next Generation (CNG) Win32 API functions.  It implements functions to encrypt/decrypt text and files, generate hashes, derive keys using Password-Based Key Derivation Function 2 (PBKDF2), create and verify signatures, and has several cryptography-related helper functions.  The UDF can implement any encryption/decryption algorithms and hashing algorithms that are supported by the installed cryptography providers on the PC in which it is running.  Most, if not all, of the "magic number" 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

• Algorithm-Specific Symmetric Encryption/Decryption Functions
  • _CryptoNG_AES_CBC_EncryptData
  • _CryptoNG_AES_CBC_DecryptData
     
  • _CryptoNG_AES_CBC_EncryptFile
  • _CryptoNG_AES_CBC_DecryptFile
     
  • _CryptoNG_AES_ECB_EncryptData
  • _CryptoNG_AES_ECB_DecryptData
     
  • _CryptoNG_AES_GCM_EncryptData
  • _CryptoNG_AES_GCM_DecryptData
     
  • _CryptoNG_3DES_CBC_EncryptData
  • _CryptoNG_3DES_CBC_DecryptData
     
  • _CryptoNG_3DES_CBC_EncryptFile
  • _CryptoNG_3DES_CBC_DecryptFile
     
• Generic Symmetric Encryption/Decryption Functions
  • _CryptoNG_EncryptData
  • _CryptoNG_DecryptData
     
  • _CryptoNG_EncryptFile
  • _CryptoNG_DecryptFile
     
• Hashing Functions
  • _CryptoNG_HashData
  • _CryptoNG_HashFile
     
  • _CryptoNG_PBKDF2
     
• Asymmetric (Public/Private Key) Cryptography Functions
  • _CryptoNG_ECDSA_CreateKeyPair
  • _CryptoNG_ECDSA_SignHash
  • _CryptoNG_ECDSA_VerifySignature
     
  • _CryptoNG_RSA_CreateKeyPair
  • _CryptoNG_RSA_CreateKeyPairEx
  • _CryptoNG_RSA_EncryptData
  • _CryptoNG_RSA_DecryptData
  • _CryptoNG_RSA_SignHash
  • _CryptoNG_RSA_VerifySignature
     
• Misc / Helper Functions
  • _CryptoNG_CryptBinaryToString
  • _CryptoNG_CryptStringToBinary
     
  • _CryptoNG_GenerateRandom
     
  • _CryptoNG_EnumAlgorithms
  • _CryptoNG_EnumRegisteredProviders
  • _CryptoNG_EnumKeyStorageProviders
     
  • _CryptoNG_LastErrorMessage
     
  • _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

 

Get CryptoNG from the AutoIt Downloads Area

Edited February 23 by TheXman

[mLipok]

Thanks for sharing.
Is this possible to use CNG feature to use Qualified Certificate store on CryptoCard ?
For example sign PDF with PADES ?

[mLipok]

For example function: 

eunmerate_registered_providers_example()

Gives me this result:

 

And I want to use "SimplySign KSP" to use my CryptoCard by using PIN to my certificate.

 

[mLipok]

Could you also be so nice and add this two following lines of code:

#AutoIt3Wrapper_Run_AU3Check=Y
#AutoIt3Wrapper_Au3Check_Parameters=-d -w 1 -w 2 -w 3 -w 4 -w 5 -w 6 -w 7

to the top of your UDF ?

 

[TheXman]

  On 12/2/2019 at 2:49 PM, mLipok said:

Thanks for sharing.
Is this possible to use CNG feature to use Qualified Certificate store on CryptoCard ?
For example sign PDF with PADES ? 

Expand  

You're quite welcome!  I hope you and others find it useful.

I wasn't familiar with PAdES so I was researching it a bit before trying to reply.  It appears that it is a set of restrictions and extensions related to signing a PDF.  After doing some quick Googling, it appears that it may be possible.  CNG does have APIs to create signatures.  Unfortunately, those API were not in my initial release of the CryptoNG UDF.  I do plan to extend the UDF's functionality.  So maybe signature creation will be on the short list. 

https://www.codeproject.com/Articles/1256991/The-AdES-Collection-CAdES-XAdES-PAdES-and-ASiC

 

 

[TheXman]

  On 12/2/2019 at 2:56 PM, mLipok said:

And I want to use "SimplySign KSP" to use my CryptoCard by using PIN to my certificate.

Expand  

One of the nice things about CNG is that you can use any registered provider that is installed on the computer.  I didn't include the ability to manually select a provider in the initial version.  Currently, I let the API choose the preferred provider.  That is one of the feature of the Microsoft API.  However, allowing one to choose their provider manually doesn't appear to be too difficult.  I can look into adding that functionality also.

I would just need to modify the OpenAlgorithm API in my UDF to allow the specification of the Provider (pszImplementation).  Currently, I leave it Null.

https://docs.microsoft.com/en-us/windows/win32/api/bcrypt/nf-bcrypt-bcryptopenalgorithmprovider

 

Edited December 2, 2019 by TheXman

[water]

  On 12/2/2019 at 2:58 PM, mLipok said:

Could you also be so nice and add this two following lines of code:

#AutoIt3Wrapper_Run_AU3Check=Y
#AutoIt3Wrapper_Au3Check_Parameters=-d -w 1 -w 2 -w 3 -w 4 -w 5 -w 6 -w 7

to the top of your UDF ?

Expand  

I'm not sure this is a good idea as it forces the user to code his script so it passes this checks as well.

[TheXman]

  On 12/2/2019 at 2:58 PM, mLipok said:

Could you also be so nice and add this two following lines of code:

#AutoIt3Wrapper_Run_AU3Check=Y
#AutoIt3Wrapper_Au3Check_Parameters=-d -w 1 -w 2 -w 3 -w 4 -w 5 -w 6 -w 7

to the top of your UDF ?

 

Expand  

I usually put those directives in the script that includes the UDF.  By putting them in the UDF itself, it may override directives used by the user. which I'm not sure would be an appropriate thing to do.

[TheXman]

  On 12/2/2019 at 2:56 PM, mLipok said:

And I want to use "SimplySign KSP" to use my CryptoCard by using PIN to my certificate.

Expand  

I will add the ability to specify a Crypto Provider to the __CryptoNG_BCryptOpenAlgorithmProvider() function today.  I will publish the updated UDF as soon as I have implemented and tested it.  Unfortunately, that will not help in creating signatures because I haven't added those APIs to the UDF yet.  That will take a little longer to implement and test.   But at least that functionality to choose a Provider, which would be required, will already be there.

Edited December 2, 2019 by TheXman

[water]

Added your UDF to the wiki

[TheXman]

  On 12/2/2019 at 3:46 PM, water said:

Added your UDF to the wiki

Expand  

@water

The link below from the Encryption section of the Wiki does not appear to link to my UDF.

Cryptography API: Next Gen (by TheXman) - Microsoft's long-term replacement for their CryptoAPI.

[water]

Fixed

[TheXman]

Thanks 

[argumentum]

browsing the UDF I believe this sould be added/mod.

Func __CryptoNG_Shutdown()

    _DebugOut(@CRLF & "Function: __CryptoNG_Shutdown()")

    ;If dll file is open, then close it
    If $__gbDllOpened Then
        DllClose($__ghBcryptDll)
        $__ghBcryptDll = -1 ; <=======
        $__gbDllOpened = False
    EndIf

EndFunc

Love it !, thanks for sharing.

[TheXman]

  On 12/2/2019 at 4:28 PM, argumentum said:

browsing the UDF I believe this sould be added/mod.

Expand  

Thanks!    

Just so that I understand your suggestion, are you suggesting that I add that line in order to release any resources related to the handle?  If so, having closed the handle, wouldn't those resources be released when the variable goes out of scope - in this case, when the script exits?  __CryptoNG_Shutdown() is an internal function that only gets executed upon exiting the script.  The startup function, which is also an internal function, registered the shutdown function to execute on exit.  I'm not trying to be difficult, I'm truly trying to understand the need to add that line.

Edited December 2, 2019 by TheXman

[argumentum]

The way I see it, one can run the Func at will,  ...and wait for it ..., some one will  
Also the only flag you use is "$__ghBcryptDll = -1", so is needed.
By doing so, the "$__gbDllOpened = False" flag is unneeded, given that "$__ghBcryptDll = -1" determines if is loaded or not.

[argumentum]

<snip>

Edited December 2, 2019 by argumentum
not needed

[TheXman]

  On 12/2/2019 at 4:49 PM, argumentum said:

Also the only flag you use is "$__ghBcryptDll = -1", so is needed.
By doing so, the "$__gbDllOpened = False" flag is unneeded, given that "$__ghBcryptDll = -1" determines if is loaded or not. 

Expand  

Yes, you are correct.  The $__gbDllOpened flag is a holdover from some original logic that I removed.  It really isn't necessary because I can just check whether the handle = -1 (as you have pointed out).  Thanks, I will definitely clean that up. 

  On 12/2/2019 at 4:49 PM, argumentum said:

The way I see it, one can run the Func at will,  ...and wait for it ..., some one will  

Expand  

Yes, one could execute internal/helper functions if they choose to.  But if they do so, hopefully they understand what they are doing.  To me, although they are visible, I look at internal functions as I would functions that are private in scope in an OOP environment.  They should not be executed out of context or really at all.  But you are right, people will do it.

Edited December 2, 2019 by TheXman

[mLipok]

 

 

 

 

  On 12/2/2019 at 3:03 PM, TheXman said:

You're quite welcome!  I hope you and others find it useful.

I wasn't familiar with PAdES so I was researching it a bit before trying to reply.  It appears that it is a set of restrictions and extensions related to signing a PDF.  After doing some quick Googling, it appears that it may be possible. 

Expand  

It would be nice even if this UDF gives you a possibility to Sign XML or PDF , as XADES or verify the signed file.

 

[TheXman]

@mLipok

CNG does have some signature-related APIs as it relates to generating signatures and signature verification.  I will have to look into whether it can actually do the signing of specific file types.  If any of the requested functionality is possible and relevant to the stated purpose of the CryptoNG UDF, I will definitely look into adding that functionality.  If not, then it may be a separate project that I can look into tackling.