6. Liquid Crypto Library

Liquid crypto library provides a set of cryptographic primitives that can be used to offload cryptographic operations to hardware accelerators. The library is optimized for performance and low power consumption.

The library provides a set of APIs for various cryptographic operations, including symmetric encryption, hashing, and public key cryptography. The library is designed to be modular and can be easily extended to support new algorithms and hardware accelerators.

6.1. Architecture Overview

The Liquid Crypto Library is designed to be modular and extensible. The library is built on top of the ‘eth_transport’ library from DAO, which provides a set of APIs for managing hardware accelerators and pushing cryptographic operations to the hardware accelerators. The ‘eth_transport’ library internally uses the ‘rte_ethdev’ library from DPDK to manage the hardware accelerators.

For more information about the ‘eth_transport’ library, see the Ethernet Transport Library guide.

The Liquid Crypto Library uses a queue-based architecture to manage the execution of cryptographic operations. The queue is used to manage the execution of cryptographic operations in a non-blocking manner, allowing multiple operations to be executed concurrently. The library provides a set of APIs for various cryptographic operations, including symmetric encryption, hashing, and public key cryptography.

Note

Enqueue and dequeue operations on a queue must not be executed concurrently by different threads.
Only 2048, 4096 and 8192 queue depths are supported.

6.2. Features

6.2.1. Asymmetric Cryptography

Algorithm	Parameters
RSA	17 - 1024 bytes
RSA	Encrypt, decrypt
RSA-CRT	34 - 1024 bytes
RSA-CRT	Encrypt, decrypt

6.2.2. Symmetric Cryptography

6.2.2.1. Ciphering Algorithms

Algorithm	Key Size
AES-CBC	128 bits
	192 bits
	256 bits

6.2.2.2. Authentication Algorithms

Algorithm	Key Size	Digest Length
SHA1	N/A	20 bytes
SHA1-HMAC	1 - 64 bytes	20 bytes

6.2.2.3. AEAD Algorithms

Algorithm	Key Size	Digest Length	IV Length	AAD Length
AES-CCM	128 bits	8 bytes	7 - 13 bytes	0 - 1024 bytes
	192 bits
	256 bits
AES-GCM	128 bits	16 bytes	12 bytes	0 - 1024 bytes
	192 bits
	256 bits

6.3. Control Plane

Liquid crypto library provides a set of APIs for configuring devices and managing queues. Queues are used to submit cryptographic operations to the hardware accelerators and retrieve the results. One device can have multiple queues, and each queue can be used to submit multiple operations.

6.3.1. Setup Device and Queues

The following sequence demonstrates how to use the Liquid Crypto Library APIs to perform cryptographic operations:

Initialize the Library:

Call the dao_liquid_crypto_init() function to initialize the library and prepare it for use.

int ret;

ret = dao_liquid_crypto_init();
if (ret != 0) {
         /* Handle initialization error */
}

Get Device Information:

Use the dao_liquid_crypto_info_get() function to retrieve information about the available devices.

struct dao_lc_info info;
int ret;

ret = dao_liquid_crypto_info_get(device_id, &info);
if (ret != 0) {
         /* Handle device info retrieval error */
}

Create a Device:

Use the dao_liquid_crypto_dev_create() function to create a cryptographic device. Up to dao_lc_info.nb_dev devices can be created.

struct dao_lc_dev_conf conf;
int ret;

ret = dao_liquid_crypto_dev_create(&conf);
if (ret < 0) {
         /* Handle device creation error */
}

Calculate Size of Segments

Use the dao_liquid_crypto_seg_size_calc() function to calculate the size of the segments required for the features to be enabled. This segment size need to be configured per queue.

struct dao_lc_feature_params feature_params;
uint16_t seg_sz;

seg_sz = dao_liquid_crypto_seg_size_calc(&params);
if (seg_sz == 0) {
         /* Handle segment size calculation error */
}

Configure Queue Pair:

Configure the queue pair for cryptographic operations using dao_liquid_crypto_qp_configure().

struct dao_lc_qp_conf qp_config;
uint8_t dev_id = 0;
uint16_t qp_id = 0;
int ret;

