[Qemu-devel] [RFC v2] virtio-crypto specification

[Gonglei (Arei)]

Dear all,

I'm so sorry for the late version 2 and appreciate the good comments came from 
Cornelia and Michael.

Changes from v1:
 - Drop the feature bit definaion for each algorithm, and using config space 
instead  [Cornelia]
 - Add multiqueue support and add corresponding feature bit
 - Update Encryption process and header defination
 - Add session opration process and add corresponding header descprition
 - Other better description in order to fit for virtio spec  [Micheael]
 - Some other trivial fixes.

TODO:
 - add RSA asymmetric algorithm descritpion

PS: I've finished a general scheme in the last year, which the performance of 
blk cipher is not well, but the performance
of RSA is much better in para-virtualization (virtio-crypto) than plain 
softwere acceleration. Now, I'm working on an
user space scheme for better performance in symmetric algorithms.


Please review and give me some feedback, thanks a lot!


Regards,
-Gonglei


                 Virtio-crypto device Spec

1       Crypto Device
The virtio crypto device is a virtual crypto device (ie. hardware crypto 
accelerator card). The encryption and decryption requests of are placed in the 
data queue, and handled by the real hardware crypto accelerators finally. A 
second queue is the control queue, which is used to create or destroy session 
for symmetric algorithms, and to control some advanced features.
1.1     Device ID
65535 (experimental)

1.2     Virtqueues
0  dataq
…
N-1  dataq
N  controlq

N=1 if VIRTIO_CRYPTO_F_MQ is not negotiated, otherwise N is set by 
max_virtqueues.

1.3     Feature bits
VIRTIO_CRYPTO_F_STATUS (0)      
    Configuration status field is available. 
VIRTIO_CRYPTO_F_MQ (1)
        Device supports multiqueue to encrypt and decrypt.
VIRTIO_CRYPTO_F_ALGS (2)
    Configuration algorithms field is available.

1.4     Device configuration layout
Three driver-read-only configuration fields are currently defined. The status 
only exists if VIRTIO_CRYPTO_F_STATUS is set. On read-only bit (for the driver) 
is currently defined for the status field: VIRTIO_CRYPTO_S_HW_READY.
#define VIRTIO_CRYPTO_S_HW_READY 1

The following driver-read-only field, max_virtqueues only exists if 
VIRTIO_CRYPTO_F_MQ is set. This field specifies the maximum number of data 
virtqueues (dataq1. . .dataqN) that can be configured once VIRTIO_CRYPTO_F_MQ 
is negotiated.
struct virtio_crypto_config {
        le16 status;
    le16 max_virtqueues;
    le32 algorithms;
}

The last driver-read-only field, algorithms only exists if VIRTIO_CRYPTO_F_ALGS 
is set. This field specifies the algorithms which the device offered once 
VIRTIO_CRYPTO_F_ALGS is negotiated. Two read-only bits (for the driver) are 
currently defined for the algorithms field: VIRTIO_CRYPTO_ALG_SYM and 
VIRTIO_CRYPTO_ALG_ASYM.
#define VIRTIO_CRYPTO_ALG_SYM  (1 << 0)
#define VIRTIO_CRYPTO_ALG_SYM  (1 << 1)
1.4.1   Device Requirements: Device configuration layout
The device MUST set max_virtqueues to between 1 and 0x8000 inclusive, if it 
offers VIRTIO_CRYPTO_F_MQ.
If the driver does not negotiate the VIRTIO_CRYPTO_F_STATUS feature, it SHOULD 
assume the hardware-backed implementation is ready, otherwise it SHOULD read 
the ready status from the bottom bit of status.
If the driver does not negotiate the VIRTIO_CRYPTO_F_ALGS feature, it SHOULD 
assume the
device support all algorithms.
1.5     Device Initialization
A driver would perform a typical initialization routine like so:
1. Identify and initialize data virtqueue, up to N if VIRTIO_CRYPTO_F_MQ 
feature bit is negotiated, N=max_virtqueues, otherwise identify N=1.
2. Identify the control virtqueue.
3. If the VIRTIO_CRYPTO_F_STATUS feature bit is negotiated, the ready status of 
hardware-backend comes from the bottom bit of status. Otherwise, the driver 
assumes it’s active.
4. If the VIRTIO_CRYPTO_F_ALGS feature bit is negotiated, the driver can read 
the supported algorithms from bits of algorithms. Otherwise, the driver assumes 
all algorithms are supported.
1.6     Device Operation
1.6.1   Session operation
The symmetric algorithms have the concept of sessions. A session is a handle 
which describes the
cryptographic parameters to be applied to a number of buffers. The data within 
a session handle includes the following:
•1. The operation (cipher, hash or both, and if both, the order in which the 
algorithms should be applied).
•2. The cipher setup data, including the cipher algorithm and mode, the key and 
its length, and the direction (encrypt or decrypt).
•3. The hash setup data, including the hash algorithm, mode (plain, nested or 
authenticated), and digest result length (to allow for truncation).
        Authenticated mode can refer to HMAC, which requires that the key and 
