The execution environment of a Realm is an EL0 + EL1 environment, as described in Arm Architecture Reference Manual for A-Profile architecture [3].

A Realm can use a Host call to pass arguments to the Host and receive results from the Host.

A Realm is able to determine whether a given IPA is protected or unprotected.

The RMM may suppress a feature which is supported by the underlying hardware platform, if exposing that feature to a Realm could lead to a security vulnerability.

An example of a way in which a Realm attribute may be observable is the outcome of an RMM command.

Attributes of a Realm include an array of measurement values. The first entry in this array is a RIM. The remaining entries in this array are REMs.

The VMID of a Realm is chosen by the Host. The VMID must be within the range supported by the hardware platform. The RMM ensures that every Realm on the system has a unique VMID.

The RMM treats the RPV as an opaque value.

The RPV is included in the Realm attestation report as a separate claim.

The RPV is included in the output of the RSI_REALM_CONFIG command.

If a Realm is live, it cannot be destroyed.

If a Realm owns a non-zero number of Data Granules, this implies that it has a starting level RTT which is live, and therefore that the Realm itself is live.

A transition from the pseudo-state NULL represents creation of an RD. A transition to the pseudo-state NULL represents destruction of an RD.

Permitted Realm state transitions are shown in the following figure. Each arc is labeled with the events which can cause the corresponding state transition.

The use of a Granule is reflected in its lifecycle state.

• Code or data used by the Host
• Code or data used by software in the Secure Security state
• Code or data used by a Realm
• Data used by the RMM to manage a Realm

A Granule may be used to store one of the following:

Examples of ways in which a Granule attribute may be observable include the outcome of an RMM command, and whether a memory access generates a fault.

A Granule whose state is neither UNDELEGATED nor DELEGATED is owned by a Realm.

The owner of a Granule is identified by the address of a Realm Descriptor (RD).

For a Granule whose state is RD, the ownership relation is recursive: the owning Realm is identified by the address of the RD itself.

• A starting level RTT. The address of this RTT is stored in the RD of the owning Realm.

• A non-starting level RTT. The address of this RTT is stored in its parent RTT, in an RTT entry whose state is TABLE. Recursively following the parent relationship leads to the RD of the owning Realm.

A Granule whose state is RTT is one of the following:

A Granule whose state is DATA is mapped at a Protected IPA, in an RTT entry whose state is ASSIGNED. The Realm which owns the RTT is the owner of the DATA Granule.

A REC has an “owner” attribute which points to the RD of the owning Realm.

If the state of a Granule is UNDELEGATED then the RMM does not prevent the GPT entry of the Granule from being changed by another agent to any value except GPT_REALM.

Permitted Granule state transitions are shown in the following figure. Each arc is labeled with the events which can cause the corresponding state transition.

Wiping is not guaranteed to be implemented as zero filling.

Examples of ways in which a REC attribute may be observable include the outcome of an RMM command, and the PE state following Realm entry.

The aux attribute of a REC is a list of auxiliary Granules.

The number of auxiliary Granules required for a REC is returned by the RMI_REC_AUX_COUNT command.

The number of auxiliary Granules required for a REC can vary between Realms on a CCA platform.

The gprs attribute of a REC is the set of general-purpose register values which are saved by the RMM on exit from the REC and restored by the RMM on entry to the REC.

The mpidr attribute of a REC is a value which can be used to identify the VPE associated with the REC.

The pc attribute of a REC is the program counter which is saved by the RMM on exit from the REC and restored by the RMM on entry to the REC.

The runnable flag of a REC determines whether the REC is eligible for execution. The RMI_REC_ENTER command results in a REC entry only if the value of the flag is RUNNABLE.

The runnable flag of a REC is controlled by the Realm. Its initial value is reflected in the Realm Initial Measurement, and during Realm execution its value can be changed by execution of the PSCI_CPU_ON and PSCI_CPU_OFF commands.

The state attribute of a REC is controlled by the Host, by execution of the RMI_REC_ENTER command.

The Aff0[7:4] field of a REC MPIDR value is res0 for compatibility with GICv3.

When creating the nth REC in a Realm, the Host is required to use the MPIDR corresponding to REC index n.

A transition from the pseudo-state NULL represents creation of a REC. A transition to the pseudo-state NULL represents destruction of a REC.

Permitted REC state transitions are shown in the following figure. Each arc is labeled with the events which can cause the corresponding state transition.

The maximum number of RECs per Realm is an implementation defined value which is discoverable via RMI_FEATURES.

RMM implementations across different CCA platforms may support disparate features and may offer disparate configuration options for Realms.

The features supported by an RMI implementation are discovered by reading feature pseudo-register values using the RMI_FEATURES command.

On Realm creation, the Host specifies a set of desired features in a Realm parameters structure to the RMI_REALM_CREATE command. The RMM checks that the features specified by the Host are supported by the implementation.

The features specified at Realm creation time are included in the Realm Initial Measurement.

The features supported by an RSI implementation are discovered by reading feature pseudo-register values using the RSI_FEATURES command.

The set of hash algorithms supported by the implementation is reported by the RMI_FEATURES command in RmiFeatureRegister0.

