| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-Id: <1478548394-8184-12-git-send-email-tomas.winkler@intel.com>
Date: Mon, 7 Nov 2016 21:53:14 +0200
From: Tomas Winkler <tomas.winkler@...el.com>
To: Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
Ulf Hansson <ulf.hansson@...aro.org>,
Adrian Hunter <adrian.hunter@...el.com>,
James Bottomley <James.Bottomley@...senPartnership.com>,
"Martin K . Petersen" <martin.petersen@...cle.com>,
Vinayak Holikatti <vinholikatti@...il.com>,
Andy Lutomirski <luto@...nel.org>,
Arve Hjønnevåg <arve@...roid.com>,
Michael Ryleev <gmar@...gle.com>,
Joao Pinto <Joao.Pinto@...opsys.com>,
Christoph Hellwig <hch@....de>,
Yaniv Gardi <ygardi@...eaurora.org>
Cc: Avri Altman <avri.altman@...il.com>, linux-kernel@...r.kernel.org,
linux-mmc@...r.kernel.org, linux-scsi@...r.kernel.org,
linux-doc@...r.kernel.org, Tomas Winkler <tomas.winkler@...el.com>
Subject: [PATCH v7 11/11] char: rpmb: Document Replay Protected Memory Block (RPMB) subsystem
Add rpmb documentatin in sphinx format.
V7: new in the series
Signed-off-by: Tomas Winkler <tomas.winkler@...el.com>
---
Documentation/index.rst | 1 +
Documentation/rpmb/conf.py | 5 ++
Documentation/rpmb/index.rst | 18 ++++++
Documentation/rpmb/introduction.rst | 102 +++++++++++++++++++++++++++++++
Documentation/rpmb/rpmb-tool.rst | 19 ++++++
Documentation/rpmb/simulation-device.rst | 19 ++++++
MAINTAINERS | 1 +
7 files changed, 165 insertions(+)
create mode 100644 Documentation/rpmb/conf.py
create mode 100644 Documentation/rpmb/index.rst
create mode 100644 Documentation/rpmb/introduction.rst
create mode 100644 Documentation/rpmb/rpmb-tool.rst
create mode 100644 Documentation/rpmb/simulation-device.rst
diff --git a/Documentation/index.rst b/Documentation/index.rst
index c53d089455a4..56dd46e9359c 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -18,6 +18,7 @@ Contents:
media/index
gpu/index
80211/index
+ rpmb/index
Indices and tables
==================
diff --git a/Documentation/rpmb/conf.py b/Documentation/rpmb/conf.py
new file mode 100644
index 000000000000..20c7c275ef4a
--- /dev/null
+++ b/Documentation/rpmb/conf.py
@@ -0,0 +1,5 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = "Linux 802.11 Driver Developer's Guide"
+
+tags.add("subproject")
diff --git a/Documentation/rpmb/index.rst b/Documentation/rpmb/index.rst
new file mode 100644
index 000000000000..876a2603e4b5
--- /dev/null
+++ b/Documentation/rpmb/index.rst
@@ -0,0 +1,18 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+==============================================
+Replay Protected Memory Block (RPMB) subsystem
+==============================================
+
+.. toctree::
+
+ introduction
+ simulation-device.rst
+ rpmb-tool.rst
+
+.. only:: subproject
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/rpmb/introduction.rst b/Documentation/rpmb/introduction.rst
new file mode 100644
index 000000000000..f4ded7d18e55
--- /dev/null
+++ b/Documentation/rpmb/introduction.rst
@@ -0,0 +1,102 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+=============
+Introduction:
+=============
+
+Few storage technologies such is EMMC, UFS, and NVMe support RPMB
+hardware partition with common protocol and frame layout.
+The RPMB partition `cannot` be accessed via standard block layer,
+but by a set of specific commands:
+
+WRITE, READ, GET_WRITE_COUNTER, and PROGRAM_KEY.
+
+The commands and the data are embedded within :c:type:`rpmb_frame <rpmb_frame>`.
+
+An RPMB partition provides authenticated and replay protected access,
+hence it is suitable as a secure storage.
+
+In-kernel API
+-------------
+The RPMB layer aims to provide in-kernel API for Trusted Execution
+Environment (TEE) devices that are capable to securely compute the block
+frame signature. In case a TEE device wish to store a replay protected
+data, it creates an RPMB frame with requested data and computes HMAC of
+the frame, then it requests the storage device via RPMB layer to store
+the data.
+
+The layer provides two APIs, for :c:func:`rpmb_req_cmd()` for issuing one of RPMB
+specific commands and :c:func:`rpmb_seq_cmd()` for issuing of raw RPMB protocol
+frames, which is close to the functionality provided by emmc multi ioctl
+interface.
+
+.. c:function:: int rpmb_cmd_req(struct rpmb_dev *rdev, struct rpmb_data *data);
+
+.. c:function:: int rpmb_cmd_seq(struct rpmb_dev *rdev, struct rpmb_cmd *cmds, u32 ncmds);
+
+
+A TEE driver can claim the RPMB interface, for example, via
+:c:func:`class_interface_register`:
+
+.. code-block:: c
+
+ struct class_interface tee_rpmb_intf = {
+ .class = &rpmb_class;
+ .add_dev = rpmb_add_device;
+ .remove_dev = rpmb_remove_device;
+ }
+ class_interface_register(&tee_rpmb_intf);
+
+
+RPMB device registeration
+----------------------------
+
+A storage device registers its RPMB hardware (eMMC) partition or RPMB
+W-LUN (UFS) with the RPMB layer :c:func:`rpmb_dev_register` providing
+an implementation for :c:func:`rpmb_seq_cmd()` handler. The interface
+enables sending sequence of RPMB standard frames.
+
+.. code-block:: c
+
+ struct rpmb_ops mmc_rpmb_dev_ops = {
+ .cmd_seq = mmc_blk_rpmb_cmd_seq,
+ .type = RPMB_TYPE_EMMC,
+ ...
+ }
+ rpmb_dev_register(disk_to_dev(part_md->disk), &mmc_rpmb_dev_ops);
+
+
+User space API
+--------------
+
+A parallel user space API is provided via /dev/rpmbX character
+device with two IOCTL commands.
+Simplified one, ``RPMB_IOC_REQ_CMD``, were read result cycles is performed
+by the framework on behalf the user and second, ``RPMB_IOC_SEQ_CMD`` where
+the whole RPMB sequence, including ``RESULT_READ`` is supplied by the caller.
+The latter is intended for easier adjusting of the applications that
+use ``MMC_IOC_MULTI_CMD`` ioctl, such as
+https://android.googlesource.com/trusty/app/storage/
+
+.. code-block:: c
+
+ struct rpmb_ioc_req_cmd ireq;
+ int ret;
+
+ ireq.req_type = RPMB_WRITE_DATA;
+ rpmb_ioc_cmd_set(ireq.icmd, RPMB_F_WRITE, frames_in, cnt_in);
+ rpmb_ioc_cmd_set(ireq.ocmd, 0, frames_out, cnt_out);
+
+ ret = ioctl(fd, RPMB_IOC_REQ_CMD, &ireq);
+
+
+API
+---
+.. kernel-doc:: include/linux/rpmb.h
+
+.. kernel-doc:: drivers/char/rpmb/core.c
+
+.. kernel-doc:: include/uapi/linux/rpmb.h
+
+.. kernel-doc:: drivers/char/rpmb/cdev.c
+
diff --git a/Documentation/rpmb/rpmb-tool.rst b/Documentation/rpmb/rpmb-tool.rst
new file mode 100644
index 000000000000..148eb0df4750
--- /dev/null
+++ b/Documentation/rpmb/rpmb-tool.rst
@@ -0,0 +1,19 @@
+==========
+RPMB Tool
+==========
+
+There is a sample rpmb tool under tools/rpmb/ directory that exercises
+the RPMB devices via RPMB character devices interface (/dev/rpmbX)
+
+.. code-block:: none
+
+ rpmb [-v] [-r|-s] <command> <args>
+
+ rpmb program-key [-<RPMB_DEVICE> <KEY_FILE>
+ rpmb write-counter <RPMB_DEVICE> [KEY_FILE]
+ rpmb write-blocks <RPMB_DEVICE> <address> <block_count> <DATA_FILE> <KEY_FILE>
+ rpmb read-blocks <RPMB_DEVICE> <address> <blocks count> <OUTPUT_FILE> [KEY_FILE]
+
+ rpmb -v/--verbose: runs in verbose mode
+ rpmb -s/--sequence: use RPMB_IOC_SEQ_CMD
+ rpmb -r/--request: use RPMB_IOC_REQ_CMD
diff --git a/Documentation/rpmb/simulation-device.rst b/Documentation/rpmb/simulation-device.rst
new file mode 100644
index 000000000000..9192a78a71d4
--- /dev/null
+++ b/Documentation/rpmb/simulation-device.rst
@@ -0,0 +1,19 @@
+======================
+RPMB Simulation Device
+======================
+
+RPMB partition simulation device is a virtual device that
+provides simulation of the RPMB protocol and uses kernel memory
+as storage.
+
+This driver cannot promise any real security, it is suitable for testing
+of the RPMB subsystem it self and mostly it was found useful for testing of
+RPMB applications prior to RPMB key provisioning/programming as
+The RPMB key programming can be performed only once in the life time
+of the storage device.
+
+Implementation:
+---------------
+
+.. kernel-doc:: drivers/char/rpmb/rpmb_sim.c
+
diff --git a/MAINTAINERS b/MAINTAINERS
index d9bca5134c7f..fa6f8017a05c 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -10292,6 +10292,7 @@ F: drivers/char/rpmb/*
F: include/uapi/linux/rpmb.h
F: include/linux/rpmb.h
F: Documentation/ABI/testing/sysfs-class-rpmb
+F: Documentation/rpmb.rst
F: tools/rpmb/
RTL2830 MEDIA DRIVER
--
2.7.4
Powered by blists - more mailing lists