[RFC v3] virtio-crypto specification

["Gonglei (Arei)" <arei.gonglei@huawei.com>]

Hi all,

This is the specification (version 3) about a new virtio crypto device. 

Changes from v2:
 - Reserve virtio device ID 20 for crypto device. [Cornelia]
 - Drop all feature bits, those capabilities are offered by the device all the time.  [Stefan & Cornelia]
 - Add a new section 1.4.2 for driver requirements. [Stefan]
 - Use definite type definition instead of enum type in some structure. [Stefan]
 - Add virtio_crypto_cipher_alg definition. [Stefan]
 - Add a "Device requirements" section as using MUST. [Stefan]
 - Some grammar nits fixes and typo fixes. [Stefan & Cornelia]
 - Add one VIRTIO_CRYPTO_S_STARTED status for the driver as the flag of virtio-crypto device started and can work now.

Great thanks for Stefan and Cornelia!

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

TODO:
 - Add RSA asymmetric algorithm description
 - Finish the frontend driver based on the latest Linux kernel


If you have any comments, please let me know, thanks :)


Regards,
-Gonglei

Virtio-crypto device Spec
                  Signed-off-by: Gonglei <arei.gonglei@huawei.com>

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. The second queue is the control queue, which is used to create or destroy session for symmetric algorithms, and to control some advanced features in the future.

1.1	Device ID
20

1.2	Virtqueues
0  dataq
…
N-1  dataq
N  controlq

N is set by max_virtqueues (max_virtqueues >= 1).

1.3	Feature bits
There are no feature bits (yet).

1.4	Device configuration layout
Three driver-read-only configuration fields are currently defined. One read-only bit (for the device) is currently defined for the status field: VIRTIO_CRYPTO_S_HW_READY. One read-only bit (for the driver) is currently defined for the status field: VIRTIO_CRYPTO_S_STARTED.
#define VIRTIO_CRYPTO_S_HW_READY  (1 << 0)
#define VIRTIO_CRYPTO_S_STARTED  (1 << 1)

The following driver-read-only field, max_virtqueues specifies the maximum number of data virtqueues (dataq1. . .dataqN) .
struct virtio_crypto_config {
	le16 status;
    le16 max_virtqueues;
    le32 algorithms;
}

The last driver-read-only field, algorithms specifies the algorithms which the device offered. 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_ASYM  (1 << 1)

1.4.1	Device Requirements: Device configuration layout
The device MUST set max_virtqueues to between 1 and 65535 inclusive.

The device SHOULD set status according to the status of the hardware-backed implementation.

The device MUST set algorithms according to the algorithms which the device offered.

1.4.2	Driver Requirements: Device configuration layout
The driver MUST read the ready status from the bottom bit of status to check whether the hardware-backed implementation is ready or not.
The driver MUST read the algorithms to discover the algorithms which the device supports.

1.5	Device Initialization
A driver would perform a typical initialization routine like so:
1. Identify and initialize data virtqueue, up to max_virtqueues.
2. Identify the control virtqueue.
3. Identify the ready status of hardware-backend comes from the bottom bit of status.
4. Read the supported algorithms from bits of algorithms. 

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 Driver Requirements: Session operation
The driver MUST set the control type with VIRTIO_CRYPTO_CTRL_CREATE_SESSION before the request is preceded by an operation header when executing session creation:
typedef struct virtio_crypto_sym_session_op {
	u8 op_type;  /* virtio_crypto_sym_op_type_t  */
    virtio_crypto_sym_cipher_t cipher_setup_data;
    virtio_crypto_sym_hash_t hash_setup_data;
    u8 alg_chain_order;  /* virtio_crypto_sym_alg_chain_order_t */
} 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;

/* All the supported algorithms
 */
enum virtio_crypto_cipher_alg {
    /* Option to not do any cryptography */
    VIRTIO_CRYPTO_NO_CIPHER,
    VIRTIO_CRYPTO_CIPHER_DES,
    VIRTIO_CRYPTO_CIPHER_DES_CBC,
    VIRTIO_CRYPTO_CIPHER_DES3,
    VIRTIO_CRYPTO_CIPHER_DES3_CBC,
    VIRTIO_CRYPTO_CIPHER_AES,
    VIRTIO_CRYPTO_CIPHER_AES_CBC,
    VIRTIO_CRYPTO_CIPHER_KASUMI_F8,
    VIRTIO_CRYPTO_NUM_CRYPTO,
};

enum virtio_crypto_hash_alg {
    /* Option to not do any hash */
    VIRTIO_CRYPTO_NO_HASH,
    VIRTIO_CRYPTO_HASH_MD5,
    VIRTIO_CRYPTO_HASH_SHA1,
    VIRTIO_CRYPTO_HASH_SHA1_96,
    VIRTIO_CRYPTO_HASH_SHA224,
    VIRTIO_CRYPTO_HASH_SHA256,
    VIRTIO_CRYPTO_HASH_SHA384,
    VIRTIO_CRYPTO_HASH_SHA512,
    VIRTIO_CRYPTO_HASH_AES_XCBC,
    VIRTIO_CRYPTO_HASH_AES_XCBC_96,
    VIRTIO_CRYPTO_HASH_KASUMI_F9,
    VIRTIO_CRYPTO_NUM_HMAC,
};
typedef struct virtio_crypto_sym_cipher {
	/* cipher algorithm type (ie. aes-cbc ) */
    le32 alg;  /* enum virtio_crypto_cipher_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 */
    le32 hash_alg;  /* enum virtio_crypto_hash_alg */
    /* mode of hash operation, including authenticated/plain/nested hash */
    u8 hash_mode;  /* virtio_crypto_sym_hash_mode_t */
	/* 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;
The driver MUST set the control type with VIRTIO_CRYPTO_CTRL_CLOSE_SESSION and pass the session_id to the device when executing session close.

1.6.1.2 Device Requirements: Session operation
The device MUST return a session identifier to the driver when the device finishes the processing of session close. 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.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 controlq and dataq virtqueue are bidirectional.
Step1: Create a session:
1.	The driver fills out the context message, including algorithm name, key, keylen etc;
2.	The driver sends a context message to the backend device by controlq;
3.	The device creates 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 fills out the encrypt requests;
2.	Put the requests into dataq and kick the virtqueue;
3.	The device executes the encryption operation according the requests’ arguments;
4.	The device returns the encryption result to the driver by dataq;
5.	The driver callback handle the result and over.

Note: the driver MAY 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.

1.6.3.1 Device Requirements: Decryption operation
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) MUST be returned the driver.