Support by the implementation for LPA2 is reported by the RMI_FEATURES command in RmiFeatureRegister0.

Usage of LPA2 for Realm Translation Tables is an attribute which is set by the Host during Realm creation.

Realm IPA width is an attribute which is set by the Host during Realm creation.

The Host can choose a smaller IPA width than the maximum supported IPA width reported by RMI_FEATURES. This is true regardless of whether LPA2 is enabled for the Realm.

A Realm can query its IPA width using the RSI_REALM_CONFIG command.

• RMI_DATA_CREATE
• RMI_DATA_CREATE_UNKNOWN
• RMI_RTT_CREATE
• RMI_RTT_MAP_UNPROTECTED

If LPA2 is not enabled for a Realm then passing a PA greater than or equal to 2^48 to any of the following commands causes an error to be returned:

Support by the implementation for the Scalable Vector Extension (FEAT_SVE) is reported by the RMI_FEATURES command in RmiFeatureRegister0.

Availability of SVE to a Realm is set by the Host during Realm creation.

SVE vector length for a Realm is set by the Host during Realm creation.

Self-hosted debug is always available in Armv8-A.

The number of breakpoints and watchpoints are attributes which are set by the Host during Realm creation.

Support by the implementation for the Performance Monitors Extension (FEAT_PMU) is reported by the RMI_FEATURES command in RmiFeatureRegister0.

Availability of PMU to a Realm is set by the Host during Realm creation.

The number of PMU counters available to a Realm is set by the Host during Realm creation.

The number of GICv3 List Registers which can be provided by the Host via the RMI_REC_ENTER command is reported by the RMI_FEATURES command in RmiFeatureRegister0.

When executing in a Realm, an exception taken to R-EL2 or EL3 results in a Realm exit.

The Host provides the address of a REC as an input to the RMI_REC_ENTER command.

In this chapter, both rec and “the target REC” refer to the REC object which is provided to the RMI_REC_ENTER command.

A RecRun object is stored in Non-secure memory.

The Host provides the address of a RecRun object as an input to the RMI_REC_ENTER command.

An implementation is permitted to return RMI_SUCCESS from RMI_REC_ENTER without performing a REC entry. For example, on observing a pending interrupt, the implementation can generate a REC exit due to IRQ without entering the target REC.

1. The exception is taken to EL3. The Monitor handles the exception and returns control to the Realm.

2. The exception is taken to EL3. The Monitor pre-empts Realm Security state and passes control to the Secure Security state. This may be for example due to an FIQ.

3. The exception is taken to EL2. The RMM decides to perform a REC exit. The RMM executes an SMC instruction, requesting the Monitor to pass control to the Non-secure Security state.

4. The exception is taken to EL2. The RMM executes an SMC instruction, requesting the Monitor to perform an operation, then returns control to the Realm.

5. The exception is taken to EL2. The RMM handles the exception and returns control to the Realm.

The following diagram summarises the possible control flows that result from a Realm exit.

An RmiRecEnter object is stored in the RecRun object which is passed by the Host as an input to the RMI_REC_ENTER command.

On REC entry, execution state is restored from the REC object and from the RmiRecEnter object to the PE.

An RmiRecEnter object contains attributes which are used to manage Realm virtual interrupts.

In this chapter, both enter and “the RmiRecEnter object” refer to the RmiRecEnter object which is provided to the RMI_REC_ENTER command.

On REC exitentry, all enter fields are ignored unless specified otherwise.

On execution of RMI_REC_ENTER, if the most recent exit from the target REC was not a REC exit due to Emulatable Data Abort and enter.flags.emul_mmio == RMI_EMULATED_MMIO, then the RMI_REC_ENTER command fails.

An RmiRecExit object is stored in the RecRun object which is passed by the Host as an input to the RMI_REC_ENTER command.

On REC exit, execution state is saved from the PE to the REC object and to the RmiRecExit object.

An RmiRecExit object contains attributes which are used to manage Realm virtual interrupts and Realm timers.

In this chapter, both exit and “the RmiRecExit object” refer to the RmiRecExit object which is provided to the RMI_REC_ENTER command.

On return from the RMI_REC_ENTER command, the reason for the REC exit is indicated by exit.exit_reason and exit.esr.

A synchronous exception taken to R-EL2 can cause a REC exit.

The following table summarises the behavior of synchronous exceptions taken to R-EL2.

• handled by the RMM, returning to the Realm, or
• forwarded by the RMM to the Host via a REC exit due to PSCI.

A PSCI function executed by a Realm is either:

PSCI functions not listed in this table are not supported. Calling a non-supported PSCI function results in a return value of PSCI_NOT_SUPPORTED.

The following table summarises the behavior of PSCI function execution by a Realm.

• If the Host provides PSCI_SUCCESS, the RMM performs the PSCI operation requested by the Realm. The result of the PSCI operation is recorded in the REC and returned to the Realm on the next entry to the calling REC.

• If the Host provides a status value other than PSCI_SUCCESS, the RMM validates that the status code is permitted for the PSCI operation requested by the Realm. If the status code is permitted, it is recorded in the REC and returned to the Realm on the next entry to the calling REC.

