mirror of
https://github.com/ARM-software/arm-trusted-firmware.git
synced 2025-05-09 02:51:21 +00:00
docs: el3 token signing
Add documentation for the feature where EL3 can be used to sign realm attestation token requests using RMM_EL3_TOKEN_SIGN command. This patch also adds documentation for the RMM_EL3_FEATURES features command that can be used to discover support for features such as RMM_EL3_TOKEN_SIGN. Change-Id: Iab5a157761ed17931210c3702f813198fc9c4b3a Signed-off-by: Raghu Krishnamurthy <raghupathyk@nvidia.com>
This commit is contained in:
Raghu Krishnamurthy
Soby Mathew
parent
a9fdd198fd
commit
b226357bdb
3 changed files with 318 additions and 1 deletions
|
|
@ -52,7 +52,7 @@ are explained below:
|
|||
- ``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.3 version of Boot Interface ABI and RMM-EL3
|
||||
This document specifies the 0.4 version of Boot Interface ABI and RMM-EL3
|
||||
services specification and the 0.3 version of the Boot Manifest.
|
||||
|
||||
.. _rmm_el3_boot_interface:
|
||||
|
|
@ -259,6 +259,8 @@ implemented by EL3 Firmware.
|
|||
0xC40001B1,``RMM_GTSI_UNDELEGATE``
|
||||
0xC40001B2,``RMM_ATTEST_GET_REALM_KEY``
|
||||
0xC40001B3,``RMM_ATTEST_GET_PLAT_TOKEN``
|
||||
0xC40001B4,``RMM_EL3_FEATURES``
|
||||
0xC40001B5,``RMM_EL3_TOKEN_SIGN``
|
||||
|
||||
RMM_RMI_REQ_COMPLETE command
|
||||
============================
|
||||
|
|
@ -505,6 +507,170 @@ a failure. The errors are ordered by condition check.
|
|||
``E_RMM_UNK``,An unknown error occurred whilst processing the command
|
||||
``E_RMM_OK``,No errors detected
|
||||
|
||||
RMM_EL3_FEATURES command
|
||||
========================
|
||||
|
||||
This command provides a mechanism to discover features and ABIs supported by the
|
||||
RMM-EL3 interface, for a given version. This command is helpful when there are
|
||||
platform specific optional RMM-EL3 interfaces and features exposed by vendor
|
||||
specific EL3 firmware, and a generic RMM that can modify its behavior based on
|
||||
discovery of EL3 features.
|
||||
|
||||
The features can be discovered by specifying the feature register index that
|
||||
has fields defined to indicate presence or absence of features and other
|
||||
relevant information. The feature register index is specified in the
|
||||
``feat_reg_idx`` parameter. Each feature register is a 64 bit register.
|
||||
|
||||
This command is available from v0.4 of the RMM-EL3 interface.
|
||||
|
||||
The following is the register definition for feature register index 0 for
|
||||
v0.4 of the interface:
|
||||
|
||||
RMM-EL3 Feature Resister 0
|
||||
--------------------------
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
63 32 31 16 15 8 7 1 0
|
||||
+-------+-------+-------+-------+-------+-------+-------+-------+
|
||||
| | | | | | | | |
|
||||
| | | | | | | | |
|
||||
+-------+-------+-------+-------+-------+-------+-------+-------+
|
||||
^
|
||||
|
|
||||
RMMD_EL3_TOKEN_SIGN
|
||||
|
||||
**Bit Fields:**
|
||||
|
||||
- **Bit 0**: `RMMD_EL3_TOKEN_SIGN`
|
||||
- When set to 1, the `RMMD_EL3_TOKEN_SIGN` feature is enabled.
|
||||
- When cleared (0), the feature is disabled.
|
||||
- **Bits [1:63]**: Reserved (must be zero)
|
||||
|
||||
FID
|
||||
---
|
||||
|
||||
``0xC40001B4``
|
||||
|
||||
|
||||
Input values
|
||||
------------
|
||||
|
||||
.. csv-table:: Input values for RMM_EL3_FEATURES
|
||||
:header: "Name", "Register", "Field", "Type", "Description"
|
||||
:widths: 1 1 1 1 5
|
||||
|
||||
fid,x0,[63:0],UInt64,Command FID
|
||||
feat_reg_idx,x1,[63:0],UInt64, "Feature register index. For v0.4, a value of 0 is the only
|
||||
acceptable value"
|
||||
|
||||
|
||||
Output values
|
||||
-------------
|
||||
|
||||
.. csv-table:: Output values for RMM_EL3_FEATURES
|
||||
:header: "Name", "Register", "Field", "Type", "Description"
|
||||
:widths: 1 1 1 1 5
|
||||
|
||||
Result,x0,[63:0],Error Code,Command return status
|
||||
feat_reg,x1,[63:0],Value,Value of the register as defined above
|
||||
|
||||
Failure conditions
|
||||
------------------
|
||||
|
||||
The table below shows all the possible error codes returned in ``Result`` upon
|
||||
a failure. The errors are ordered by condition check.
|
||||
|
||||
.. csv-table:: Failure conditions for RMM_EL3_FEATURES
|
||||
:header: "ID", "Condition"
|
||||
:widths: 1 5
|
||||
|
||||
``E_RMM_INVAL``,``feat_reg_idx`` is out of valid range
|
||||
``E_RMM_UNK``,"if the SMC is not present, if interface version is <0.4"
|
||||
``E_RMM_OK``,No errors detected
|
||||
|
||||
RMM_EL3_TOKEN_SIGN command
|
||||
==========================
|
||||
|
||||
This command is an optional command that can be discovered using the RMM_EL3_FEATURES command.
|
||||
This command is used to send requests related to realm attestation token signing requests to EL3.
|
||||
The command supports 3 opcodes:
|
||||
|
||||
- RMM_EL3_TOKEN_SIGN_PUSH_REQ_OP
|
||||
- RMM_EL3_TOKEN_SIGN_PULL_RESP_OP
|
||||
- RMM_EL3_TOKEN_SIGN_GET_RAK_PUB_OP
|
||||
|
||||
The above opcodes can be used to send realm attestation token signing requests to EL3 and get their
|
||||
response, so that the realm attestation token can be constructed.
|
||||
|
||||
This command is useful when the RMM may not have access to the private portion of the realm
|
||||
attestation key and needs signing services from EL3 or CCA HES, or other platform specific
|
||||
mechanisms to perform signing.
|
||||
|
||||
The RMM-EL3 interface for this command is modeled as two separate queues, one for signing requests
|
||||
and one for retrieving the signed responses. It is possible that the queue in EL3 is full or EL3 is busy and
|
||||
unable to service the RMM requests, in which case the RMM is expected to retry the push operation
|
||||
for requests and pop operation for responses.
|
||||
|
||||
FID
|
||||
---
|
||||
|
||||
``0xC40001B5``
|
||||
|
||||
Input values
|
||||
------------
|
||||
|
||||
.. csv-table:: Input values for RMM_EL3_TOKEN_SIGN
|
||||
:header: "Name", "Register", "Field", "Type", "Description"
|
||||
:widths: 1 1 1 1 5
|
||||
|
||||
fid,x0,[63:0],UInt64,Command FID
|
||||
opcode,x1,[63:0],UInt64,"
|
||||
Opcode that is one of:
|
||||
|
||||
- RMM_EL3_TOKEN_SIGN_PUSH_REQ_OP: 0x1 -
|
||||
Opcode to push a token signing request to EL3 using struct el3_token_sign_request as described above
|
||||
- RMM_EL3_TOKEN_SIGN_PULL_RESP_OP: 0x2 -
|
||||
Opcode to pull a token signing response from EL3 using struct el3_token_sign_response as described above
|
||||
- RMM_EL3_TOKEN_SIGN_GET_RAK_PUB_OP: 0x3 -
|
||||
Opcode to get the realm attestation public key
|
||||
|
||||
"
|
||||
buf_pa,x2,[63:0],Address,"PA where the request structure is stored for the opcode RMM_EL3_TOKEN_SIGN_PUSH_REQ_OP, the response structure needs to be populated for the opcode RMM_EL3_TOKEN_SIGN_PULL_RESP_OP, or where the public key must be populated for the opcode RMM_EL3_TOKEN_SIGN_GET_RAK_PUB_OP. The PA must belong to the RMM-EL3 shared buffer"
|
||||
buf_size,x3,[63:0],Size,Size in bytes of the input buffer in ``buf_pa``. ``buf_pa + buf_size`` must lie within the shared buffer
|
||||
ecc_curve,x4,[63:0],Enum,Type of the elliptic curve to which the requested attestation key belongs to. See :ref:`ecc_curves`. This parameter is valid on for the opcode RMM_EL3_TOKEN_SIGN_GET_RAK_PUB_OP
|
||||
|
||||
Output values
|
||||
-------------
|
||||
|
||||
.. csv-table:: Output values for RMM_EL3_TOKEN_SIGN
|
||||
:header: "Name", "Register", "Field", "Type", "Description"
|
||||
:widths: 1 1 1 1 5
|
||||
|
||||
Result,x0,[63:0],Error Code,Command return status. Valid for all opcodes listed in input values
|
||||
retval1,x1,[63:0],Value, "If opcode is RMM_EL3_TOKEN_SIGN_GET_RAK_PUB_OP, then returns length of
|
||||
public key returned. Otherwise, reserved"
|
||||
|
||||
|
||||
Failure conditions
|
||||
------------------
|
||||
|
||||
The table below shows all the possible error codes returned in ``Result`` upon
|
||||
a failure. The errors are ordered by condition check.
|
||||
|
||||
.. csv-table:: Failure conditions for RMM_EL3_TOKEN_SIGN
|
||||
:header: "ID", "Condition"
|
||||
:widths: 1 5
|
||||
|
||||
``E_RMM_INVAL``,"if opcode is invalid or buffer address and length passed to the EL3 are not in valid range
|
||||
corresponding to the RMM-EL3 shared buffer, or if the curve used for opcode
|
||||
RMM_EL3_TOKEN_SIGN_GET_RAK_PUB_OP is not the ECC P384 curve"
|
||||
``E_RMM_UNK``,"if the SMC is not present, if interface version is <0.4"
|
||||
``E_RMM_AGAIN``,"For opcode RMM_EL3_TOKEN_SIGN_PUSH_REQ_OP, if the request is not queued since
|
||||
the EL3 queue is full, or if the response is not ready yet, for other opcodes"
|
||||
``E_RMM_OK``,No errors detected
|
||||
|
||||
|
||||
RMM-EL3 world switch register save restore convention
|
||||
_____________________________________________________
|
||||
|
||||
|
|
@ -654,3 +820,55 @@ Console Info structure contains information about each Console available to RMM.
|
|||
| flags | 40 | uint64_t | Additional flags (RES0) |
|
||||
+-----------+--------+---------------+----------------------------------------+
|
||||
|
||||
.. _el3_token_sign_request_struct:
|
||||
|
||||
EL3 Token Sign Request structure
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This structure represents a realm attestation toekn signing request.
|
||||
|
||||
+-------------+--------+---------------+-----------------------------------------+
|
||||
| Name | Offset | Type | Description |
|
||||
+=============+========+===============+=========================================+
|
||||
| sig_alg_id | 0 | uint32_t | Algorithm idenfier for the sign request.|
|
||||
| | | | - 0x0: ECC SECP384R1 (ECDSA) |
|
||||
| | | | - Other values reserved |
|
||||
+-------------+--------+---------------+-----------------------------------------+
|
||||
| rec_granule | 8 | uint64_t | Identifier used by RMM to associate |
|
||||
| | | | a signing request to a realm. Must not |
|
||||
| | | | be interpreted or modified. |
|
||||
+-------------+--------+---------------+-----------------------------------------+
|
||||
| req_ticket | 16 | uint64_t | Value used by RMM to associate request |
|
||||
| | | | and responses. Must not be interpreted |
|
||||
| | | | or modified. |
|
||||
+-------------+--------+---------------+-----------------------------------------+
|
||||
| hash_alg_id | 24 | uint32_t | Hash algorithm for data in `hash_buf` |
|
||||
| | | | - 0x1: SHA2-384 |
|
||||
| | | | - All other values reserved. |
|
||||
+-------------+--------+---------------+-----------------------------------------+
|
||||
| hash_buf | 32 | uint8_t[] | TBS (to-be-signed) Hash of length |
|
||||
| | | | defined by hash algorithm `hash_alg_id` |
|
||||
+-------------+--------+---------------+-----------------------------------------+
|
||||
|
||||
.. _el3_token_sign_response_struct:
|
||||
|
||||
EL3 Token Sign Response structure
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This structure represents a realm attestation token signing response.
|
||||
|
||||
+---------------+--------+---------------+-----------------------------------------+
|
||||
| Name | Offset | Type | Description |
|
||||
+===============+========+===============+=========================================+
|
||||
| rec_granule | 0 | uint64_t | Identifier used by RMM to associate |
|
||||
| | | | a signing request to a realm. Must not |
|
||||
| | | | be interpreted or modified. |
|
||||
+---------------+--------+---------------+-----------------------------------------+
|
||||
| req_ticket | 8 | uint64_t | Value used by RMM to associate request |
|
||||
| | | | and responses. Must not be interpreted |
|
||||
| | | | or modified. |
|
||||
+---------------+--------+---------------+-----------------------------------------+
|
||||
| sig_len | 16 | uint16_t | Length of the `signature_buf` field |
|
||||
+---------------+--------+---------------+-----------------------------------------+
|
||||
| signature_buf | 18 | uint8_t[] | Signature |
|
||||
+---------------+--------+---------------+-----------------------------------------+
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue