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

Cipher

The cipher class is intended for integrators familiar with basic crypto concepts.

Class function​

nevis.crypto.cipher.new(mode, algorithm, key, IV)​

Instantiates a new crypto cipher object.

  • mode: ENCRYPT or DECRYPT.
  • algorithm: Blowfish, DES, DESede, RC4, AES, or AES/GCM.
  • key: Key for encryption/decryption.
  • IV: Initialization value for encryption/decryption.

Both key and IV are 16 bytes long, except for AES/GCM where the key is 32 bytes and the IV is 12 bytes. Longer values are truncated; shorter values are padded with "@" up to 16 bytes. They are interpreted as an ASCII string (1 byte per character), but are not limited to ASCII characters. For non-ASCII values, use \x00–\xFF. There are no defaults for IV or key; both must be provided. We recommend using unique random IVs per encryption.

Sample:

encrypt = nevis.crypto.cipher.new("ENCRYPT", "AES", "mysecret0123456789", "myrandom0123456789")

Object methods​

crypto:updateAAD(aad)​

Sets the associated data used for calculating the authentication tag for AEAD ciphers (currently only AES/GCM is supported). Throws a Lua error when called on a non-AEAD cipher. Does nothing when called without a parameter or with an empty or non-string value. Can be called multiple times, but only before calling update or doFinal.

Sample:

encrypt:updateAAD("aad")

crypto:update(data)​

For streaming encryption, call this method multiple times. The result may be nil if using a block cipher and there is not yet enough data to fill a block. The final call must be crypto:doFinal(data).

Sample:

data = encrypt:update("hello world")

data, tag, status = crypto:doFinal(data)​

Encrypts or decrypts a single string, or terminates a sequence of update calls. Can be called without an argument except when encrypting with an AEAD cipher, in which case the authentication tag must be provided.

Return values:

  • data: The encrypted or decrypted data.
  • tag: The calculated authentication tag (AEAD ciphers only, encryption only).
  • status: The crypto operation status:
    • ok: Successful encryption/decryption.
    • badtag: Authentication tag mismatch (AEAD ciphers only).
    • error: Generic failure. In plain AES mode this usually means the IV or key used for decryption is wrong, but incorrect key/IV detection is not guaranteed. We recommend using AES/GCM or manually verifying the decrypted data.

Sample:

data, tag, status = encrypt:doFinal("hello world")

data, status = crypto:doFinalJava(data)​

Similar to doFinal, but when used with AEAD ciphers it appends the authentication tag into the ciphertext — compatible with Java's Cipher class behavior. Can be used as a drop-in replacement for doFinal when upgrading a non-AEAD cipher to AEAD.

Sample:

data, status = encrypt:doFinalJava("hello world")

Examples​

AES example​

local cryptoKey = "IZ3AS678gO123456"
local cryptoIV = "1234567890123456"
local encrypter = nevis.crypto.cipher.new("ENCRYPT", "AES", cryptoKey, cryptoIV)
local decrypter = nevis.crypto.cipher.new("DECRYPT", "AES", cryptoKey, cryptoIV)
local encryptedData = encrypter:doFinal("secretData100")
local plaintext = decrypter:doFinal(encryptedData)

AES/GCM example where the authentication tag is appended to the ciphertext​

local cryptoKey = "crypt0key9O123456"
local cryptoIV = "1234567890123456"
local cryptoAAD = "aad"
 
local encrypter = nevis.crypto.cipher.new("ENCRYPT", "AES/GCM", cryptoKey, cryptoIV)
encrypter:updateAAD(cryptoAAD)
local encryptedDataWithTag = encrypter:doFinalJava("secretData200")
 
local decrypter = nevis.crypto.cipher.new("DECRYPT", "AES/GCM", cryptoKey, cryptoIV)
decrypter:updateAAD(cryptoAAD)
local plaintext, decryptionStatus = decrypter:doFinalJava(encryptedDataWithTag)

AES/GCM example using explicitly provided tag​

local cryptoKey = "crypt0key9O123456"
local cryptoIV = "1234567890123456"
local cryptoAAD = "aad"
 
local encrypter = nevis.crypto.cipher.new("ENCRYPT", "AES/GCM", cryptoKey, cryptoIV)
encrypter:updateAAD(cryptoAAD)
local encryptedData, authTag = encrypter:doFinal("secretData200")
 
local decrypter = nevis.crypto.cipher.new("DECRYPT", "AES/GCM", cryptoKey, cryptoIV)
decrypter:updateAAD(cryptoAAD)
local p1 = decrypter:update(encryptedData)
local p2, decryptionStatus = decrypter:doFinal(authTag)
local plaintext = p1..p2

For examples mixing the Cipher class with the AesGcmEncrypter class, visit the AesGcmEncrypter page.