In the call to RMI_PSCI_COMPLETE, the Host provides a PSCI status value, which the RMM handles as follows:

In the call to RMI_PSCI_COMPLETE, the Host provides the target REC, which corresponds to the MPIDR value provided by the Realm. This is necessary because the RMM does not maintain a mapping from MPIDR values to REC addresses. The RMM validates that the REC provided by the Host matches the MPIDR value.

Following REC exit due to PSCI, if rec.psci_pending is PSCI_REQUEST_PENDING, the Host must complete the request by calling the RMI_PSCI_COMPLETE command, prior to re-entering the REC.

• exit holds the base address and the size of the region on which a RIPAS change is pending. These values inform the Host of the bounds of the RIPAS change request.

• rec holds the next address to be processed in a RIPAS change, and the top of the requested RIPAS change region. These values are used by the RMM to enforce that the RMI_RTT_SET_RIPAS command can only apply RIPAS change within the bounds of the RIPAS change request, and to report the progress of the RIPAS change to the Realm on the next REC entry.

On REC exit due to RIPAS change pending:

• Establish a mapping in the RTT, in which case it would want the Realm to re-attempt the access. In this case, on the next REC entry the Host sets enter.flags.emul_mmio = RMI_NOT_EMULATED_MMIO, which indicates that instruction emulation was not performed. This causes the return address to be the faulting instruction.

• Emulate the access. For an emulated write, the data is provided in exit.gprs[0]. For an emulated read, the data is provided in enter.gprs[0]. In this case, on the next REC entry the Host sets
  enter.flags.emul_mmio = RMI_EMULATED_MMIO, which indicates that the instruction was emulated. This causes the return address to be the address of the instruction which generated the Data Abort plus 4 bytes.

On taking the REC exit, the Host can either

On REC exit due to Emulatable Data Abort, sufficient information is provided to the Host to enable it to emulate the access, for example to emulate a virtual peripheral.

A Host call can be used by a Realm to make a hypercall.

The IPA space of a Realm is divided into two halves: Protected IPA space and Unprotected IPA space.

RIPAS values are stored in an RTT.

The Realm can query the RIPAS of an IPA range by executing RSI_IPA_STATE_GET.

Realm data access to a Protected IPA can cause an REC exit due to Data Abort.

Realm instruction fetch from a Protected IPA whose RIPAS is RAM can cause a REC exit due to Instruction Abort.

For a Realm in the REALM_NEW state, the RIPAS of a Protected IPA can change to RAM due to Host execution of RMI_DATA_CREATE or RMI_RTT_INIT_RIPAS.

For a Realm in the REALM_NEW state, changing the RIPAS of a Protected IPA to RAM causes the RIM to be updated.

For a Realm in the REALM_NEW state, the RIPAS of a Protected IPA can change to DESTROYED due to Host execution of RMI_DATA_DESTROY or RMI_RTT_DESTROY.

For a Realm in the REALM_NEW state, changing the RIPAS of a Protected IPA to DESTROYED does not cause the RIM to be updated.

A Realm in the REALM_ACTIVE state can request the RIPAS of a region of Protected IPA space to be changed to either EMPTY or RAM.

A Realm in the REALM_ACTIVE state cannot request the RIPAS of a region of Protected IPA space to be changed to DESTROYED.

For a Realm in the REALM_ACTIVE state, the RIPAS of a Protected IPA can change to EMPTY only in response to Realm execution of RSI_IPA_STATE_SET.

For a Realm in the REALM_ACTIVE state, the RIPAS of a Protected IPA can change to RAM only in response to Realm execution of RSI_IPA_STATE_SET.

On execution of RSI_IPA_STATE_SET, a Realm can optionally specify that the RIPAS change should only succeed if the current RIPAS is not DESTROYED.

For a Realm in the REALM_ACTIVE state, the RIPAS of a Protected IPA can change to DESTROYED due to Host execution of RMI_DATA_DESTROY or RMI_RTT_DESTROY.

The following diagram summarizes RIPAS changes which can occur when the Realm state is REALM_ACTIVE.

The RMM does not ensure that the GPT entry of a Granule mapped at an Unprotected IPA permits access via Non-secure PAS.

An access by a Realm to an Unprotected IPA can result in a Granule Protection Fault (GPF).

Realm data access to an Unprotected IPA can cause a REC exit due to Data Abort.

On taking a REC exit due to Data Abort at an Unprotected IPA, the Host can inject a Synchronous External Abort to the Realm.

Realm data access to an Unprotected IPA which caused ESR_EL2.ISS.ISV to be set to '1' can be emulated by the Host.

The following table summarizes the properties of Realm IPA space.

HIPAS values are stored in a Realm Translation Table (RTT).

HIPAS transitions are caused by execution of RMI commands.

A mapping at a Protected IPA is valid if the HIPAS is ASSIGNED and the RIPAS is RAM.

Each TTD.X column refers to the value of the corresponding “X” field in the architecturally-defined Stage 2 translation table descriptor which is written by the RMM.

• the translation table entry attributes, and
• the behavior which results from Realm access to that IPA.

