refactor(rmmd): plat token requests in pieces
Until now, the attestation token size was limited by the size of the
shared buffer between RMM and TF-A. With this change, RMM can now
request the token in pieces, so they fit in the shared buffer. A new
output parameter was added to the SMC call, which will return (along
with the size of bytes copied into the buffer) the number of bytes
of the token that remain to be retrieved.
TF-A will keep an offset variable that will indicate the position in
the token where the next call will retrieve bytes from. This offset
will be increased on every call by adding the number number of bytes
copied. If the received hash size is not 0, TF-A will reset the
offset to 0 and copy from that position on.
The SMC call will now return at most the size of the shared buffer
in bytes on every call. Therefore, from now on, multiple SMC calls
may be needed to be issued if the token size exceeds the shared
buffer size.
Change-Id: I591f7013d06f64e98afaf9535dbea6f815799723
Signed-off-by: Juan Pablo Conde <juanpablo.conde@arm.com>
diff --git a/docs/components/rmm-el3-comms-spec.rst b/docs/components/rmm-el3-comms-spec.rst
index 5fbd7fd..03703bc 100644
--- a/docs/components/rmm-el3-comms-spec.rst
+++ b/docs/components/rmm-el3-comms-spec.rst
@@ -52,7 +52,7 @@
- ``RES0``: Bit 31 of the version number is reserved 0 as to maintain
consistency with the versioning schemes used in other parts of RMM.
-This document specifies the 0.2 version of Boot Interface ABI and RMM-EL3
+This document specifies the 0.3 version of Boot Interface ABI and RMM-EL3
services specification and the 0.3 version of the Boot Manifest.
.. _rmm_el3_boot_interface:
@@ -238,6 +238,7 @@
``E_RMM_BAD_PAS``,Incorrect PAS,-3
``E_RMM_NOMEM``,Not enough memory to perform an operation,-4
``E_RMM_INVAL``,The value of an argument was invalid,-5
+ ``E_RMM_AGAIN``,The resource is busy. Try again.,-6
If multiple failure conditions are detected in an RMM to EL3 command, then EL3
is allowed to return an error code corresponding to any of the failure
@@ -442,7 +443,21 @@
RMM_ATTEST_GET_PLAT_TOKEN command
=================================
-Retrieve the Platform Token from EL3.
+Retrieve the Platform Token from EL3. If the entire token does not fit in the
+buffer, EL3 returns a hunk of the token (via ``tokenHunkSize`` parameter) and
+indicates the remaining bytes that are pending retrieval (via ``remainingSize``
+parameter). The challenge object for the platform token must be populated in
+the buffer for the first call of this command and the size of the object is
+indicated by ``c_size`` parameter. Subsequent calls to retrieve remaining hunks of
+the token must be made with ``c_size`` as 0.
+
+If ``c_size`` is not 0, this command could cause regeneration of platform token
+and will return token hunk corresponding to beginning of the token.
+
+It is valid for the calls of this command to return ``E_RMM_AGAIN`` error,
+which is an indication to the caller to retry this command again. Depending on the
+platform, this mechanism can be used to implement queuing to HES, if HES is
+involved in platform token generation.
FID
---
@@ -457,9 +472,9 @@
:widths: 1 1 1 1 5
fid,x0,[63:0],UInt64,Command FID
- buf_pa,x1,[63:0],Address,PA of the platform attestation token. The challenge object is passed in this buffer. The PA must belong to the shared buffer
+ buf_pa,x1,[63:0],Address,"PA of the platform attestation token. The challenge object must be passed in this buffer for the first call of this command. Any subsequent calls, if required to retrieve the full token, should not have this object. The PA must belong to the shared buffer."
buf_size,x2,[63:0],Size,Size in bytes of the platform attestation token buffer. ``bufPa + bufSize`` must lie within the shared buffer
- c_size,x3,[63:0],Size,Size in bytes of the challenge object. It corresponds to the size of one of the defined SHA algorithms
+ c_size,x3,[63:0],Size,"Size in bytes of the challenge object. It corresponds to the size of one of the defined SHA algorithms. Any subsequent calls, if required to retrieve the full token, should set this size to 0."
Output values
-------------
@@ -469,7 +484,8 @@
:widths: 1 1 1 1 5
Result,x0,[63:0],Error Code,Command return status
- tokenSize,x1,[63:0],Size,Size of the platform token
+ tokenHunkSize,x1,[63:0],Size,Size of the platform token hunk retrieved
+ remainingSize,x2,[63:0],Size,Remaining bytes of the token that are pending retrieval
Failure conditions
------------------
@@ -481,9 +497,11 @@
:header: "ID", "Condition"
:widths: 1 5
+ ``E_RMM_AGAIN``,Resource for Platform token retrieval is busy. Try again.
``E_RMM_BAD_ADDR``,``PA`` is outside the shared buffer
``E_RMM_INVAL``,``PA + BSize`` is outside the shared buffer
- ``E_RMM_INVAL``,``CSize`` does not represent the size of a supported SHA algorithm
+ ``E_RMM_INVAL``,``CSize`` does not represent the size of a supported SHA algorithm for the first call to this command
+ ``E_RMM_INVAL``,``CSize`` is not 0 for subsequent calls to retrieve remaining hunks of the token
``E_RMM_UNK``,An unknown error occurred whilst processing the command
``E_RMM_OK``,No errors detected
diff --git a/docs/porting-guide.rst b/docs/porting-guide.rst
index 5643ea1..e672ad7 100644
--- a/docs/porting-guide.rst
+++ b/docs/porting-guide.rst
@@ -2248,26 +2248,35 @@
::
- Argument : uintptr_t, size_t *, uintptr_t, size_t
+ Argument : uintptr_t, size_t *, uintptr_t, size_t, size_t *
Return : int
-This function returns the Platform attestation token.
+This function returns the Platform attestation token. If the full token does
+not fit in the buffer, the function will return a hunk of the token and
+indicate how many bytes were copied and how many are pending. Multiple calls
+to this function may be needed to retrieve the entire token.
The parameters of the function are:
arg0 - A pointer to the buffer where the Platform token should be copied by
- this function. The buffer must be big enough to hold the Platform
- token.
+ this function. If the platform token does not completely fit in the
+ buffer, the function may return a piece of the token only.
- arg1 - Contains the size (in bytes) of the buffer passed in arg0. The
- function returns the platform token length in this parameter.
+ arg1 - Contains the size (in bytes) of the buffer passed in arg0. In
+ addition, this parameter is used by the function to return the size
+ of the platform token length hunk copied to the buffer.
arg2 - A pointer to the buffer where the challenge object is stored.
arg3 - The length of the challenge object in bytes. Possible values are 32,
- 48 and 64.
+ 48 and 64. This argument must be zero for subsequent calls to
+ retrieve the remaining hunks of the token.
+
+ arg4 - Returns the remaining length of the token (in bytes) that is yet to
+ be returned in further calls.
-The function returns 0 on success, -EINVAL on failure.
+The function returns 0 on success, -EINVAL on failure and -EAGAIN if the
+resource associated with the platform token retrieval is busy.
Function : plat_rmmd_get_cca_realm_attest_key() [mandatory when ENABLE_RME == 1]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~