Cipher object methods
| Method | Description | Sample |
|---|---|---|
| crypto:updateAAD(aad) | Sets the associated data that is used for calculating the authentication tag for Authenticated encryption with associated data (AEAD) ciphers (currently only AES/GCM is supported). When called on a non-AEAD cipher, a lua error is thrown. The function does nothing when called without a parameter or if its input is an empty string or a non-string. Can be called multiple times, but only before calling the object's update or doFinal function. | encrypt:updateAAD("aad") |
| crypto:update(data) | For the streaming encryption, there is an update function that can be called many times. The cryptoBuf can be nil if using a block cipher and if there is not yet enough data to fill it up. The last call has to be crypto:doFinal(data), see the corresponding line. | data = encrypt:update("hello world") |
| crypto:doFinal(data) | To encrypt a single string (not streaming) or terminate a sequence of update calls, use doFinal. doFinal can also be called without an argument, except when encrypting with an AEAD cipher. In that case, the authentication tag has to be provided. The first result contains the encrypted / decrypted data. The second result contains the calculated authentication tag (only available for AEAD ciphers and only returned during encryption). The third result contains the crypto operation's status, possible values are: ok: Successful encryption/decryption. badtag: Authentication tag mismatch (only available for AEAD ciphers). * error: Generic failure. In plain AES mode, this usually means that the IV or key used for the decryption is wrong, but the incorrect key/IV detection is not guaranteed. We recommend another cipher to verify the payload integrity (AES/GCM), or manually verify the decrypted data. | data, tag, status = encrypt:doFinal("hello world") |
| crypto:doFinalJava(data) | Similar to the doFinal method, the only difference being when used with AEAD ciphers: it appends the authentication tag into the ciphertext. This is a compatibility function that acts like Java's Cipher class' doFthe ciphertext. To upgrade a non-AEAD cipher into an AEAD one, this function can be used as a drop-in replacement for the doFinal method, because it has the same interface for AEADthe ciphertext. The first result is the same as in doFinal, except for encrypting with AEAD ciphers. In that case, it also contains the the ciphertext. The second result is the same crypto operation's status as in doFinal. | data, status = encrypt:doFinal("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 Object Methods page.