The following table summarizes, for each combination of RIPAS and HIPAS for a Protected IPA:

The following diagram summarizes HIPAS changes at a Protected IPA which can occur when the Realm state is REALM_NEW.

The following diagram summarizes HIPAS changes at a Protected IPA which can occur when the Realm state is REALM_ACTIVE.

The following diagram summarizes HIPAS and RIPAS changes at a Protected IPA which can occur when the Realm state is NEW.

The following diagram summarizes HIPAS and RIPAS changes at a Protected IPA which can occur when the Realm state is REALM_ACTIVE.

The following table summarizes dependencies on RMI command execution on the current Protected IPA.

Successful execution of RMI_DATA_CREATE_UNKNOWN does not depend on the RIPAS value of the target IPA.

Successful execution of RMI_DATA_DESTROY does not depend on the RIPAS value of the target IPA.

Successful execution of RMI_RTT_DESTROY does not depend on the RIPAS values of entries in the target RTT.

Successful execution of RMI_RTT_FOLD does depend on the RIPAS values of entries in the target RTT.

The following diagram summarises HIPAS transitions for an Unprotected IPA.

• The top of the IPA range which has been modified by the command (new_base).
• If the requested RIPAS value was RAM, whether the Host rejected the Realm request.

Output values from RSI_IPA_STATE_SET indicate:

• The Realm issues a RIPAS change request by executing RSI_IPA_STATE_SET.
  • The input values to this command include:
    • The requested IPA range: [base, top)
    • The requested RIPAS value (either EMPTY or RAM)
    • A flag which indicates whether a change from DESTROYED should be permitted
  • The RMM records these values in the REC, and then performs a REC exit due to RIPAS change pending.
• In response, the Host executes zero or more RMI_RTT_SET_RIPAS commands.
• If the requested RIPAS value was RAM, at the next RMI_REC_ENTER the Host can optionally indicate that it rejects the RIPAS change request.

A RIPAS change consists of actions taken by first the Realm, and then the Host:

The RIPAS change process, together with the Realm Initial Measurement ensures that a Realm can always reliably determine the RIPAS of any Protected IPA.

A RIPAS change is applied by one or more calls to the RMI_RTT_SET_RIPAS command.

Successful execution of RMI_RTT_SET_RIPAS targets an RTTE at address rec.ripas_addr.

• rec.ripas_addr
• The command output value

On successful execution of RMI_RTT_SET_RIPAS, both of the following are set to the address of the next page whose RIPAS is to be modified:

then rec.ripas_addr and the command output value are both set to P.

• The RIPAS change request indicated that a change from DESTROYED should not be permitted
• A page P within the target IPA range has RIPAS value DESTROYED

If both of the following are true on successful execution of RMI_RTT_SET_RIPAS

On REC entry following a REC exit due to RIPAS change, GPR values are updated to indicate for how much of the target IPA range the RIPAS change has been applied.

Otherwise, the output value of RSI_IPA_STATE_SET indicates “Host accepted the request”.

• rec.ripas_value is RAM.
• rec.ripas_addr is not equal to rec.ripas_top.
• rec.ripas_response is REJECT.

If all of the following are true then the output value of RSI_IPA_STATE_SET indicates “Host rejected the request”:

The attributes and format of an Armv8-A stage 2 translation table are defined by the Armv8-A Virtual Memory System Architecture (VMSA) Arm Architecture Reference Manual for A-Profile architecture [3].

The RMM architecture can only be deployed on a hardware platform which implements a translation granule size of 4KB.

The contents of an RTT are not directly accessible to the Host.

The contents of an RTT are manipulated using RMM commands. These commands allow the Host to manipulate the contents of the RTT used by a Realm, subject to constraints imposed by the RMM.

• Another RTT
• A DATA Granule which is owned by the Realm
• Non-secure memory which is accessible to both the Realm and the Host

An RTTE contains an output address which can point to one of the following:

An RTT contains an array of RTTEs.

An RTT does not have an intrinsic “level” attribute. The level of an RTT is determined by its position within an RTT tree.

• whether LPA2 is selected when the Realm is created
• the rtt_level_start attribute of the Realm
• the ipa_width attribute of the Realm.

The maximum depth of an RTT tree depends on all of the following:

The RTT starting level is set when a Realm is created.

The number of starting level RTTs is architecturally defined as a function of the Realm IPA width and the RTT starting level. See Arm Architecture Reference Manual for A-Profile architecture [3] for further details.

The address of the first starting level RTT is stored in the RTT base attribute of the owning Realm.

The RTT base attribute is set when a Realm is created.

An RTT entry (RTTE) is an abstraction over an Armv8-A stage 2 translation table descriptor. The attributes and format of an Armv8-A stage 2 translation table descriptor are defined by the Armv8-A Virtual Memory System Architecture (VMSA) Arm Architecture Reference Manual for A-Profile architecture [3].

The state of an RTTE in a RTT which is not level 1 or level 2 or level 3 is UNASSIGNED, UNASSIGNED_NS or TABLE.

An RTT whose level n is not the starting RTT level is pointed-to by exactly one TABLE RTTE in a level n-1 RTT.