/* Populate the qp_config structure */
ret = dao_liquid_crypto_qp_configure(dev_id, qp_id, &qp_config);
if (ret != 0) {
         /* Handle queue pair configuration error */
}

Start the Device:
Use dao_liquid_crypto_dev_start() to start the device after configuring the queue pair. Datapath operations can be performed only after the device is started.
ret = dao_liquid_crypto_dev_start(device_id); if (ret != 0) { /* Handle device start error */ }

6.3.2. Device Teardown

Stop the Device:

Use dao_liquid_crypto_dev_stop() to stop the device when it is no longer needed.

ret = dao_liquid_crypto_dev_stop(device_id);
if (ret != 0) {
         /* Handle device stop error */
}

Destroy the Device:

Use dao_liquid_crypto_dev_destroy() to destroy the device and free any associated resources.

ret = dao_liquid_crypto_dev_destroy(device_id);
if (ret != 0) {
         /* Handle device destruction error */
}

Finalize the Library:

Call dao_liquid_crypto_fini() to finalize the library and release any resources.

ret = dao_liquid_crypto_fini();
if (ret != 0) {
         /* Handle library finalization error */
}

Note

Once the library is finalized, all resources associated with the library are released. Library functions should not be called after finalization.

6.3.3. Command Queue

The command queue is used to submit command operations to the hardware accelerators. The command queue operations are non-blocking and can be executed concurrently with the data queue operations. A queue is designated as command queue during liquid crypto device creation using dao_liquid_crypto_dev_create() by setting the ‘cmd_qp_idx’ field in the device configuration structure dao_lc_dev_conf.

Following command operations are supported

Symmetric session create (dao_liquid_crypto_sym_sess_create)
Symmetric session destroy (dao_liquid_crypto_sym_sess_destroy)

Since the operations are performed asynchronously, the user submits the operation and polls for completion event. The user can use the dao_liquid_crypto_cmd_event_dequeue API to poll for completion events.

6.4. Data Plane

All datapath operations are performed using the data queue. The data queue is used to submit cryptographic operations to the hardware accelerators. The data queue operations are non-blocking. There are multiple APIs for performing enqueue operations, while the dequeue operation is performed using a single API.

6.4.1. Enqueue API - Asymmetric Crypto

The following APIs are used to enqueue asymmetric cryptographic operations:

dao_liquid_crypto_enq_op_pkcs1v15enc : Enqueue PKCS1v15 encryption operation.
dao_liquid_crypto_enq_op_pkcs1v15dec : Enqueue PKCS1v15 decryption operation.
dao_liquid_crypto_enq_op_pkcs1v15enc_crt : Enqueue PKCS1v15 CRT encryption operation.
dao_liquid_crypto_enq_op_pkcs1v15dec_crt : Enqueue PKCS1v15 CRT decryption operation.

6.4.2. Enqueue API - Symmetric Crypto

The following API is used to enqueue symmetric cryptographic operations:

dao_liquid_crypto_sym_enqueue_burst(): Enqueue a burst of symmetric cryptographic operations.

6.4.2.1. Buffer Usage

DAO Liquid Crypto Library allows the user to provide fragmented buffers for cryptographic operations. The user can provide a list of buffers for each operation, and the library will handle the fragmentation and reassembly of the buffers internally. This allows for efficient memory usage and reduces the overhead of copying data between buffers.

Following represents the dao_lc_sym_op structure that is used to enqueue symmetric cryptographic operations:

struct dao_lc_sym_op {
	/**
	 * The cookie to be associated with the operation. This cookie is returned in the
	 * *dao_lc_res* structure when the operation is dequeued.
	 */
	uint64_t op_cookie;
	/** Session ID to be used. */
	uint64_t sess_id;
	/**
	 * Data buffer input for the operation. The memory pointed to by in_buffer must remain
	 * valid until the operation is completed and dequeued by the application using
	 * dao_liquid_crypto_dequeue_burst().
	 * */
	struct dao_lc_buf *in_buffer;
	/**
	 * Data buffer output for the operation. NULL value means in-place operation.
	 * The memory pointed to by out_buffer must remain valid until the operation is
	 * completed and dequeued by the application using dao_liquid_crypto_dequeue_burst().
	 * */
	struct dao_lc_buf *out_buffer;
	/**
	 * Starting point for cipher processing, specified as number of bytes from start of data in
	 * the input buffer. The result of the cipher operation will be written back into the
	 * output buffer starting at this location.
	 */
	uint32_t cipher_offset;
	/**
	 * Length of data to be ciphered, specified as number of bytes from the cipher_offset
	 * in the input buffer.
	 *
	 * For block ciphers, the cipher length must be aligned with the block size of the
	 * cipher type. It is the application's responsibility to ensure the cipher length
	 * meets this alignment requirement.
	 */
	uint32_t cipher_len;
	/**
	 * Starting point for auth processing, specified as number of bytes from start of data in
	 * the input buffer.
	 */
	uint32_t auth_offset;
	/**
	 * Length of data to be authenticated, specified as number of bytes from the
	 * auth_offset in the input buffer.
	 */
	uint32_t auth_len;
	/** Cipher IV */
	uint8_t *cipher_iv;
	/** Auth IV */
	uint8_t *auth_iv;
	/** AAD. Ignored for non-AEAD operations. */
	uint8_t *aad;
	/** AAD length. Ignored for non-AEAD operations. */
	uint16_t aad_len;
	/** Digest. Ignored for non auth use cases. */
	uint8_t *digest;
	/** Type of operation */
	union {
		/** Is encrypt operation or decrypt operation. */
		bool encrypt;
		/** Is auth generate or auth verify. Used in case of auth-only operations. */
		bool auth_gen;
	};
};

Data Buffers:

Pointers to the input and output data buffers for the operation are specified using dao_lc_sym_op.in_buffer (input buffer) and dao_lc_sym_op.out_buffer (output buffer). If dao_lc_sym_op.out_buffer is set to NULL, the operation is performed in-place, and the input buffer is used as both the source and destination.

Both input and output buffers can be fragmented; the library manages fragmentation and reassembly internally. Cryptographic operations are applied only to the regions of the buffer specified by the cipher and authentication offsets and lengths, not to the entire buffer.

AEAD Operations:

The dao_lc_sym_op structure supports AEAD (Authenticated Encryption with Associated Data) operations, such as AES-GCM, which perform encryption and authentication simultaneously. For AEAD operations:

cipher_offset and cipher_len specify the region of the input buffer to be encrypted and authenticated.
The aad field provides additional authenticated data that is not encrypted but is included in the authentication calculation.
The cipher_iv field supplies the initialization vector (IV) required for the cipher operation.
The digest field is used to store or verify the authentication tag (also known as the authentication digest). For encryption, the tag is generated and written to digest; for decryption, the tag in digest is verified. If digest is NULL, the authentication tag is expected to be located immediately after the ciphered data in the buffer.

The library manages all AEAD-specific processing internally, including handling of fragmented buffers and correct placement of the authentication tag.

In case of out-of-place operations, the output buffer contains the ciphered data and, if the digest field is NULL, the authentication tag as well. The input buffer remains unchanged. Ciphered data is copied to the output buffer starting from the offset defined by cipher_offset and for a length of cipher_len.

In case of in-place operations, the input buffer is overwritten with the ciphered data starting at the offset specified by cipher_offset for a length of cipher_len. If digest is NULL, the authentication tag (for encrypt operations) is written immediately after the ciphered data in the buffer. For decrypt operations, if the digest field is NULL, the authentication tag is expected to be located immediately after the ciphered data in the buffer and is used for verification.

The fields, auth_offset, auth_len, and auth_iv, are ignored for AEAD operations.

Cipher Only Operations:

The dao_lc_sym_op structure supports cipher-only operations, such as symmetric ciphering algorithms like AES-CBC. For these operations:

cipher_offset and cipher_len specify the offset and length of the data within the input buffer to be encrypted or decrypted.
cipher_iv provides the initialization vector (IV) required for the cipher operation.

In case of out-of-place operations, the output buffer contains the ciphered data, while the input buffer remains unchanged. The ciphered data is copied to the output buffer starting at the offset specified by cipher_offset and for a length of cipher_len.