its length are also specified. It is also used for GCM and CCM authenticated 
encryption, in which case the AAD length is also specified.
        For nested mode, the inner and outer prefix data and length are 
specified, as well as the outer hash algorithm.

The controlq virtqueue is used to control session operations, including 
creation or close. The request is preceded by a header:
struct virtio_crypto_sym_ctlhdr {
    /* control type  */
    u8 type;
};
Two bits are currently defined for the control header type: 
enum virto_crypto_ctl_type {
    VIRTIO_CRYPTO_CTRL_CREATE_SESSION = 1,
    VIRTIO_CRYPTO_CTRL_CLOSE_SESSION = 2,
};

1.6.1.1 Session creation
Firstly, the session creation request MUST be set the control type with 
VIRTIO_CRYPTO_CTRL_CREATE_SESSION, then the request is preceded by an operation 
header:
typedef struct virtio_crypto_sym_session_op {
        virtio_crypto_sym_op_type_t op_type;
    virtio_crypto_sym_cipher_t cipher_setup_data;
    virtio_crypto_sym_hash_t hash_setup_data;
    virtio_crypto_sym_alg_chain_order_t alg_chain_order;
    u8 verify_digest;
} virtio_crypto_sym_session_op_t;

And the structures definition details are:

typedef enum virtio_crypto_sym_op_type
{
    VIRTIO_CRYPTO_SYM_OP_NONE = 0,
    /**< No operation */
    VIRTIO_CRYPTO_SYM_OP_CIPHER,
    /**< Cipher only operation on the data */
    VIRTIO_CRYPTO_SYM_OP_HASH,
    /**< Hash only operation on the data */
    VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING
    /**< Chain any cipher with any hash operation. The order depends on
     * the value in the CpaCySymAlgChainOrder enum.
     *
     * This value is also used for authenticated ciphers (GCM and CCM), in
     * which case the cipherAlgorithm should take one of the values @ref
     * CPA_CY_SYM_CIPHER_AES_CCM or @ref CPA_CY_SYM_CIPHER_AES_GCM, while the
     * hashAlgorithm should take the corresponding value @ref
     * CPA_CY_SYM_HASH_AES_CCM or @ref CPA_CY_SYM_HASH_AES_GCM.
     */
} virtio_crypto_sym_op_type_t;

typedef enum virtio_crypto_sym_hash_mode
{
    VIRTIO_CRYPTO_SYM_HASH_MODE_PLAIN = 1,
    /**< Plain hash.  Can be specified for MD5 and the SHA family of
     * hash algorithms. */
    VIRTIO_CRYPTO_SYM_HASH_MODE_AUTH,
    /**< Authenticated hash.  This mode may be used in conjunction with the
     * MD5 and SHA family of algorithms to specify HMAC.  It MUST also be
     * specified with all of the remaining algorithms, all of which are in
     * fact authentication algorithms.
     */
    VIRTIO_CRYPTO_SYM_HASH_MODE_NESTED
    /**< Nested hash.  Can be specified for MD5 and the SHA family of
     * hash algorithms. */
} virtio_crypto_sym_hash_mode_t;

typedef struct virtio_crypto_sym_hash_auth_mode {
        /* length of authenticated key */
        le32 auth_key_len;
        /* The length of the additional authenticated data (AAD) in bytes */
        le32 aad_len;
} virtio_crypto_sym_hash_auth_mode_t;

typedef struct virtio_crypto_sym_cipher {
        /* cipher algorithm type (ie. aes-cbc ) */
    enum virtio_crypto_cipher_alg alg;
    /* length of key */
    le32 keylen;
    /* encrypt or decrypt */
    u8 op;
} virtio_crypto_sym_cipher_t;

