13.15. Gcrypt symmetric cipher functions
Prev | Chapter 13. Wireshark’s Lua API Reference Manual | Next

## 13.15. Gcrypt symmetric cipher functions

A `GcryptCipher` object represents gcypt symmetric cipher in Lua.

The cipher functions are used for symmetrical cryptography, i.e. cryptography using a shared key. The programming model follows an open/process/close paradigm and is in that similar to other building blocks provided by Libgcrypt.

There is an example after the `GcryptCipher.authenticate` function.

### 13.15.1. GcryptCipher

#### 13.15.1.1. GcryptCipher.open(algorithm, mode, flags)

Creates a new `GcryptCipher` object.

This object uses the symmetric cipher functions to encrypt or decrypt data.

#### 13.15.1.2. Example

        local cipher = GcryptCipher.open(GCRY_CIPHER_AES, GCRY_CIPHER_MODE_CBC, 0)

##### Arguments

algorithm
  Select the algorithm for this cipher.

mode
  Select mode for this algorithm

flags
  Set the flags for this cipher

##### Returns

The new GcryptCipher object.

#### 13.15.1.3. gcryptcipher:__tostring()

Returns a short label of the form `GcryptCipher: (<state>)` where <state> is `open` while the cipher handle is live and `closed` once it has been garbage-collected. Libgcrypt does not expose algorithm/mode metadata back from a `gcry_cipher_hd_t`, so the label intentionally stops at the open/closed state instead of guessing.

##### Returns

The string.

#### 13.15.1.4. gcryptcipher:ctl(cmd, buffer)

Perform various operations on the cipher object H.

#### 13.15.1.5. Example

        local cipher = GcryptCipher.open(GCRY_CIPHER_AES, GCRY_CIPHER_MODE_CBC, 0)
        -- CFB mode synchronization
        cipher:ctl(GCRYCTL_CFB_SYNC, ByteArray.new())
        -- enabling CBC-MAC mode
        cipher:ctl(GCRYCTL_SET_CBC_MAC, ByteArray.new())

##### Arguments

cmd
  Command identifier.

buffer
  `ByteArray` as buffer and buffer length.

#### 13.15.1.6. gcryptcipher:info(what, buffer_size, nbytes)

Retrieve various information about the cipher object H.

#### 13.15.1.7. Example

        local cipher = GcryptCipher.open(GCRY_CIPHER_AES, GCRY_CIPHER_MODE_GCM, 0)
        -- Get the tag length of GCM.
        local userdata, nbytes =  cipher:info(GCRYCTL_GET_TAGLEN, NULL, 1)
        print("Tag length: " .. tostring(nbytes))

##### Arguments

what
  Select what info will be returned.

buffer_size
  Buffer size or NULL

nbytes
  Nbytes integer or NULL

#### 13.15.1.8. gcryptcipher:encrypt(out, [in])

Encrypt the plaintext of size INLEN in IN using the cipher handle H into the buffer OUT which has an allocated length of OUTSIZE. For most algorithms it is possible to pass NULL for in and do a in-place encryption of the data returned in a `ByteArray`.

#### 13.15.1.9. Example

        local cipher = GcryptCipher.open(GCRY_CIPHER_AES, GCRY_CIPHER_MODE_CBC, 0)
        cipher:setkey(ByteArray.new("abcdefabcdef1234abcdefabcdef1234"))
        local encrypted = cipher:encrypt(NULL, ByteArray.new("000102030405060708090a0b0c0d0e0f"))
        print("Encrypted: " .. encrypted:tohex())
        -- in place encryption
        cipher:ctl(GCRYCTL_RESET, ByteArray.new())
        local data = ByteArray.new("000102030405060708090a0b0c0d0e0f")
        cipher:encrypt(data)
        print("In-place encrypted: " .. data:tohex())

##### Arguments

out
  `ByteArray` with data for in-place encryption or NULL

in (optional)
  `ByteArray` with data or NULL

