5. 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.

5.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.

5.2. Features

5.2.1. Asymmetric Cryptography

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

5.2.2. Symmetric Cryptography

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

5.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.

5.3.1. Setup Device and Queues

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

1. 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 */
   }
   

2. 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 */
   }
   

3. 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 */
   }
   

4. 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 */
   }
   

4. 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 */
   }
   

5. 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 */
   }
   

5.3.2. Device Teardown

1. 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 */
   }
   

2. 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 */
   }
   

3. 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.

5.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

1. Symmetric session create (dao_liquid_crypto_sym_sess_create)

2. 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.

5.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.

5.4.1. Enqueue API - Asymmetric Crypto

The following APIs are used to enqueue asymmetric cryptographic operations:

1. dao_liquid_crypto_enq_op_pkcs1v15enc : Enqueue PKCS1v15 encryption operation.

2. dao_liquid_crypto_enq_op_pkcs1v15dec : Enqueue PKCS1v15 decryption operation.

3. dao_liquid_crypto_enq_op_pkcs1v15enc_crt : Enqueue PKCS1v15 CRT encryption operation.

4. dao_liquid_crypto_enq_op_pkcs1v15dec_crt : Enqueue PKCS1v15 CRT decryption operation.

5.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.

5.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.

5.5. Known Limitations

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