Skip to main content
Version: 9.2605.x.x RR

AesGcmEncrypter

The AesGcmEncrypter class is intended for integrators without basic knowledge of cryptography.

Added features compared to Crypto class:

  • A basic KDF function is used to generate proper encryption keys based on arbitrary length passwords.
  • Randomized IVs are automatically used.
  • The ciphered data is Base64 encoded internally.

Class function​

nevis.crypto.aesgcmencrypter.new(password, ivLen=12, tagLen=16)​

Instantiate a new encrypter object based on the AES-256-GCM cipher. Password length is arbitrary; longer passwords offer higher entropy. The password's sha1 hash is used as the cipher's key (other systems might handle passwords differently). The password is interpreted as an ASCII string (1 byte per character), but it is not limited to ASCII characters. For non-ASCII values, use \x00 - \xFF.

The ivLen parameter sets the length of the generated IVs. It has no effect when the user supplies the IV to the encrypt and decrypt functions. The default IV length is 12 bytes.

The tagLen parameter sets the authentication tag's length used to protect the encrypted data against tampering. The default tag length is 16 bytes.

Sample:

cryptoEngine = nevis.crypto.aesgcmencrypter.new("secret_password", 12, 16)

Object methods​

cipher, authTag = encrypter:encrypt(plaintext[, aad][, nonce])​

Encrypts the given data using AES-256 GCM. It takes the following parameters:

  • plaintext: The input to encrypt.
  • aad: Associated data that is used for calculating the authentication tag. The same value must be provided during decrypting. Optional parameter, the default value is an empty string.
  • nonce: Provides the IV to the cipher.

The input parameters are interpreted as an ASCII string (1 byte per character), but they are not limited to ASCII characters. For non-ASCII values, use \x00 - \xFF.

The result is Base64 encoded internally, so it is always text-based. It contains the cipher text and the authentication tag. In random IV mode (when nonce is not given), the output of repeated encrypt calls may be different with the same input, as the random salt makes them likely to be different.

Sample:

cipher, authTag = encrypter:encrypt("hello world", "aad", "\x00\x01\x02")

plaintext, status = encrypter:decrypt(ciphertext[, aad][, nonce])​

Decrypts the given data. It takes the following input parameters:

  • ciphertext: The first result of a previous encrypt call (contains the encrypted message with the IV if it was generated, in Base64 encoded format).
  • tag: The second result of a previous encrypt call (contains the authentication tag in Base64 encoded format).
  • aad: Associated data, must be the same as the encrypt call's aad value.
  • nonce: Provides the IV to the cipher, that must also be the same as the encrypt call's nonce value.

The first result contains the decoded message. It is empty when decrypting with the wrong key, or when the input's authentication tag does not match the given data. The second result shows the decryption status:

  • ok: Successful decryption.
  • badtag: Authentication tag mismatch.
  • error: Other error occurred. In case of an error, a NOTICE is traced in navajo.log with further information.

Sample:

data, status = encrypter:decrypt(cipher, tag, "aad", "\x00\x01\x02")

Example​

local cryptoPass = "secret_password"
local cryptoEngine = nevis.crypto.aesgcmencrypter.new(cryptoPass, 12, 16)
local encryptedData, authTag = cryptoEngine:encrypt("SecretData100", "aad", "nonce")
local plaintext, status = cryptoEngine:decrypt(ciphertext, authTag, "aad", "nonce")
if status == "ok" then
   -- Successful decryption
elseif status == "badtag" then
   -- Authentication tag mismatch
else
   -- Other error
end

Encrypt with AesGcmEncrypter, then decrypt with Cipher​

local cryptoKey = "IZ3AS678gO123456"
local cryptoIV = "1234567890123456"
local encrypter = nevis.crypto.aesgcmencrypter.new(cryptoKey)
local encryptedData, tag = encrypter:encrypt("HelloWorld", "TheAAD", cryptoIV)
 
-- Get the raw key with the following command: echo -n "IZ3AS678gO123456" | openssl sha1
local cryptoKeyRaw = "\xf9\x7f\xf8\xc8\xd2\x84\x89\x4b\xe6\xba\x02\x8a\x7a\x59\xcb\xd7\xb1\xfb\x89\xd7"
local decrypter = nevis.crypto.cipher.new("DECRYPT", "AES/GCM", cryptoKeyRaw, cryptoIV)
decrypter:updateAAD("TheAAD")
local part1 = decrypter:update(base64:decode(encryptedData))
local part2, decodeStatus = decrypter:doFinal(base64:decode(tag))
local plaintext = part1 .. part2

Encrypt with Cipher, then decrypt with AesGcmEncrypter​

local cryptoKey = "IZ3AS678gO123456"
local cryptoIV = "1234567890123456"
-- Get the raw key with the following command: echo -n "IZ3AS678gO123456" | openssl sha1
local cryptoKeyRaw = "\xf9\x7f\xf8\xc8\xd2\x84\x89\x4b\xe6\xba\x02\x8a\x7a\x59\xcb\xd7\xb1\xfb\x89\xd7"
local encrypter = nevis.crypto.cipher.new("ENCRYPT", "AES/GCM", cryptoKeyRaw, cryptoIV)
encrypter:updateAAD("TheAAD")
local cipherText, authTag = encrypter:doFinal("SecretData100")
cipherText = base64:encode(cipherText)
authTag = base64:encode(authTag)
 
local decrypter = nevis.crypto.aesgcmencrypter.new(cryptoKey)
local plainText, decodeStatus = encrypter:decrypt(cipherText, "TheAAD", cryptoIV)