AES GCM Encryption - Mijick/AES-GCM-HKDF GitHub Wiki

Overview

AES-GCM (Advanced Encryption Standard - Galois/Counter Mode) provides authenticated encryption, ensuring data confidentiality and integrity.

Available Methods

AES-GCM-HKDF library offers 3 methods, allowing for different levels of automation in key derivation and encryption.

Method	Use Case
encrypt(privateKey: publicKey: derivationConfig: aesConfig:)	Generate a shared secret, derive a key, and encrypt data in one step.
encrypt(key: derivationConfig: aesConfig:)	Derive a key using HKDF, then encrypt the data.
encrypt(secret: configuration:)	Encrypt data using a pre-derived key.

1️⃣ Configure

AES-GCM configuration

AES-GCM encryption requires configuration parameters to be executed. Use M_AES_GSM_Configuration model to set-up them.

Properties

Property	Type	Description
message	Data	The plaintext (for encryption).
iv	Data	The Initialization Vector (IV). Can be randomly generated with function Data.randomIV().
add	Data	Optional. Additional Authenticated Data (AAD). Can be randomly generated with function Data.randomAAD().

Usage

• Empty AAD

let aesConfig = M_AES_GSM_Configuration(
    message: Data("Hello, World!".utf8),
    iv: .randomIV(),
)

• Random IV and AAD

let aesConfig = M_AES_GSM_Configuration(
    message: Data("Hello, World!".utf8),
    iv: .randomIV(),
    add: .randomAAD()
)

HKDF configuration

Take a look at HKDF configuration requirements here

2️⃣ AES-GCM+HKDF with key agreement

This method performs the full encryption process:

1. Generates a shared secret using ECDH key agreement.
2. Derives a key using HKDF.
3. Encrypts data using AES-GCM.

func encrypt(privateKey: M_KeyProtocol, 
             publicKey: M_KeyProtocol, 
             derivationConfig: M_HKDF_Configuration, 
             aesConfig: M_AES_GSM_Configuration) throws -> M_AES_GCM_HKDF_Result

Usage

let privateKey = P256.KeyAgreement.PrivateKey()
let publicKey = privateKey.publicKey
let hkdfConfig = M_HKDF_Configuration(hashVariant: .sha256, length: 32)
let aesConfig = M_AES_GSM_Configuration(message: Data("Hello, Secure".utf8), iv: Data.randomIV())

let result = try M_AES_GCM_HKDF.encrypt(privateKey: privateKey, 
                                        publicKey: publicKey, 
                                        derivationConfig: hkdfConfig,   
                                        aesConfig: aesConfig)

2️⃣ AES-GCM+HKDF using existed key

This method derives a key bytes using HKDF, then encrypts data.

func encrypt(key: Data, derivationConfig: M_HKDF_Configuration, aesConfig: M_AES_GSM_Configuration) throws -> M_AES_GCM_HKDF_Result

Usage

let hkdfConfig = M_HKDF_Configuration(hashVariant: .sha256, length: 32)
let aesConfig = M_AES_GSM_Configuration(message: Data("Hello, Secure".utf8), iv: Data.randomIV())

let encryptionResult = try M_AES_GCM_HKDF.encrypt(key: sharedSecret, derivationConfig: hkdfConfig, aesConfig: aesConfig)

3️⃣ AES-GCM using secret

This method encrypts data when you already have a symmetric key.

func encrypt(secret: Data, configuration: M_AES_GSM_Configuration) throws -> M_AES_Encryption_Result

Usage

let secret: Data
let config = M_AES_GSM_Configuration(message: Data("Hello, World!".utf8), iv: Data.randomIV())

let encryptionResult = try M_AES_GCM_HKDF.encrypt(secret: derivedKey, configuration: aesConfig)

4️⃣ Get result

- AES-GSM result

M_AES_Encryption_Result is a structured output returned by the AES-GCM encryption process. It contains all the essential components required for secure decryption and message authentication.

Properties

Property	Type	Description
iv	Data	The Initialization Vector used for encryption. Must be reused for decryption.
aad	Data	Additional Authenticated Data used for integrity verification. Must be reused for decryption.
cipertext	Data	The encrypted message.
tag	Data	The authentication tag that ensures the ciphertext has not been tampered with. Must be reused for decryption.

- AES-GSM+HKDF Result

M_AES_GCM_HKDF_Result is a structured output that stores both the data for HKDF derivation and the AES-GCM encryption results.

Properties

Property	Type	Description
derivationResult	M_HKDF_Result	Read more here
encryptionResult	M_AES_Encryption_Result	Read more here