OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

virtio-dev message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: RE: [RFC v4] virtio-crypto specification


Ping...

I'd like to know what's the process of a new virtio device can be merged? 
Anybody can tell me? Thanks a lot.

Taking Virtio-gpu as an example, the virtio-gpu had been merged in Linux kernel
And Qemu communities, but the corresponding virtio-gpu spec hadn't been merged
yet. Why was that? Am I missing some rules? Thanks. 


Regards,
-Gonglei


> -----Original Message-----
> From: Gonglei (Arei)
> Sent: Sunday, June 26, 2016 5:35 PM
> To: virtio-dev@lists.oasis-open.org; qemu-devel@nongnu.org; Gonglei (Arei)
> Cc: Hanweidong (Randy); Stefan Hajnoczi; Cornelia Huck; mst@redhat.com;
> Lingli Deng; Jani Kokkonen; Luonengjun; Huangpeng (Peter); Zhoujian (jay,
> Euler); chenshanxi 00222737; 'Ola Liljedahl@arm.com'; Varun Sethi
> Subject: [RFC v4] virtio-crypto specification
> 
> Hi all,
> 
> This is the specification (version 4) about a new virtio crypto device.
> 
> Changes from v3:
>  - Don't use enum is the spec but macros in specific structures. [Michael &
> Stefan]
>  - Add two complete structures for session creation and closing, so that
>   the spec is clear on how to lay out the request.  [Stefan]
>  - Definite the crypto operation request with assigned structure, in this way,
>   each data request only occupies *one entry* of the Vring descriptor table,
>   which *improves* the *throughput* of data transferring.
> 
> 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.
> 
> If you have any comments, please let me know, thanks :)
> 
> 
> 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:
> #define VIRTIO_CRYPTO_CTRL_CREATE_SESSION  1
> #define VIRTIO_CRYPTO_CTRL_CLOSE_SESSION  2
> 
> 1.6.1.1 Session creation operation
> A request of creating a session including the following information:
> struct virtio_crypto_sym_session_creation {
> 	struct virtio_crypto_sym_ctlhdr   ctlhdr;  /* OUT */
> 	struct virtio_crypto_sym_session_op  session_op;  /* OUT */
> 	struct virtio_crypto_sym_session_op_inhdr  inhdr;  /* IN */
> };
> The details of specific structure, including struct virtio_crypto_sym_session_op
> and struct virtio_crypto_sym_session_op_inhdr  are defined by the following
> sections.
> 1.6.1.1.1 Driver Requirements: Session creation 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 {
> /**< No operation */
> #define VIRTIO_CRYPTO_SYM_OP_NONE    0
> /**< Cipher only operation on the data */
> #define VIRTIO_CRYPTO_SYM_OP_CIPHER    1
> /**< Hash only operation on the data */
> #define VIRTIO_CRYPTO_SYM_OP_HASH     2
> /**< Chain any cipher with any hash operation */
> #define VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING    3
> 	u8 op_type; /* Operation type */
>     virtio_crypto_sym_cipher_t cipher_setup_data;
> 	virtio_crypto_sym_hash_t hash_setup_data;
> /* Perform the hash operation followed by the cipher operation */
> #define VIRTIO_CRYPTO_SYM_ALG_CHAIN_ORDER_HASH_THEN_CIPHER
> 	1
> /* Perform the cipher operation followed by the hash operation */
> #define VIRTIO_CRYPTO_SYM_ALG_CHAIN_ORDER_CIPHER_THEN_HASH
> 	2
>     u8 alg_chain_order;
> } virtio_crypto_sym_session_op_t;
> And the structures definition details are:
> 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 {
> /* Option to not do any cryptography */
> #define VIRTIO_CRYPTO_NO_CIPHER	0
> #define VIRTIO_CRYPTO_CIPHER_DES	1
> #define VIRTIO_CRYPTO_CIPHER_DES_CBC	2
> #define VIRTIO_CRYPTO_CIPHER_DES3	3
> #define VIRTIO_CRYPTO_CIPHER_DES3_CBC	4
> #define VIRTIO_CRYPTO_CIPHER_AES	5
> #define VIRTIO_CRYPTO_CIPHER_AES_CBC	6
> #define VIRTIO_CRYPTO_CIPHER_KASUMI_F8	7
>     le32 alg;  /* cipher algorithm type (ie. aes-cbc ) */
>     /* length of key */
>     le32 keylen;
> #define VIRTIO_CRYPTO_DECRYPT	0
> #define VIRTIO_CRYPTO_ENCRYPT	1
> 	u8 op; /* encrypt or decrypt */
> } virtio_crypto_sym_cipher_t;
> 
> typedef struct virtio_crypto_sym_hash {
> /* Option to not do any hash */
> #define VIRTIO_CRYPTO_NO_HASH	0
> #define VIRTIO_CRYPTO_HASH_MD5	1
> #define VIRTIO_CRYPTO_HASH_SHA1	2
> #define VIRTIO_CRYPTO_HASH_SHA1_96	3
> #define VIRTIO_CRYPTO_HASH_SHA224	4
> #define VIRTIO_CRYPTO_HASH_SHA256	5
> #define VIRTIO_CRYPTO_HASH_SHA384	6
> #define VIRTIO_CRYPTO_HASH_SHA512	7
> #define VIRTIO_CRYPTO_HASH_AES_XCBC	   8
> #define VIRTIO_CRYPTO_HASH_AES_XCBC_96  9
> #define VIRTIO_CRYPTO_HASH_KASUMI_F9	10
>     le32 hash_alg;  /* hash algorithm type */
> #define VIRTIO_CRYPTO_SYM_HASH_MODE_PLAIN	1
> #define VIRTIO_CRYPTO_SYM_HASH_MODE_AUTH	2
> #define VIRTIO_CRYPTO_SYM_HASH_MODE_NESTED	3
> u8 hash_mode; /* mode of hash operation, including
> authenticated/plain/nested hash */
> 	/* hash result length */
>     le32 hash_result_len;
>     virtio_crypto_sym_hash_auth_mode_t auth_mode_setup_data;
> } virtio_crypto_sym_hash_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.1.2 Device Requirements: Session creation 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.
> #define VIRTIO_CRYPTO_CTRL_OK	0
> #define VIRTIO_CRYPTO_CTRL_ERR	1
> 1.6.1.2 Session closing operation
> A request of closing a session including the following information:
> struct virtio_crypto_sym_session_creation {
> 	struct virtio_crypto_sym_ctlhdr   ctlhdr;  /* OUT */
> 	le64  session_id;  /* OUT */
> 	u8 status;  /* IN */
> };
> 1.6.1.2.1 Driver Requirements: Session closing operation
> The driver MUST set the control type with
> VIRTIO_CRYPTO_CTRL_CLOSE_SESSION, and the session_id MUST be a valid
> value which assigned by the device when a session was created.
> 1.6.1.2.2 Device Requirements: Session closing operation
> Status is written by the device: either VIRTIO_CRYPTO_CTRL_OK for success,
> VIRTIO_CRYPTO_CTRL_ERR for creation failed or device error.
> #define VIRTIO_CRYPTO_CTRL_OK	0
> #define VIRTIO_CRYPTO_CTRL_ERR	1
> 1.6.2	Encryption operation
> 1.6.2.1 Driver Requirements: 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:
> struct virtio_crypto_sym_op_hdr {
> 	/* 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;
> } ;
> The encryption request MUST end by a tailer:
> typedef struct virtio_crypto_sym_op_inhdr {
> 	u8     status;
> } virtio_crypto_sym _op_inhdr_t;
> The specific content of symmetric algorithms requests SHOULD be same as
> below:
> struct virtio_crypto_sym_op_data {
> 	struct virtio_crypto_sym_op_hdr  hdr_info;
> 	le64 iv_addr; /* iv guest address */
> 	le64 auth_data_addr; /* associated data guest address */
> 	le64 src_data_addr; /* source data guest address */
> 	le64 dst_data_addr; /* destination data guest address */
> 	le64 digest_result_addr; /* digest result guest address */
> 	le64 inhdr_addr; /* in-header guest address */
> };
> In this way, each data request only occupies one entry of the Vring descriptor
> table, which improves the throughput of data transferring.
> 1.6.2.2 Device Requirements: Encryption operation
> The struct virtio_crypto_sym_op_inhdr’s 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.3 Steps of encryption Operation
> 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.
> 
> Regards,
> -Gonglei
> 
> 
> 



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]