* [virtio-dev] [PATCH v6] Add virtio rpmb device specification
@ 2019-10-09 2:36 Huang Yang
2019-10-27 11:48 ` Michael S. Tsirkin
2019-10-27 11:49 ` Michael S. Tsirkin
0 siblings, 2 replies; 3+ messages in thread
From: Huang Yang @ 2019-10-09 2:36 UTC (permalink / raw)
To: virtio-dev; +Cc: mst, cohuck, bing.zhu, tomas.winkler, peter.fang, Huang Yang
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.
---
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-B51.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
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [virtio-dev] [PATCH v6] Add virtio rpmb device specification
2019-10-09 2:36 [virtio-dev] [PATCH v6] Add virtio rpmb device specification Huang Yang
@ 2019-10-27 11:48 ` Michael S. Tsirkin
2019-10-27 11:49 ` Michael S. Tsirkin
1 sibling, 0 replies; 3+ messages in thread
From: Michael S. Tsirkin @ 2019-10-27 11:48 UTC (permalink / raw)
To: Huang Yang; +Cc: virtio-dev, cohuck, bing.zhu, tomas.winkler, peter.fang
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-B51.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
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [virtio-dev] [PATCH v6] Add virtio rpmb device specification
2019-10-09 2:36 [virtio-dev] [PATCH v6] Add virtio rpmb device specification Huang Yang
2019-10-27 11:48 ` Michael S. Tsirkin
@ 2019-10-27 11:49 ` Michael S. Tsirkin
1 sibling, 0 replies; 3+ messages in thread
From: Michael S. Tsirkin @ 2019-10-27 11:49 UTC (permalink / raw)
To: Huang Yang; +Cc: virtio-dev, cohuck, bing.zhu, tomas.winkler, peter.fang
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.
Just one point, pls send comments to virtio-comment in the future.
virtio-dev is more for implementation discussions.
> ---
> 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-B51.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
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2019-10-27 11:49 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-10-09 2:36 [virtio-dev] [PATCH v6] Add virtio rpmb device specification Huang Yang
2019-10-27 11:48 ` Michael S. Tsirkin
2019-10-27 11:49 ` Michael S. Tsirkin
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.