Skip to content

Commit

Permalink
[keymgr, doc] Update diversification inputs
Browse files Browse the repository at this point in the history 
For better alignment with the NIST standards, we
have updated how diversification inputs are consumed
during advance calls. The RTL/DV change was resolved
in #22878.

This commit updates the identity and keys documentation
to match these previously merged changes.

Signed-off-by: Fatih Balli <[email protected]>
  • Loading branch information
@ballifatih @timothytrippel
ballifatih authored and timothytrippel committed Oct 2, 2024
1 parent 3362011 commit d897544
Show file tree
Hide file tree
Showing 3 changed files with 59 additions and 53 deletions.
99 changes: 51 additions & 48 deletions doc/security/specs/identities_and_root_keys/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -101,8 +101,8 @@ injective. This can be achieved by fixing the width of all the operands.

```
CreatorRootKey = KM_DERIVE(RootKey,
DiversificationKey | HealthStateMeasurement | DeviceIdentifier |
ROMExtSecurityDescriptor | HardwareRevisionSecret)
HardwareRevisionSecret | RomHash | HealthStateMeasurement |
DeviceIdentifier | ROMExtSecurityDescriptor)
```

<table>
Expand All @@ -121,59 +121,52 @@ Hidden from software once personalization is complete.
</td>
</tr>
<tr>
<td id="diversification-key">DiversificationKey</td>
<td>Flash</td>
<td>HardwareRevisionSecret</td>
<td>Gates</td>
<td>
Additional diversification key stored in flash. Provisioned at
manufacturing time by the Silicon Creator.

Hidden from software once provisioned.
Encoded in gates. Provisioned by Silicon Creator before tapeout. Hidden from
software.
</td>
</tr>
<tr>
<td>ROMExtSecurityDescriptor</td>
<td>SW register</td>
<td id="rom-hash">RomHash</td>
<td>Computed by ROM controller</td>
<td>
The implementation may choose one of the following options:

1. Hash of the ROM extension. Changes in the ROM extension code will trigger an
update of the Creator Identity.
2. Use a software binding tag stored in the ROM_EXT manifest. This is to
retain the Creator Identity across validated updates of the ROM_EXT.
The implementation may opt to use the software binding interface
described in later sections to fulfill this property.
SHA-3-256 hash of the ROM image.
</td>
</tr>
<tr>
<td>DeviceIdentifier</td>
<td>OTP</td>
<td>Health State Measurement</td>
<td>Computed by Lifecycle controller</td>
<td>
Provisioned at manufacturing time. Readable from software and JTAG interface.
Comprises the following measurements:

* Device life cycle state.
* Debug mode state.

The debug mode shall be used as well if there are multiple debug configurations
supported by a single life cycle state.
</td>
</tr>
<tr>
<td>HardwareRevisionSecret</td>
<td>Gates</td>
<td>DeviceIdentifier</td>
<td>OTP</td>
<td>
Encoded in gates. Provisioned by Silicon Creator before tapeout. Hidden from
software.
Provisioned at manufacturing time. Readable from software and JTAG interface.
</td>
</tr>
<tr>
<td>Health State Measurement</td>
<td>Register (ROM stage)</td>
<td>ROMExtSecurityDescriptor</td>
<td>SW register</td>
<td>
Comprises the following measurements:

* Device life cycle state.
* Debug mode state.
* ROM Hash.

Some values are read from the device life cycle controller. The device life
cycle state should be consumed by the ROM stage.
The implementation may choose one of the following options:

The debug mode shall be used as well if there are multiple debug configurations
supported by a single life cycle state.
1. Hash of the ROM extension. Changes in the ROM extension code will trigger an
update of the Creator Identity.
2. Use a software binding tag stored in the ROM_EXT manifest. This is to
retain the Creator Identity across validated updates of the ROM_EXT.
The implementation may opt to use the software binding interface
described in later sections to fulfill this property.
</td>
</tr>
</table>
Expand Down Expand Up @@ -243,7 +236,7 @@ The `OwnerIntermediateKey` is generated as follows:

```
OwnerIntermediateKey =
KM_DERIVE(CreatorRootKey, OwnerRootSecret | SoftwareBindingValue)
KM_DERIVE(CreatorRootKey, CreatorSecret | SoftwareBindingValue)
```