#### 13.15.1.10. gcryptcipher:decrypt(out, [in])

The counterpart to gcry_cipher_encrypt.

#### 13.15.1.11. Example

        local cipher = GcryptCipher.open(GCRY_CIPHER_AES, GCRY_CIPHER_MODE_CBC, 0)
        cipher:setkey(ByteArray.new("abcdefabcdef1234abcdefabcdef1234"))
        local decrypted = cipher:decrypt(NULL, ByteArray.new("E27FC30A38E17B6BB7E67AFF2800792F"))
        print("Decrypted: " .. decrypted:tohex())
        -- in place decryption
        cipher:ctl(GCRYCTL_RESET, ByteArray.new())
        local data = ByteArray.new("E27FC30A38E17B6BB7E67AFF2800792F")
        cipher:decrypt(data)
        print("In-place decrypted: " .. data:tohex())

##### Arguments

out
  `ByteArray` with data for in-place decryption or NULL

in (optional)
  `ByteArray` with data or NULL

#### 13.15.1.12. gcryptcipher:setkey(key)

Set KEY of length KEYLEN bytes for the cipher handle HD.

#### 13.15.1.13. Example

        local cipher = GcryptCipher.open(GCRY_CIPHER_AES, GCRY_CIPHER_MODE_CBC, 0)
        cipher:setkey(ByteArray.new("abcdefabcdef1234abcdefabcdef1234"))

##### Arguments

key
  `ByteArray` as buffer and buffer length.

#### 13.15.1.14. gcryptcipher:setiv(iv)

Set initialization vector IV of length IVLEN for the cipher handle HD.

#### 13.15.1.15. Example

        local cipher = GcryptCipher.open(GCRY_CIPHER_AES, GCRY_CIPHER_MODE_CBC, 0)
        cipher:setiv(ByteArray.new("abcdefabcdef1234abcdefabcdef1234"))

##### Arguments

iv
  `ByteArray` as buffer and buffer length.

#### 13.15.1.16. gcryptcipher:authenticate(abuf)

Provide additional authentication data for AEAD modes/ciphers.

#### 13.15.1.17. Example

        local cipher_encrypt = GcryptCipher.open(GCRY_CIPHER_AES, GCRY_CIPHER_MODE_GCM, 0)
        cipher_encrypt:setkey(ByteArray.new("abcdefabcdef1234abcdefabcdef1234"))
        cipher_encrypt:setiv(ByteArray.new("01020304050607080102030405060708"))

        local cipher_decrypt = GcryptCipher.open(GCRY_CIPHER_AES, GCRY_CIPHER_MODE_GCM, 0)
        cipher_decrypt:setkey(ByteArray.new("abcdefabcdef1234abcdefabcdef1234"))
        cipher_decrypt:setiv(ByteArray.new("01020304050607080102030405060708"))

        print("Plain data: " .. ByteArray.new("000102030405060708090a0b0c0d0e0f"):tohex())
        cipher_encrypt:authenticate(ByteArray.new("55667788"))
        local encrypted = cipher_encrypt:encrypt(NULL,
            ByteArray.new("000102030405060708090a0b0c0d0e0f"))
        local tag = cipher_encrypt:gettag()
        print("Encrypted data: " .. encrypted:tohex())
        print("Tag: " .. tag:tohex())

        cipher_decrypt:authenticate(ByteArray.new("55667788"))
        local decrypted = cipher_decrypt:decrypt(NULL, encrypted)
        local result, errstring = cipher_decrypt:checktag(tag)
        if (result == 0) then
            print("Message ok!")
            print("Decrypted data: " .. decrypted:tohex())
        else
            print("Manipulated message: " .. errstring)
        end

##### Arguments

abuf
  `ByteArray` as authentication data.

#### 13.15.1.18. gcryptcipher:gettag()

Get authentication tag for AEAD modes/ciphers.

#### 13.15.1.19. gcryptcipher:checktag(tag)