The following diagram shows an example RTT tree, annotated with RTTE states.

The function AddrIsRttLevelAligned() is used to evaluate whether an address is aligned to the address range described by an RTTE at a specified RTT level.

Attributes of an RTTE, including the RTTE state, can be read by calling the RMI_RTT_READ_ENTRY command. The set of RTTE attributes which are returned depends on the state of the RTTE.

The function RttIsHomogeneous() is used to evaluate whether an RTT is homogeneous.

On RTT folding, the state of the parent RTTE is determined from the contents of the child RTTEs.

The function RttFold() is used to evaluate the parent RTTE state which results from an RTT folding operation.

On RTT folding, if the state of the parent RTTE is ASSIGNED or ASSIGNED_NS then the attributes of the parent RTTE are copied from the child RTTEs.

On RTT unfolding, the state of all RTTEs in the child RTT are set to the state of the parent RTTE.

On RTT unfolding, if the state of the parent RTTE is ASSIGNED or ASSIGNED_NS, then the output addresses of RTTEs in the child RTT are set to a contiguous range which starts from the address of the parent RTTE.

The function RttSkipNonLiveEntries() is used to scan an RTT to find the next live RTTE. The resulting IPA is returned to the Host from commands whose successful execution causes a live RTTE to become non-live.

Note that an RTT can be non-live, even if one of its entries is live. This would be the case for example if the RTT corresponds to an Unprotected IPA range and the state of one of its entries is ASSIGNED_NS.

The function RttIsLive() is used to evaluate whether an RTT is live.

An RTT cannot be destroyed if it is live.

An RTT can be destroyed regardless of whether it is homogeneous.

• RIPAS is DESTROYED
• RTTE state is UNASSIGNED

Following RTT destruction, all of the following are true for the parent RTTE:

An IPA is translated to a PA by walking an RTT tree, starting at the RTT base.

The behaviour of an RTT walk is defined by the Armv8-A Virtual Memory System Architecture (VMSA) Arm Architecture Reference Manual for A-Profile architecture [3].

• it reaches the target RTT level, or
• it reaches an RTTE whose state is not TABLE.

The RTT walk terminates when either:

• a Realm Descriptor, which contains the address of the initial RTT
• a target IPA
• a target RTT level.

The inputs to an RTT walk are:

The function RmmRttWalkResult RttWalk(rd, addr, level) is used to represent an RTT walk.

The input address to an RTT walk is always less than 2^w, where w is the IPA width of the target Realm.

Hardware access flag and dirty bit management may be enabled by software executing within the Realm, for its own stage 1 translation.

If any other field in enter.gicv3_hcr is set to ‘1’, then RMI_REC_ENTER fails.

• UIE
• LRENPIE
• NPIE
• VGrp0EIE
• VGrp0DIE
• VGrp1EIE
• VGrp1DIE
• TDIR

On REC entry, fields in enter.gicv3_hcr must be set to ‘0’ except for the following:

If the Host has programmed an EL1 timer to assert its output during Realm execution, that timer output is not guaranteed to assert.

The rule that virtual and physical counter values are identical may need to be amended if a future version of the specification supports migration and / or virtualization of time based on the virtual counter differing from the physical counter.

It is only when a change in the hardware timer output means that the corresponding virtual interrupt needs to be made pending or idle, that a REC exit must occur.

During Realm execution, when the hardware timer signal is masked, the Realm may write to the timer registers, causing the hardware timer to become de-asserted and possibly asserted again. Such changes in the output of the EL1 timer are not required to result in a REC exit if the RMM can infer that the change should not result in a Realm-observable change to the state of virtual interrupts.

This masking is done to allow the Realm to make forward progress, which would otherwise be prevented by the hardware timer generating a physical interrupt that would cause a Realm exit.

On REC entry, for both the EL1 Virtual Timer and the EL1 Physical Timer, if the EL1 timer asserts its output in the state described in the REC exit structure from the previous REC exit then the RMM masks the hardware timer signal before returning to the Realm.

The RHA used by a Realm is selected via the hash_algo attribute.

The initial RIM value for a Realm is calculated from a subset of the Realm parameters.

A RIM is extended by applying the RHA to the inputs of RMM operations which are executed during Realm construction.

• Creation of a DATA Granule during Realm construction
• Creation of a runnable REC
• Changes to RIPAS of Protected IPA during Realm construction

The following operations cause a RIM to be extended:

A RIM is immutable while the state of the Realm is REALM_ACTIVE. This implies that a RIM reflects the configuration and contents of the Realm at the moment when it transitioned from the REALM_NEW to the REALM_ACTIVE state.

A RIM depends upon the order of the RMM operations which are executed during Realm construction.

The value of a RIM can be read using the RSI_MEASUREMENT_READ command.

A REM is extended using the RSI_MEASUREMENT_EXTEND command.

The value of a REM can be read using the RSI_MEASUREMENT_READ command.

The initial value of a REM is zero.

• Realm token

  Contains attributes of the Realm, including:

  • Realm Initial Measurement
  • Realm Extensible Measurements

• CCA platform token

  Contains attributes of the CCA platform on which the Realm is running, including:

  • CCA platform identity
  • CCA platform lifecycle state
  • CCA platform software component measurements

