(PureBasic) AES GCM Encrypt and Decrypt a File

See more Encryption Examples

Demonstrates how to AES GCM encrypt and decrypt a file.

Chilkat PureBasic Module Download Chilkat PureBasic Module

IncludeFile "CkCrypt2.pb"

Procedure ChilkatExample()

    ; This example assumes the Chilkat API to have been previously unlocked.
    ; See Global Unlock Sample for sample code.

    crypt.i = CkCrypt2::ckCreate()
    If crypt.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    ; Set the encryption algorithm to "AES"	
    CkCrypt2::setCkCryptAlgorithm(crypt, "aes")

    ; Indicate that the Galois/Counter Mode (GCM) should be used:
    CkCrypt2::setCkCipherMode(crypt, "gcm")

    ; KeyLength may be 128, 192, 256
    CkCrypt2::setCkKeyLength(crypt, 256)

    ; This is the 256-bit AES secret key (in hex format)
    K.s = "000102030405060708090A0B0C0D0E0F000102030405060708090A0B0C0D0E0F"

    ; This is the 16-byte initialization vector (in hex format)
    IV.s = "000102030405060708090A0B0C0D0E0F"

    ; This is the OPTIONAL additional data (in hex format) to be used as input to the GCM AEAD algorithm,
    ; but is not included in the output.  It plays a role in the computation of the
    ; resulting authenticated tag.
    AAD.s = "feedfacedeadbeeffeedfacedeadbeefabaddad2"

    ; Set the secret key and IV
    CkCrypt2::ckSetEncodedIV(crypt,IV,"hex")
    CkCrypt2::ckSetEncodedKey(crypt,K,"hex")

    ; Set the additional authenticated data (AAD)
    success.i = CkCrypt2::ckSetEncodedAad(crypt,AAD,"hex")

    ; Encrypt a file.
    inFile.s = "qa_data/hamlet.xml"
    outFile.s = "c:/temp/qa_output/hamlet_aes_gcm.enc"
    success = CkCrypt2::ckCkEncryptFile(crypt,inFile,outFile)
    If success = 0
        Debug CkCrypt2::ckLastErrorText(crypt)
        CkCrypt2::ckDispose(crypt)
        ProcedureReturn
    EndIf

    ; Get the authentication tag in hex format
    authTag.s = CkCrypt2::ckGetEncodedAuthTag(crypt,"hex")
    Debug "authentication tag = " + authTag

    ; Decrypt..

    ; Before decrypting, you must provide the expected authentication tag.
    ; The decrypt will fail if the resulting authentication tag computed while decrypting is not equal to the
    ; expected authentication tag.
    CkCrypt2::ckSetEncodedAuthTag(crypt,authTag,"hex")

    inFile = outFile
    outFile = "c:/temp/qa_output/hamlet_restored.xml"
    success = CkCrypt2::ckCkDecryptFile(crypt,inFile,outFile)
    If success = 0
        Debug CkCrypt2::ckLastErrorText(crypt)
        CkCrypt2::ckDispose(crypt)
        ProcedureReturn
    EndIf

    Debug "Success."

    ; --------------------------------------------------------------------------------------------
    ; About AES-GCM:

    ; AES-GCM (Advanced Encryption Standard - Galois/Counter Mode) is a widely-used
    ; encryption mode that provides both confidentiality (encryption) and
    ; integrity/authentication (data integrity verification) in one operation. It is
    ; commonly used in secure communications due to its efficiency and strong security
    ; properties.
    ; 
    ; Key Concepts:
    ; 
    ;     AES (Advanced Encryption Standard):
    ; 
    ;         AES is a symmetric encryption algorithm, meaning the same key is used
    ;         for both encryption and decryption.
    ; 
    ;         It operates on fixed-size blocks of data (128 bits) using key sizes of
    ;         128, 192, or 256 bits.
    ; 
    ;         In AES-GCM, AES is used to perform the actual data encryption.
    ; 
    ;     GCM (Galois/Counter Mode):
    ; 
    ;         Counter Mode (CTR): GCM uses counter mode for encryption. In this mode,
    ;         a nonce (or initialization vector, IV) and a counter are combined and encrypted
    ;         with AES. The result is XORed with the plaintext to produce the ciphertext. 
    ; 
    ;         Galois Mode (GMAC): GCM also includes an authentication mechanism based
    ;         on a Galois field. It generates an authentication tag, which ensures the
    ;         integrity of both the ciphertext and any additional data (called AAD -
    ;         Additional Authenticated Data). This tag is verified during decryption to ensure
    ;         that the data hasn't been tampered with.
    ; 
    ; Key Features:
    ; 
    ;     Confidentiality (Encryption):
    ; 
    ;         The plaintext is encrypted using AES in counter mode. Each block of
    ;         plaintext is XORed with the output of AES applied to a combination of the IV and
    ;         an incremented counter.
    ; 
    ;     Integrity (Authentication):
    ; 
    ;         In addition to encryption, GCM provides authentication for both the
    ;         encrypted data (ciphertext) and any Additional Authenticated Data (AAD), such as
    ;         headers or metadata that need to be protected but not encrypted.
    ; 
    ;         The authentication tag is generated using a Galois field multiplication
    ;         of the ciphertext and AAD. This ensures that any changes to the encrypted
    ;         message or the AAD will be detected during decryption.
    ; 
    ; Key Components:
    ; 
    ;     - Plaintext: The data you want to encrypt.
    ;     - Ciphertext: The encrypted data.
    ;     - Key: A symmetric key used for both encryption and decryption.
    ;     - Nonce/IV: A unique value used for each encryption to ensure security. It is not secret but should never be reused with the same key.
    ;     - AAD (Additional Authenticated Data): Optional data that is not encrypted but needs to be authenticated (e.g., headers).
    ;     - Authentication Tag: A tag generated to verify the integrity and authenticity of the ciphertext and AAD


    CkCrypt2::ckDispose(crypt)


    ProcedureReturn
EndProcedure