Check authentication tag for AEAD modes/ciphers.

##### Arguments

tag
  `ByteArray` as authentication tag to check.

#### 13.15.1.20. gcryptcipher:setctr(ctr, ctrlen)

Set counter for CTR mode. (CTR,CTRLEN) must denote a buffer of block size length, or (NULL,0) to set the CTR to the all-zero block.

#### 13.15.1.21. Example

        local cipher = GcryptCipher.open(GCRY_CIPHER_AES, GCRY_CIPHER_MODE_CBC, 0)
        cipher:setctr(ByteArray.new("000102030405060708090A0B0C0D0E0F"), 16)

##### Arguments

ctr
  `ByteArray` with ctr or NULL

ctrlen
  CTR Length

### 13.15.2. Global Functions

#### 13.15.2.1. gcry_cipher_algo_info(algorithm, what, [buffer_size], [nbytes])

Retrieve various information about the cipher algorithm ALGO.

#### 13.15.2.2. Example

        local userdata, nbytes = gcry_cipher_algo_info(GCRY_CIPHER_AES, GCRYCTL_GET_KEYLEN, NULL, 0)
        print("Key length: " .. nbytes)
        local userdata, nbytes = gcry_cipher_algo_info(GCRY_CIPHER_AES, GCRYCTL_GET_BLKLEN, NULL, 0)
        print("Block length: " .. nbytes)
        local status = gcry_cipher_algo_info(GCRY_CIPHER_AES, GCRYCTL_TEST_ALGO)
        if (status == 0) then
          print("GCRY_CIPHER_AES - Supported.")
        else
          print("GCRY_CIPHER_AES - Not supported.")
        end

##### Arguments

algorithm
  Select the algorithm for this function.

what
  Select the algorithm for this function.

buffer_size (optional)
  Buffer size or NULL, optional only if nbytes not present.

nbytes (optional)
  Nbytes integer or NULL, optional.

#### 13.15.2.3. gcry_cipher_algo_name(algorithm)

Map the cipher algorithm whose ID is contained in ALGORITHM to a string representation of the algorithm name. For unknown algorithm IDs this function returns "?".

#### 13.15.2.4. Example

        local name = gcry_cipher_algo_name(GCRY_CIPHER_AES)
        print(name)

##### Arguments

algorithm
  Algorithm id for this function.

#### 13.15.2.5. gcry_cipher_map_name(algorithm)

Map the algorithm name NAME to an cipher algorithm ID. Return 0 if the algorithm name is not known.

#### 13.15.2.6. Example

        local id = gcry_cipher_map_name("AES")
        print(id)

##### Arguments

algorithm
  Algorithm name for this function.

#### 13.15.2.7. gcry_cipher_mode_from_oid(string)

Given an ASN.1 object identifier in standard IETF dotted decimal format in STRING, return the encryption mode associated with that OID or 0 if not known or applicable.

#### 13.15.2.8. Example

        local mode = gcry_cipher_mode_from_oid("2.16.840.1.101.3.4.1.2")
        -- reurned value 3 means GCRY_CIPHER_MODE_CBC
        print(mode)

##### Arguments

string
  ASN.1 object identifier as STRING.

#### 13.15.2.9. gcry_cipher_get_algo_keylen(algorithm)

Retrieve the key length in bytes used with algorithm A.

#### 13.15.2.10. Example

        local length = gcry_cipher_get_algo_keylen(GCRY_CIPHER_AES)
        print(length)

##### Arguments

algorithm
  Algorithm id for this function.

#### 13.15.2.11. gcry_cipher_get_algo_blklen(algorithm)

Retrieve the block length in bytes used with algorithm A.

#### 13.15.2.12. Example

        local length = gcry_cipher_get_algo_blklen(GCRY_CIPHER_AES)
        print(length)

##### Arguments

algorithm
  Algorithm id for this function.

Prev | Up | Next
13.14. Binary encode/decode support | Home | 13.16. PCRE2 Regular Expressions