A CCA attestation token consists of two parts:

The size of a CCA attestation token may be greater than 4KB.

Each call to RSI_ATTESTATION_TOKEN_CONTINUE retrieves up to one Granule of the attestation token.

• Call RSI_ATTESTATION_TOKEN_INIT once
• Call RSI_ATTESTATION_TOKEN_CONTINUE in a loop, until the result is not RSI_INCOMPLETE

The process for a Realm to obtain an attestation token is:

Up to one attestation token generation operation may be ongoing on a REC.

On execution of RSI_ATTESTATION_TOKEN_INIT, if an attestation token generation operation is ongoing on the calling REC, it is terminated.

The challenge value provided to RSI_ATTESTATION_TOKEN_INIT is included in the generated attestation token. This allows the relying party to establish freshness of the attestation token.

Generation of an attestation token can be a long-running operation, during which interrupts may need to be handled.

• If a virtual interrupt is pending on that REC, it is taken to the REC’s exception handler
• RSI_ATTESTATION_TOKEN_CONTINUE returns RSI_INCOMPLETE
• The REC should call RSI_ATTESTATION_TOKEN_CONTINUE again

On the next entry to the REC:

If a physical interrupt becomes pending during execution of RSI_ATTESTATION_TOKEN_CONTINUE, a REC exit due to IRQ can occur.

The CCA attestation token is a profiled IETF Entity Attestation Token (EAT).

The CCA attestation token is a Concise Binary Object Representation (CBOR) map, in which the map values are the Realm token and the CCA platform token.

The Realm token contains structured data in CBOR, wrapped with a COSE_Sign1 envelope according to the CBOR Object Signing and Encryption (COSE) standard.

The Realm token is signed by the Realm Attestation Key (RAK).

The CCA platform token contains structured data in CBOR, wrapped with a COSE_Sign1 envelope according to the COSE standard.

The CCA platform token is signed by the Initial Attestation Key (IAK).

The CCA platform token contains a hash of RAK_pub. This establishes a cryptographic binding between the Realm token and the CCA platform token.

cca-token = #6.399(cca-token-collection) ; EAT tokenCMW Collection
                                         ; (draft-collection extensionietf-rats-msg-wrap)

cca-platform-token = bstr .cbor COSE_Sign1_Tagged
cca-realm-delegated-token = bstr .cbor COSE_Sign1_Tagged

cca-token-collection = {
    44234 => cca-platform-token          ; 44234 = 0xACCA
    44241 => cca-realm-delegated-token
}

; EAT standard definitions
COSE_Sign1_Tagged = #6.18(COSE_Sign1)

; Deliberately shortcut these definitions until EAT is finalised and able to
; pull in the full set of definitions
COSE_Sign1 = "COSE-Sign1 placeholder"

The CCA attestation token is defined as follows:

The composition of the CCA attestation token is summarised in the following figure.

cca-realm-claims = (cca-realm-claim-map)

cca-realm-claim-map = {
    cca-realm-challenge
    ? cca-realm-profile
    cca-realm-personalization-value
    cca-realm-initial-measurement
    cca-realm-extensible-measurements
    cca-realm-hash-algo-id
    cca-realm-public-key
    cca-realm-public-key-hash-algo-id
}

The Realm token claim map is defined as follows:

The Realm challenge claim is used to carry the challenge provided by the caller to demonstrate freshness of the generated token.

The Realm challenge claim is identified using the EAT nonce label (10).

The length of the Realm challenge is 64 bytes.

The Realm challenge claim must be present in a Realm token.

cca-realm-challenge-label = 10
cca-realm-challenge-type = bytes .size 64

cca-realm-challenge = (
    cca-realm-challenge-label => cca-realm-challenge-type
)

The format of the Realm challenge claim is defined as follows:

The Realm profile claim identifies the EAT profile to which the Realm token conforms.

The Realm profile claim is identified using the EAT profile label (265).

The Realm profile claim is optional in a CCA Realm token.

If the Realm profile is not included in a CCA Realm token then the profile value used in the CCA Platform token should refer to a profile that describes both Platform and Realm claims.

cca-realm-profile-label = 265 ; EAT profile

cca-realm-profile-type = "tag:arm.com,2023:realm#1.0.0"

cca-realm-profile = (
    cca-realm-profile-label => cca-realm-profile-type
)

The format of the Realm profile claim is defined as follows:

The Realm Personalization Value claim contains the RPV which was provided at Realm creation.

The Realm Personalization Value claim must be present in a Realm token.

cca-realm-personalization-value-label = 44235
cca-realm-personalization-value-type = bytes .size 64

cca-realm-personalization-value = (
    cca-realm-personalization-value-label => cca-realm-personalization-value-type
)

The format of the Realm Personalization Value claim is defined as follows:

The Realm Initial Measurement claim contains the values of the Realm Initial Measurement.

The Realm Initial Measurement claim must be present in a Realm token.

cca-realm-measurement-type = bytes .size 32 / bytes .size 48 / bytes .size 64
cca-realm-initial-measurement-label = 44238

