[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Request vote for the patch: Add virtio rpmb device specification
Fixes: https://github.com/oasis-tcs/virtio-spec/issues/53 Request vote at this time. > -----Original Message----- > From: Michael S. Tsirkin <mst@redhat.com> > Sent: Sunday, October 27, 2019 19:48 > To: Huang, Yang <yang.huang@intel.com> > Cc: virtio-dev@lists.oasis-open.org; cohuck@redhat.com; Zhu, Bing > <bing.zhu@intel.com>; Winkler, Tomas <tomas.winkler@intel.com>; Fang, > Peter <peter.fang@intel.com> > Subject: Re: [virtio-dev] [PATCH v6] Add virtio rpmb device specification > > On Wed, Oct 09, 2019 at 10:36:51AM +0800, Huang Yang wrote: > > It is a virtio based RPMB (Replay Protected Memory Block) device. > > > > Signed-off-by: Yang Huang <yang.huang@intel.com> > > Reviewed-by: Bing Zhu <bing.zhu@intel.com> > > Reviewed-by: Tomas Winkler <tomas.winkler@intel.com> > > > > v5 -> v6: > > 1. Remove UFS reference, keep eMMC as the only one. > > 2. Update eMMC reference link to a free version. > > 3. Typo fixes. > > 4. Copy normative statements to the normative sections, > > and rewrite text to Device Operation section. > > 5. Update conformance. > > Looks reasonable at this point. Feel free to create a github issue and request a > vote as documented here: > https://github.com/oasis-tcs/virtio-spec/README.md > see section "use of github issues". > > > --- > > conformance.tex | 24 ++++- > > content.tex | 1 + > > introduction.tex | 3 + > > virtio-rpmb.tex | 289 > > +++++++++++++++++++++++++++++++++++++++++++++++++++++++ > > 4 files changed, 316 insertions(+), 1 deletion(-) create mode 100644 > > virtio-rpmb.tex > > > > diff --git a/conformance.tex b/conformance.tex index 0ac58aa..50969e5 > > 100644 > > --- a/conformance.tex > > +++ b/conformance.tex > > @@ -22,7 +22,7 @@ \section{Conformance Targets}\label{sec:Conformance > / Conformance Targets} > > \begin{itemize} > > \item Clause \ref{sec:Conformance / Device Conformance}. > > \item One of clauses \ref{sec:Conformance / Device Conformance / PCI > Device Conformance}, \ref{sec:Conformance / Device Conformance / MMIO > Device Conformance} or \ref{sec:Conformance / Device Conformance / Channel > I/O Device Conformance}. > > - \item One of clauses \ref{sec:Conformance / Device Conformance / > Network Device Conformance}, \ref{sec:Conformance / Device Conformance / > Block Device Conformance}, \ref{sec:Conformance / Device Conformance / > Console Device Conformance}, \ref{sec:Conformance / Device Conformance / > Entropy Device Conformance}, \ref{sec:Conformance / Device Conformance / > Traditional Memory Balloon Device Conformance}, \ref{sec:Conformance / > Device Conformance / SCSI Host Device Conformance}, \ref{sec:Conformance / > Device Conformance / Input Device Conformance}, \ref{sec:Conformance / > Device Conformance / Crypto Device Conformance} or \ref{sec:Conformance / > Device Conformance / Socket Device Conformance}. > > + \item One of clauses \ref{sec:Conformance / Device Conformance / > Network Device Conformance}, \ref{sec:Conformance / Device Conformance / > Block Device Conformance}, \ref{sec:Conformance / Device Conformance / > Console Device Conformance}, \ref{sec:Conformance / Device Conformance / > Entropy Device Conformance}, \ref{sec:Conformance / Device Conformance / > Traditional Memory Balloon Device Conformance}, \ref{sec:Conformance / > Device Conformance / SCSI Host Device Conformance}, \ref{sec:Conformance / > Device Conformance / Input Device Conformance}, \ref{sec:Conformance / > Device Conformance / Crypto Device Conformance}, \ref{sec:Conformance / > Device Conformance / Socket Device Conformance} or \ref{sec:Conformance / > Device Conformance / RPMB Device Conformance}. > > \item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device > and Transitional Driver Conformance}. > > \end{itemize} > > \end{description} > > @@ -183,6 +183,14 @@ \section{Conformance > > Targets}\label{sec:Conformance / Conformance Targets} \item > > \ref{drivernormative:Device Types / Socket Device / Device Operation / > > Device Events} \end{itemize} > > > > +\conformance{\subsection}{RPMB Driver > > +Conformance}\label{sec:Conformance / Driver Conformance / RPMB Driver > > +Conformance} > > + > > +A RPMB driver MUST conform to the following normative statements: > > + > > +\begin{itemize} > > +\item \ref{drivernormative:Device Types / RPMB Device / Device > > +Operation} \end{itemize} > > + > > \conformance{\section}{Device Conformance}\label{sec:Conformance / > > Device Conformance} > > > > A device MUST conform to the following normative statements: > > @@ -338,6 +346,20 @@ \section{Conformance > > Targets}\label{sec:Conformance / Conformance Targets} \item > > \ref{devicenormative:Device Types / Socket Device / Device Operation / > > Receive and Transmit} \end{itemize} > > > > +\conformance{\subsection}{RPMB Device > > +Conformance}\label{sec:Conformance / Device Conformance / RPMB Device > > +Conformance} > > + > > +An RPMB device MUST conform to the following normative statements: > > + > > +\begin{itemize} > > +\item \ref{devicenormative:Device Types / RPMB Device / Device > > +Initialization} \item \ref{devicenormative:Device Types / RPMB Device > > +/ Device Operation / Device Operation: Program Key} \item > > +\ref{devicenormative:Device Types / RPMB Device / Device Operation / > > +Device Operation: Get Write Counter} \item > > +\ref{devicenormative:Device Types / RPMB Device / Device Operation / > > +Device Operation: Data Write} \item \ref{devicenormative:Device Types > > +/ RPMB Device / Device Operation / Device Operation: Data Read} \item > > +\ref{devicenormative:Device Types / RPMB Device / Device Operation / > > +Device Operation: Result Read} \item \ref{devicenormative:Device > > +Types / RPMB Device / Device Operation} \end{itemize} > > + > > \conformance{\section}{Legacy Interface: Transitional Device and > > Transitional Driver Conformance}\label{sec:Conformance / Legacy > > Interface: Transitional Device and Transitional Driver Conformance} A > > conformant implementation MUST be either transitional or > > non-transitional, see \ref{intro:Legacy diff --git a/content.tex > > b/content.tex index ee0d7c9..2573bd5 100644 > > --- a/content.tex > > +++ b/content.tex > > @@ -5677,6 +5677,7 @@ \subsubsection{Legacy Interface: Framing > > Requirements}\label{sec:Device \input{virtio-input.tex} > > \input{virtio-crypto.tex} \input{virtio-vsock.tex} > > +\input{virtio-rpmb.tex} > > > > \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits} > > > > diff --git a/introduction.tex b/introduction.tex index > > c96acf9..3453657 100644 > > --- a/introduction.tex > > +++ b/introduction.tex > > @@ -60,6 +60,9 @@ \section{Normative References}\label{sec:Normative > References} > > \phantomsection\label{intro:SCSI MMC}\textbf{[SCSI MMC]} & > > SCSI Multimedia Commands, > > > > \newline\url{http://www.t10.org/cgi-bin/ac.pl?t=f&f=mmc6r00.pdf}\\ > > + \phantomsection\label{intro:eMMC}\textbf{[eMMC]} & > > + eMMC Electrical Standard (5.1), JESD84-B51, > > + > > + \newline\url{http://www.jedec.org/sites/default/files/docs/JESD84-B5 > > + 1.pdf}\\ > > > > \end{longtable} > > > > diff --git a/virtio-rpmb.tex b/virtio-rpmb.tex new file mode 100644 > > index 0000000..9aa8c68 > > --- /dev/null > > +++ b/virtio-rpmb.tex > > @@ -0,0 +1,289 @@ > > +\section{RPMB Device}\label{sec:Device Types / RPMB Device} > > + > > +virtio-rpmb is a virtio based RPMB (Replay Protected Memory Block) > > +device. It is used as a tamper-resistant and anti-replay storage. > > +The device is driven via requests including read, write, get write > > +counter and program key, which are submitted via a request queue. > > +This section relies on definitions from paragraph 6.6.22 of > > +\hyperref[intro:eMMC]{eMMC}. > > +\subsection{Device ID}\label{sec:Device Types / RPMB Device / Device > > +ID} > > + > > +28 > > + > > +\subsection{Virtqueues}\label{sec:Device Types / RPMB Device / > > +Virtqueues} > > + > > +\begin{description} > > +\item[0] requestq > > +\end{description} > > + > > +\subsection{Feature bits}\label{sec:Device Types / RPMB Device / > > +Feature bits} > > + > > +None. > > + > > +\subsection{Device configuration layout}\label{sec:Device Types / > > +RPMB Device / Device configuration layout} > > + > > +All fields of this configuration are always available and read-only for the > driver. > > + > > +\begin{lstlisting} > > +struct virtio_rpmb_config { > > + u8 capacity; > > + u8 max_wr_cnt; > > + u8 max_rd_cnt; > > +} > > +\end{lstlisting} > > + > > +\begin{description} > > +\item[\field{capacity}] is the capacity of the device (expressed in 128KB units). > > + The values MUST range between 0x00 and 0x80 inclusive. > > +\item[\field{max_wr_cnt and max_rd_cnt}] are the maximum numbers of > RPMB > > + block count (256B) that can be performed to device in one request. 0 > implies > > + no limitation. > > +\end{description} > > + > > +\devicenormative{\subsection}{Device Initialization}{Device Types / > > +RPMB Device / Device Initialization} > > + > > +\begin{enumerate} > > +\item The virtqueue is initialized. > > +\item The device capacity MUST be initialized to a multiple of 128Kbytes and > up to > > + 16Mbytes. > > +\end{enumerate} > > + > > +\subsection{Device Operation}\label{sec:Device Types / RPMB Device / > > +Device Operation} > > + > > +The operation of a virtio RPMB device is driven by the requests placed on the > virtqueue. > > + The type of request can be program key > > +(VIRTIO_RPMB_REQ_PROGRAM_KEY), > > + get write counter (VIRTIO_RPMB_REQ_GET_WRITE_COUNTER), > > + write (VIRTIO_RPMB_REQ_DATA_WRITE), and read > (VIRTIO_RPMB_REQ_DATA_READ). > > + A program key or write request can also combine with a > > + result read (VIRTIO_RPMB_REQ_RESULT_READ) for a returned result. > > + > > +\begin{lstlisting} > > +/* RPMB Request Types */ > > +#define VIRTIO_RPMB_REQ_PROGRAM_KEY 0x0001 > > +#define VIRTIO_RPMB_REQ_GET_WRITE_COUNTER 0x0002 > > +#define VIRTIO_RPMB_REQ_DATA_WRITE 0x0003 > > +#define VIRTIO_RPMB_REQ_DATA_READ 0x0004 > > +#define VIRTIO_RPMB_REQ_RESULT_READ 0x0005 > > + > > +/* RPMB Response Types */ > > +#define VIRTIO_RPMB_RESP_PROGRAM_KEY 0x0100 > > +#define VIRTIO_RPMB_RESP_GET_COUNTER 0x0200 > > +#define VIRTIO_RPMB_RESP_DATA_WRITE 0x0300 > > +#define VIRTIO_RPMB_RESP_DATA_READ 0x0400 > > +\end{lstlisting} > > + > > +\begin{description} > > +\item[\field{VIRTIO_RPMB_REQ_PROGRAM_KEY}] requests for > authentication key programming. > > + If VIRTIO_RPMB_REQ_RESULT_READ is requested, the device returns the > > +RPMB frame with > > + the response (VIRTIO_RPMB_RESP_PROGRAM_KEY), the calculated MAC > and the result. > > + > > +\item[\field{VIRTIO_RPMB_REQ_GET_WRITE_COUNTER}] requests for > reading the write counter. > > + The device returns the RPMB frame with the response > (VIRTIO_RPMB_RESP_GET_COUNTER), > > + the writer counter, a copy of the nonce received in the request, the > calculated > > + MAC and the result. > > + > > +\item[\field{VIRTIO_RPMB_REQ_DATA_WRITE}] requests for authenticated > data write. > > + If VIRTIO_RPMB_REQ_RESULT_READ is requested, the device returns the > RPMB data > > + frame with the response (VIRTIO_RPMB_RESP_DATA_WRITE), the > incremented counter value, > > + the data address, the calculated MAC and the result. > > + > > +\item[\field{VIRTIO_RPMB_REQ_DATA_READ}] requests for authenticated > data read. > > + The device returns the RPMB frame with the response > (VIRTIO_RPMB_RESP_DATA_READ), > > + the block count, a copy of the nonce received in the request, the address, > > + the data, the calculated MAC and the result. > > + > > +\item[\field{VIRTIO_RPMB_REQ_RESULT_READ}] requests for a returned > result. > > + It is used following with VIRTIO_RPMB_REQ_PROGRAM_KEY or > VIRTIO_RPMB_REQ_DATA_WRITE > > + request types for a returned result in one or multiple RPMB frames. If it's > not > > + requested, the device will not return result frame to the driver. > > +\end{description} > > + > > + > > +\subsubsection{Device Operation: Request Queue}\label{sec:Device > > +Types / RPMB Device / Device Operation / Device Operation: Request > > +Queue} > > + > > +The request information is delivered in RPMB frame. > > +The frame is in size of 512B. > > + > > +\begin{lstlisting} > > +struct virtio_rpmb_frame { > > + u8 stuff[196]; > > + u8 key_mac[32]; > > + u8 data[256]; > > + u8 nonce[16]; > > + be32 write_counter; > > + be16 address; > > + be16 block_count; > > + be16 result; > > + be16 req_resp; > > +}; > > + > > +/* RPMB Operation Results */ > > +#define VIRTIO_RPMB_RES_OK 0x0000 > > +#define VIRTIO_RPMB_RES_GENERAL_FAILURE 0x0001 > > +#define VIRTIO_RPMB_RES_AUTH_FAILURE 0x0002 > > +#define VIRTIO_RPMB_RES_COUNT_FAILURE 0x0003 > > +#define VIRTIO_RPMB_RES_ADDR_FAILURE 0x0004 > > +#define VIRTIO_RPMB_RES_WRITE_FAILURE 0x0005 > > +#define VIRTIO_RPMB_RES_READ_FAILURE 0x0006 > > +#define VIRTIO_RPMB_RES_NO_AUTH_KEY 0x0007 > > +#define VIRTIO_RPMB_RES_WRITE_COUNTER_EXPIRED 0x0080 > > +\end{lstlisting} > > + > > +\begin{description} > > +\item[\field{stuff}] Padding for the frame. > > + > > +\item[\field{key_mac}] is the authentication key or the message > > + authentication code (MAC) depending on the request/response type. > > + If the request is VIRTIO_RPMB_REQ_PROGRAM_KEY, it's used as an > > + authentication key. Otherwise, it's used as MAC. The MAC is calculated > > + using HMAC SHA-256. It takes as input a key and a message. The key > > + used for the MAC calculation is always the 256-bit RPMB authentication > > + key. The message used as input to the MAC calculation is the > > + concatenation of the fields in the RPMB frames excluding stuff bytes > > + and the MAC itself. > > + > > +\item[\field{data}] is used to be written or read via authenticated > > + read/write access. It's fixed 256B. > > + > > +\item[\field{nonce}] is a random number generated by the user for the read > > + or get write counter requests and copied to the response by the device. > > + It's used for anti-replay protection. > > + > > +\item[\field{writer_counter}] is the counter value for the total amount of > > + the successful authenticated data write requests. > > + > > +\item[\field{address}] is the address of the data to be written to or read > > + from the RPMB virtio device. It is the number of the accessed > > + half sector (256B). > > + > > +\item[\field{block_count}] is the number of blocks (256B) requested to be > > + read/written. It's limited by \field{max_wr_cnt} or \field{max_rd_cnt}. > > + For RPMB read request, one virtio buffer including request command and > > + the subsequent [\field{block_count}] virtio buffers for response data > > + are placed in the queue. > > + For RPMB write request, [\field{block_count}] virtio buffers including > > + request command and data are placed in the queue. > > + > > +\item[\field{result}] includes information about the status of access made > > + to the device. It is written by the device. > > + > > +\item[\field{req_resp}] is the type of request or response, to/from the device. > > +\end{description} > > + > > +\devicenormative{\paragraph}{Device Operation: Program Key}{Device > > +Types / RPMB Device / Device Operation / Device Operation: Program > > +Key} > > + > > +If VIRTIO_RPMB_REQ_RESULT_READ is requested, the device SHOULD return > > +the RPMB frame with the response, the calculated MAC and the result: > > + > > +\begin{enumerate} > > +\item If the \field{block_count} is not set to 1 then > > + VIRTIO_RPMB_RES_GENERAL_FAILURE SHOULD be responded as > \field{result}. > > + > > +\item If the programming of authentication key fails, > > + then VIRTIO_RPMB_RES_WRITE_FAILURE SHOULD be responded as > \field{result}. > > + > > +\item If some other error occurs then returned result > > + VIRTIO_RPMB_RES_GENERAL_FAILURE SHOULD be responded as > \field{result}. > > + > > +\item The \field{req_resp} value VIRTIO_RPMB_RESP_PROGRAM_KEY > SHOULD be responded. > > +\end{enumerate} > > + > > +\devicenormative{\paragraph}{Device Operation: Get Write > > +Counter}{Device Types / RPMB Device / Device Operation / Device > > +Operation: Get Write Counter} > > + > > +If the authentication key is not yet programmed then > > +VIRTIO_RPMB_RES_NO_AUTH_KEY SHOULD be returned in \field{result}. > > + > > +If block count has not been set to 1 then > > +VIRTIO_RPMB_RES_GENERAL_FAILURE SHOULD be responded as > \field{result}. > > + > > +The \field{req_resp} value VIRTIO_RPMB_RESP_GET_COUNTER SHOULD be > responded. > > + > > +\devicenormative{\paragraph}{Device Operation: Data Write}{Device > > +Types / RPMB Device / Device Operation / Device Operation: Data > > +Write} > > + > > +If VIRTIO_RPMB_REQ_RESULT_READ is requested, the device SHOULD return > > +the RPMB data frame with the response VIRTIO_RPMB_RESP_DATA_WRITE, > > +the incremented counter value, the data address, the calculated MAC and the > result: > > + > > +\begin{enumerate} > > +\item If the authentication key is not yet programmed, > > + then VIRTIO_RPMB_RES_NO_AUTH_KEY SHOULD be returned in > \field{result}. > > + > > +\item If block count is zero or greater than \field{max_wr_cnt} then > > + VIRTIO_RPMB_RES_GENERAL_FAILURE SHOULD be responded. > > + > > +\item The device MUST check whether the write counter has expired. > > + If the write counter is expired then the \field{result} SHOULD be > > +set to > > + VIRTIO_RPMB_RES_WRITE_COUNTER_EXPIRED. > > + > > +\item If there is an error in the address (out of range) then the > > +\field{result} > > + SHOULD be set to VIRTIO_RPMB_RES_ADDR_FAILURE. > > + > > +\item The device MUST calculate the MAC taking authentication key and > > +frame as input, > > + and compare this with the MAC in the request. If the two MACâs are > > +different > > + then VIRTIO_RPMB_RES_AUTH_FAILURE SHOULD be returned in > \field{result}. > > + > > +\item If the writer counter in the request is different from the one maintained > > + by the device then VIRTIO_RPMB_RES_COUNT_FAILURE SHOULD be > returned in \field{result}. > > + > > +\item If the MAC and write counter comparisons are matched then the write > request > > + is considered to be authenticated. The data from the request SHOULD be > written to the > > + address indicated in the request and the write counter SHOULD be > incremented by 1. > > + > > +\item If the write fails then the \field{result} SHOULD be > VIRTIO_RPMB_RES_WRITE_FAILURE. > > + > > +\item If some other error occurs during the writing procedure then the > \field{result} > > + SHOULD be VIRTIO_RPMB_RES_GENERAL_FAILURE. > > + > > +\item The \field{req_resp} value VIRTIO_RPMB_RESP_DATA_WRITE SHOULD > be responded. > > +\end{enumerate} > > + > > +\devicenormative{\paragraph}{Device Operation: Data Read}{Device > > +Types / RPMB Device / Device Operation / Device Operation: Data Read} > > + > > +If the authentication key is not yet programmed then > > +VIRTIO_RPMB_RES_NO_AUTH_KEY SHOULD be returned in \field{result}. > > + > > +If block count has not been set to 1 then > > +VIRTIO_RPMB_RES_GENERAL_FAILURE SHOULD be responded as > \field{result}. > > + > > +If there is an error in the address (out of range) then the > > +\field{result} SHOULD be set to VIRTIO_RPMB_RES_ADDR_FAILURE. > > + > > +If data fetch from addressed location inside the device fails then > > +the \field{result} SHOULD be VIRTIO_RPMB_RES_READ_FAILURE. > > + > > +If some other error occurs during the read procedure then the > > +\field{result} SHOULD be VIRTIO_RPMB_RES_GENERAL_FAILURE. > > + > > +The \field{req_resp} value VIRTIO_RPMB_RESP_DATA_READ SHOULD be > responded. > > + > > +\devicenormative{\paragraph}{Device Operation: Result Read}{Device > > +Types / RPMB Device / Device Operation / Device Operation: Result > > +Read} > > + > > +If the \field{block_count} has not been set to 1 of > > +VIRTIO_RPMB_REQ_RESULT_READ request then > VIRTIO_RPMB_RES_GENERAL_FAILURE SHOULD be responded as \field{result}. > > + > > +\drivernormative{\subsubsection}{Device Operation}{Device Types / > > +RPMB Device / Device Operation} > > + > > +The RPMB frames MUST not be packed by the driver. > > +The driver MUST configure, initialize and format virtqueue for the RPMB > requests received from its caller then send it to the device. > > + > > +\devicenormative{\subsubsection}{Device Operation}{Device Types / > > +RPMB Device / Device Operation} > > + > > +The virtio-rpmb device could be backed in a number of ways. It SHOULD > > + keep consistent behaviors with hardware as described in paragraph > > + 6.6.22 of \hyperref[intro:eMMC]{eMMC}. > > + Some elements are maintained by the device: > > +\begin{enumerate} > > +\item The device MUST maintain a one-time programmable authentication > key. > > + It cannot be overwritten, erased or read. The key is used to > > + authenticate the accesses when MAC is calculated. This key MUST be > > + kept regardless of device reset or reboot. > > +\item The device MUST maintain a read-only monotonic write counter. > > +It > > + MUST be initialized to zero and added by one automatically along with > > + successful write operation. The value cannot be reset. After > > + the counter has reached its maximum value 0xFFFF FFFF, it will > > + not be incremented anymore. This counter MUST be kept regardless > > + of device reset or reboot. > > +\item The device MUST maintain the data for read/write via authenticated > > + access. > > +\end{enumerate} > > + > > -- > > 2.7.4 > > > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org > > For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]