<table>
Expand All @@ -253,18 +246,13 @@ OwnerIntermediateKey =
<td><strong>Description</strong></td>
</tr>
<tr>
<td id="owner-root-secret">OwnerRootSecret</td>
<td> id="creator-secret"CreatorSecret</td>
<td>Flash</td>
<td>
Used as a diversification constant with acceptable entropy. Provisioned at
Ownership Transfer time by the Silicon Creator.

The OwnerRootSecret has different visibility options depending on the level of
isolation provided in hardware:
Additional diversification key stored in flash. Provisioned at
manufacturing time by the Silicon Creator.

* The value should be hidden from software after provisioning.
* The value is visible to ROM and ROM Extension, but hidden from all Silicon
Owner software. The ROM Extension implements this property.
Hidden from software once provisioned.
</td>
</tr>
<tr>
Expand Down Expand Up @@ -326,7 +314,7 @@ The key manager supports the generation of versioned keys with lineage to the

```
OwnerRootKey =
KM_DERIVE(OwnerIntermediateKey, SoftwareBindingValue)
KM_DERIVE(OwnerIntermediateKey, OwnerRootSecret | SoftwareBindingValue)
VersionedKey = KM_DERIVE(OwnerRootKey,
KeyVersion | KeyID | Salt | SoftwareExportConstant)
Expand All @@ -341,6 +329,21 @@ width of all the operands.
<td><strong>Encoding</strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td id="owner-root-secret">OwnerRootSecret</td>
<td>Flash</td>
<td>
Used as a diversification constant with acceptable entropy. Provisioned at
Ownership Transfer time by the Silicon Creator.

The OwnerRootSecret has different visibility options depending on the level of
isolation provided in hardware:

* The value should be hidden from software after provisioning.
* The value is visible to ROM and ROM Extension, but hidden from all Silicon
Owner software. The ROM Extension implements this property.
</td>
</tr>
<tr>
<td>OwnerRootKey</td>
<td>Internal RAM</td>
Expand Down
2 changes: 1 addition & 1 deletion ...security/specs/identities_and_root_keys/identities_and_root_keys_DICE_fig1b.svg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
11 changes: 7 additions & 4 deletions hw/ip/keymgr/doc/theory_of_operation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,15 +53,17 @@ When transitioning from `Initialized` to this state, a KMAC operation is invoked
The output of the KMAC operation replaces the previous value of the internal key, and the new value becomes the `CreatorRootKey`.

Inputs to the derivation function are:
* `DiversificationKey`: Secret seed from flash
* `HardwareRevisionSecret`: A global design time constant.
* `ROMHash`: SHA-3-256 hash of the ROM image.
* `HealthMeasurement`: Current life cycle state
* To avoid a state value corresponding to each life cycle state, the raw life cycle value is not used.
* Instead, certain life cycle states diversify the same way.
* Please see the life cycle controller for more details.
* `DeviceIdentifier`: Unique device identification.
* `HardwareRevisionSecret`: A global design time constant.
* `SoftwareBinding`: A software programmed value related to ROMExt.


Other than the `DiversificationKey` and `HardwareRevisionSecret`, none of the values above are considered secret.
Other than `HardwareRevisionSecret`, none of the values above are considered secret.

Once the `CreatorRootKey` is reached, software can request key manager to advance state, generate output key or generate output identity.
The key used for all 3 functions is the `CreatorRootKey`.
Expand All @@ -77,7 +79,7 @@ This state is reached through another invocation of the KMAC operation using the
The output of the KMAC operation replaces the previous value of the internal key, and the new value becomes the `OwnerIntermediateKey`.

The relevant data inputs are:
* `OwnerRootSecret`: Secret seed from flash.
* `CreatorSecret`: A secret seed from flash determined by the SiliconCreator.
* `SoftwareBinding`: A software programmed value representing the first owner code to be run.

Once the `OwnerIntermediateKey` is created, software can request key manager to advance state, generate output key or generate output identity.
Expand All @@ -92,6 +94,7 @@ This state is reached through another invocation of the KMAC operation using the
The output of the KMAC operation replaces the previous value of the internal key, and the new value becomes the `OwnerRootKey`.

The relevant inputs are:
* `OwnerRootSecret`: Secret seed from flash.
* `SoftwareBinding` - A software programmed value representing the owner kernel code.

Once the `OwnerRootKey` is created, software can request key manager to advance state, generate output key or generate output identity.
Expand Down

0 comments on commit d897544

Please sign in to comment.