In case of in-place operations, the input buffer is overwritten with the ciphered data, starting from the offset specified by cipher_offset and for a length of cipher_len.

All authentication-related fields (auth_offset, auth_len, auth_iv, aad, and digest) are ignored for cipher-only operations.

Auth Only Operations:

The dao_lc_sym_op structure supports authentication-only operations, such as hashing algorithms like SHA1. For these operations, the auth_offset and auth_len fields specify the offset and length of the data to be authenticated within the input buffer.

auth_offset and auth_len specify the region of the input buffer to be authenticated.
auth_iv provides the initialization vector (IV) required for the authentication operation. This field is optional and should be set only if the authentication algorithm requires an IV.
digest is used to store the generated authentication tag (for auth_gen operations) or to provide the tag to be verified (for auth_verify operations). The digest field must always be set (not NULL) for authentication-only operations.

In authentication-only operations, the out_buffer field is not used. The input buffer is not modified, and the authentication tag is written to the digest field.

All cipher and AEAD-related fields (cipher_offset, cipher_len, cipher_iv, and aad) are ignored for authentication-only operations.

Cipher and Auth Operations:

The dao_lc_sym_op structure supports combined cipher and authentication operations, such as AES-CBC with SHA1-HMAC. These are often called “chained” operations, where both ciphering and authentication are performed on specified regions of the input buffer. The order of operations (encrypt-then-authenticate or authenticate-then-encrypt) is determined by the session configuration. In these operations, both ciphering and authentication are applied to specified regions of the input buffer, as defined by:

cipher_offset and cipher_len: Offset and length of the data to be encrypted or decrypted.
auth_offset and auth_len: Offset and length of the data to be authenticated.
cipher_iv: Initialization vector for the cipher operation.
auth_iv: Initialization vector for the authentication operation (if required).
digest: Pointer to the authentication tag (for encrypt/auth_gen) or the tag to be verified (for decrypt/auth_verify).

The library manages the sequencing and data flow, ensuring that cipher and authentication steps are performed in the correct order as specified in the session configuration. Both in-place and out-of-place buffer modes are supported. Handling of the authentication tag (digest) follows the same rules as described for other operation types.

If the digest field is NULL, the authentication tag is expected to be located immediately after the ciphered data in the buffer. If digest is not NULL, the authentication tag is generated and stored in the digest field (for encrypt/auth_gen operations) or verified against the digest field (for decrypt/auth_verify operations), regardless of whether the operation is in-place or out-of-place.

For out-of-place operations, the output buffer contains the ciphered and/or authenticated data, and, if digest is NULL, the authentication tag as well. The input buffer remains unchanged. Ciphered data is copied to the output buffer starting at cipher_offset for cipher_len bytes. Authenticated data is copied to the output buffer starting at auth_offset for auth_len bytes.

For in-place operations, the input buffer is overwritten with the ciphered data starting at cipher_offset for cipher_len bytes, followed by the authentication tag if digest is NULL.

Summary of Fields:

The following table summarizes the fields in the dao_lc_sym_op structure and their applicability for different types of operations:

Field	Description	AEAD	Cipher only	Auth only	Cipher-Auth
`cipher_offset`	Cipher Offset	R	R	NA	R
`cipher_len`	Cipher Length	R	R	NA	R
`auth_offset`	Authentication Offset	NA	NA	R	R
`auth_len`	Authentication Length	NA	NA	R	R
`cipher_iv`	Cipher IV	R	R	NA	R
`auth_iv`	Authentication IV	NA	NA	O	O
`aad`	Additional Authentication Data	O	NA	NA	NA
`digest`	Digest	O	NA	R	O

Note

R: Required field for the operation.
O: Optional field for the operation.
NA: Not applicable for the operation.

6.4.3. Dequeue API

The following API is used to dequeue liquid crypto operations:

dao_liquid_crypto_dequeue_burst(): Dequeue a burst of liquid crypto operations.

6.5. Known Limitations

If the device is stopped & started without doing a device teardown (fini), then invalid results can be received.