cca-realm-initial-measurement = (
    cca-realm-initial-measurement-label => cca-realm-measurement-type
)

The format of the Realm Initial Measurement claim is defined as follows:

The Realm Extensible Measurements claim contains the values of the Realm Extensible Measurements.

The Realm Extensible Measurements claim must be present in a Realm token.

cca-realm-measurement-type = bytes .size 32 / bytes .size 48 / bytes .size 64
cca-realm-extensible-measurements-label = 44239

cca-realm-extensible-measurements = (
    cca-realm-extensible-measurements-label => [ 4*4 cca-realm-measurement-type ]
)

The format of the Realm measurements claim is defined as follows:

The Realm hash algorithm ID claim identifies the algorithm used to calculate all hash values which are present in the Realm token.

Arm recommends that the value of the Realm hash algorithm ID claim is an IANA Hash Function name IANA Named Information Hash Function Textual NamesAlgorithm Registry [10].

The Realm hash algorithm ID claim must be present in a Realm token.

cca-realm-hash-algo-id-label = 44236

cca-realm-hash-algo-id = (
    cca-realm-hash-algo-id-label => text
)

The format of the Realm hash algorithm ID claim is defined as follows:

The Realm public key claim identifies the key which is used to sign the Realm token.

The value of the Realm public key claim is RAK_pub, encoded according to SEC 1: Elliptic Curve Cryptography, version 2a CBOR bstr of a COSE_Key structure.0 [11] The parameters used for the COSE_Key are profile-specific.

The Realm public key claim must be present in a Realm token.

cca-realm-public-key-label = 44237

; TODO: support public key sizes other than ECC-P384
cca-realm-public-key-type = bytesbstr .size 97cbor COSE_Key

cca-realm-public-key = (
    cca-realm-public-key-label => cca-realm-public-key-type
)
COSE_Key-label = int / tstr

COSE_Key-values = any

; See RFC8152 for full definition of COSE_Key
COSE_Key = {
      1 => tstr / int,        ; kty
    ? 2 => bstr,              ; kid
    ? 3 => tstr / int,        ; alg
    ? 4 => [+ (tstr / int) ], ; key_ops
    ? 5 => bstr,              ; Base IV
    * COSE_Key-label => COSE_Key-values
}

The format of the Realm public key claim is defined as follows:

The Realm public key hash algorithm identifier claim identifies the algorithm used to calculate H(RAK_pub).

The Realm public key hash algorithm identifier claim must be present in a Realm token.

cca-realm-public-key-hash-algo-id-label = 44240

cca-realm-public-key-hash-algo-id = (
    cca-realm-public-key-hash-algo-id-label => text
)

The format of the Realm public key hash algorithm identifier claim is defined as follows:

/ Realm claim map /
{
    / cca-realm-profile /
    265: "tag:arm.com,2023:realm#1.0.0",

    / cca-realm-challenge /
    10: h'ABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABAB
          ABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABAB',

    / cca-realm-personalization-value /
    44235: h'ABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABAB
             ABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABAB',

    / cca-realm-initial-measurement /
    44238: h'0000000000000000000000000000000000000000000000000000000000000000',

    / cca-realm-extensible-measurements /
    44239: [
        h'0000000000000000000000000000000000000000000000000000000000000000',
        h'0000000000000000000000000000000000000000000000000000000000000000',
        h'0000000000000000000000000000000000000000000000000000000000000000',
        h'0000000000000000000000000000000000000000000000000000000000000000'
    ],

    / cca-realm-hash-algo-id /
    44236: "sha-256",

    / cca-realm-public-key /
    44237: h'0476F988091BE585ED41801AECFAB858548C63057E16B0E676120BBD0D2F9C29
             E056C5D41A0130EB9C21517899DC23146B28E1B062BD3EA4B315FD219F1CBB52
             8CB6E74CA49BE16773734F61A1CA61031B2BBF3D918F2F94FFC4228E50919544
             AEA50102033823200221582066EEA6A22678C3A9F83148EF349800B20ABB486F2C
             C6D7ED017EC49798C8D4372258202F25DE86812374E6E8D48DEE8E230AD29CCD
             839BE6E0DB8C7AB9DEDE0805D29D',

     / cca-realm-public-key-hash-algo-id /
     44240: "sha-256"
}

An example Realm claim map is shown below in COSE-DIAG format:

cca-platform-claims = (cca-platform-claim-map)

cca-platform-claim-map = {
    cca-platform-profile
    cca-platform-challenge
    cca-platform-implementation-id
    cca-platform-instance-id
    cca-platform-config
    cca-platform-lifecycle
    cca-platform-sw-components
    ? cca-platform-verification-service
    cca-platform-hash-algo-id
}

The CCA platform token claim map is defined as follows:

The CCA platform profile claim identifies the EAT profile to which the CCA platform token conforms. Note that because the platform token is expected to be issued when bound to a Realm token, the profile document should also include a description of thethe relevant Realm claimsprofile or a reference to that profile.

The CCA platform profile claim is identified using the EAT profile label (265).

The CCA platform profile claim must be present in a CCA platform token.

cca-platform-profile-label = 265 ; EAT profile