typedef struct virtio_crypto_sym_hash {
        /* hash algorithm type */
    enum virtio_crypto_hash_alg hash_alg;
    /* mode of hash operation, including authenticated/plain/nested hash */
    virtio_crypto_sym_hash_mode_t hash_mode;
        /* hash result length */
    le32 hash_result_len;
    virtio_crypto_sym_hash_auth_mode_t auth_mode_setup_data;
} virtio_crypto_sym_hash_t;

typedef enum virtio_crypto_sym_alg_chain_order {
        /* Perform the hash operation followed by the cipher operation */
    VIRTIO_CRYPTO_SYM_ALG_CHAIN_ORDER_HASH_THEN_CIPHER = 1,
    /* Perform the cipher operation followed by the hash operation */
    VIRTIO_CRYPTO_SYM_ALG_CHAIN_ORDER_CIPHER_THEN_HASH
} virtio_crypto_sym_alg_chain_order_t;
When the device finish the processing of session close, the device MUST return 
a session identifier to the driver. So the session creation request MUST end by 
a tailer:
typedef struct virtio_crypto_sym_session_op_inhdr {
        u8     status;
        le64    session_id;
} virtio_crypto_sym_session_op_inhdr_t;
Both status and session_id are written by the device: either 
VIRTIO_CRYPTO_CTRL_OK for success, VIRTIO_CRYPTO_CTRL_ERR for creation failed 
or device error.
enum {
    VIRTIO_CRYPTO_CTRL_OK = 0,
    VIRTIO_CRYPTO_CTRL_ERR = 1,
};

1.6.1.2 Session close
The session close request MUST be set the control type with 
VIRTIO_CRYPTO_CTRL_CLOSE_SESSION and pass the session_id to the device.
1.6.2   Encryption operation
The encryption and decryption requests and the corresponding results are 
transmitted by placing them in dataq. The symmetric algorithms requests are 
preceded by a header:
typedef struct virtio_crypto_sym_crypt_op {
        /* the backend returned session identifier */
        le64 session_id;
    /* length of initial vector */
        le32 iv_len;
        /* iv offset in the whole crypto data memory */
        le32 iv_offset;
        /* length of additional auth data */
        le32 auth_len;
        /* additional auth data offset in the whole crypto data memory */
        le32 additional_auth_offset;
        /* cipher start source offest */
        le32 cipher_start_src_offset;
        le32 len_to_cipher;
        /* hash start source offest */
        le32 hash_start_src_offset;
        le32 len_to_hash;
        /* length of source data */
        le32 source_len;
} virtio_crypto_sym_crypt_op_t;

The data requests end by a status byte. The final status byte is written by the 
device: either VIRTIO_CRYPTO_S_OK for success, VIRTIO_CRYPTO_S_ERR for device 
or driver error, VIRTIO_CRYPTO_S_BADMSG for verification failed when decrypt 
AEAD algorithms:
#define VIRTIO_CRYPTO_S_OK    0
#define VIRTIO_CRYPTO_S_ERR    1
#define VIRTIO_CRYPTO_S_BADMSG    2

1.6.2.1 Steps of encryption Operation
Both ctrlq and dataq virtqueue are bidirectional.
Step1: Create a session:
1.      The driver fill out the context message, include algorithm name, key, 
keylen etc;
2.      The driver send a context message to the backend device by controlq;
3.      The device create a session using the message transmitted by controlq;
4.      Return the session id to the driver. 
Step 2: Execute the detail encryption operation:
1.      The driver fill out the encrypt requests;
2.      Put the requests into dataq and kick the virtqueue;
3.      The device execute the encryption operation according the requests’ 
arguments;
4.      The device return the encryption result to the driver by dataq;
5.      The driver callback handle the result and over.

Note: the driver CAN support both synchronous and asynchronous encryption. Then 
the performance is poor in synchronous operation because frequent context 
switching and virtualization overhead. The driver SHOULD by preference use 
asynchronous encryption.
1.6.3   Decryption Operation
The decryption process is the same with encryption, except that the device MUST 
verify and return the verify result to the driver. If the verify result is not 
correct, VIRTIO_CRYPTO_S_BADMSG (bad message) SHOULD be returned the driver.

virtio-crypto-spec v2.docx
Description: virtio-crypto-spec v2.docx