cca-platform-profile-type = "http://armtag:arm.com/CCA-SSD/,2023:cca_platform#1.0.0"

cca-platform-profile = (
    cca-platform-profile-label => cca-platform-profile-type
)

The format of the CCA platform profile claim is defined as follows:

The CCA platform challenge claim contains a hash of the public key used to sign the Realm token.

The CCA platform challenge claim is identified using the EAT nonce label (10).

The length of the CCA platform challenge is either 32, 48 or 64 bytes.

The CCA platform challenge claim must be present in a CCA platform token.

cca-hash-type = bytes .size 32 / bytes .size 48 / bytes .size 64
cca-platform-challenge-label = 10

cca-platform-challenge = (
    cca-platform-challenge-label => cca-hash-type
)

The format of the CCA platform challenge claim is defined as follows:

The CCA platform Implementation ID claim uniquely identifies the implementation of the CCA platform.

The value of the CCA platform Implementation ID claim can be used by a verification service to locate the details of the CCA platform implementation from an endorser or manufacturer. Such details are used by a verification service to determine the security properties or certification status of the CCA platform implementation.

The semantics of the CCA platform Implementation ID value are defined by the manufacturer or a particular certification scheme. For example, the ID could take the form of a product serial number, database ID, or other appropriate identifier.

The CCA platform Implementation ID claim does not identify a particular instance of the CCA implementation.

The CCA platform Implementation ID claim must be present in a CCA platform token.

cca-platform-implementation-id-label = 2396 ; PSA implementation ID
cca-platform-implementation-id-type = bytes .size 32

cca-platform-implementation-id = (
    cca-platform-implementation-id-label => cca-platform-implementation-id-type
)

The format of the CCA platform Implementation ID claim is defined as follows:

The CCA platform Instance ID claim represents the unique identifier of the Initial Attestation Key (IAK) for the CCA platform.

The CCA platform Instance ID claim is identified using the EAT ueid label (256).

The CCA platform Instance ID claim must be present in a CCA platform token.

cca-platform-instance-id-label = 256 ; EAT ueid

; TODO: require that the first byte of cca-platform-instance-id-type is 0x01
; EAT UEIDs need to be 7 - 33 bytes
cca-platform-instance-id-type = bytes .size 33

cca-platform-instance-id = (
    cca-platform-instance-id-label => cca-platform-instance-id-type
)

The format of the CCA platform Instance ID claim is defined as follows:

The CCA platform config claim describes the set of chosen implementation options of the CCA platform. As an example, these may include a description of the level of physical memory protection which is provided.

The CCA platform config claim must be present in a CCA platform token.

The CCA platform lifecycle claim identifies the lifecycle state of the CCA platform.

The CCA platform lifecycle claim must be present in a CCA platform token.

A non debugged CCA platform will be in psa-lifecycle-secured state. Realm Management Security Domain debug is always recoverable, and would therefore be represented by psa-lifecycle-non-psa-rot-debug state. Root world debug is recoverable on a HES system and would be represented by psa-lifecycle-recoverable-psa-rot state. On a non-HES system Root world debug is usually non-recoverable, and would be represented by psa-lifecycle-lifecycle-decommissioned state.

cca-platform-lifecycle-label = 2395 ; PSA lifecycle

cca-platform-lifecycle-unknown-type = 0x0000..0x00ff
cca-platform-lifecycle-assembly-and-test-type = 0x1000..0x10ff
cca-platform-lifecycle-cca-platform-rot-provisioning-type = 0x2000..0x20ff
cca-platform-lifecycle-secured-type = 0x3000..0x30ff
cca-platform-lifecycle-non-cca-platform-rot-debug-type = 0x4000..0x40ff
cca-platform-lifecycle-recoverable-cca-platform-rot-debug-type = 0x5000..0x50ff
cca-platform-lifecycle-decommissioned-type = 0x6000..0x60ff

cca-platform-lifecycle-type =
    cca-platform-lifecycle-unknown-type /
    cca-platform-lifecycle-assembly-and-test-type /
    cca-platform-lifecycle-cca-platform-rot-provisioning-type /
    cca-platform-lifecycle-secured-type /
    cca-platform-lifecycle-non-cca-platform-rot-debug-type /
    cca-platform-lifecycle-recoverable-cca-platform-rot-debug-type /
    cca-platform-lifecycle-decommissioned-type

cca-platform-lifecycle = (
    cca-platform-lifecycle-label => cca-platform-lifecycle-type
)

The format of the CCA platform lifecycle claim is defined as follows:

The CCA platform software components claim is a list of software components which can affect the behavior of the CCA platform. It is expected that an implementation will describe the expected software component values within the profile.

The CCA platform software components claim must be present in a CCA platform token.

cca-platform-sw-components-label = 2399 ; PSA software components

cca-platform-sw-component = {
  ? 1 => text,          ; component type
    2 => cca-hash-type, ; measurement value
  ? 4 => text,          ; version
    5 => cca-hash-type, ; signer id
  ? 6 => text,          ; hash algorithm identifier
}

cca-platform-sw-components = (
    cca-platform-sw-components-label => [ + cca-platform-sw-component ]
)