NVIDIA Tegra
NVIDIA DRIVE OS 5.1 Linux SDK

Developer Guide
5.1.6.0 Release


 
Understanding Security
 
Root of Trust and Chain of Trust
NVIDIA Chain of Trust
Secure Boot
Fuse Burning Responsibilities
What is a Trusted OS?
Trusted Operating System Virtualization
Global Platform API Wrapper
TEE Secure Storage
Secure Counter
Installing the Infrastructure
User Data Encryption on Linux
Enabling JTAG Support on Secure Targets
Encrypted Key Storage in eMMC
Factory Secure Key Provisioning
The Fuse Burning Toolkit
Fuse Blob Format
Linux-based Disk Encryption
The following acronyms are used throughout this topic.
Term
Definition
ATF
ARM trusted firmware
BCT
Boot Configuration Table
BDT
Boot Device Tree
BR
BootROM
BR-BCT
BootROM Boot Configuration Table
CA
Client Applications
CBC
Cipher Block Chaining
CMAC
a block of Cipher-based Message Authentication code algorithm
ECDSA
Elliptic Curve Digital Signature Algorithm
EdDSA
Edwards-curve Digital Signature Algorithm
EKS
Encrypted Key Storage
GP API
Global Platform Application Programming Interface
HW
Hardware
JTAG
Joint Test Action Group IEEE 1149.1 Standard Test Access Port and Boundary-Scan Architecture
KEK
Key Encryption Key
LUKS
Linux Unified Key Setup disk encryption specification
ODM
Original Design Manufacturing
OEM
Original Equipment Manufacturer
OpenSSL
A general purpose cryptography library that provides an open source implementation of the Secure Sockets Layer protocol.
OS
Operating System
OSC
Oscillator
OTA
Over-the-Air
PCT
Platform Configuration Table
PKC
Public Key Cryptography
PolarSSL
also known as ARM-mbed
REE
Rich Execution Environment
ROM
Read-only Memory
RPMB
Replay protected memory block
RSA
An encryption mechanism that uses public and private keys.
RSASSA-PSS
RSA Signature Scheme with Appendix- Probabilistic Signature Scheme (cryptography)
SBK
Secure Boot Key
SDK/PDK
Software Development Kit / Platform Development Kit
SDRAM
Synchronous Dynamic Random Access Memory
SS
Secure Storage
TA
Trusted Applications
TEE
Trusted Execution Environment
TOS
Trusted Operating System
TSC
Tegra Secure Container
UID
Unique Identification
UUID
Universal Unique Identification
VM
Virtual Machine
Root of Trust and Chain of Trust
In a chain of trust, the trustworthiness of each layer of software that composes the chain is guaranteed by the previous layer, until reaching the root of the chain, or root of trust. Immutability and formal verification provide the foundation for a root of trust.. An example is the code present in read-only memory (ROM). The root of trust initiates the chain of trust.
A chain of trust, for example, can include: bootROM to boot loader to TrustZone operating system.
NVIDIA Chain of Trust
The bootROM combined with NVIDIA-programmed fuses constitute the root of trust in the boot process. BootROM is the instruction read-only memory written by NVIDIA, embedded into the hardware, and executed first upon every boot. BootROM initiates the chain of trust and hands it off to the ODM by authenticating and then invoking ODM-owned code (boot loader) with an ODM fuse programmed key.
Secure Boot
 
Public-Key Cryptography
Secure Boot Details with PKC Protection
PKC Secure Boot Requirements
RSA Validation of the BCT and Boot Loader
ECDSA or EdDSA Authentication of the BCT and Boot Loader
RSA Secured USB Recovery Mode
ECDSA or EdDSA Secured USB Recovery Mode
Security Engine Key Slot Usage
Secure boot:
Must be implemented and enabled during manufacturing.
Cannot be enabled over OTA or in the field.
Defines a chain of trust.
Is supported by hardware from power on to boot ROM to boot loader.
Must be implemented by the boot loader.
NVIDIA DRIVE devices establish the chain of trust with these boot sequences:
PKC-protected boot sequence
RSA 3K signature
EdDSA signature
The FUSE_BOOT_SECURITY_INFO on NVIDIA DRIVE devices determines which sequence is used. The information in the FUSE_BOOT_SECURITY_INFO bits is as follows:
Bit[7, 1:0]: authentication scheme
x10b: PKC-protected boot sequence with RSA 3K key pairs
111b: PKC-protected boot sequence with EdDSA key
Public-Key Cryptography
Public Key Cryptography relies on a public and private key pair, allowing the manufacturer to sign a boot loader and BCT with its private key, never needing to disclose the private key at any time during the manufacturing process. The public key, which is used to verify the digital signature of the boot loader and BCT, gets stored on the secondary boot device or embedded into the boot loader and BDT images. Using PKC allows devices to be manufactured at facilities that are not secure.
Secure Boot Details with PKC Protection
The PKC-protected boot sequence is as follows. The sequence is part of the NVIDIA Secure Solutions infrastructure, which includes:
NvImageGen utility—manages the RSA key pairs, ECDSA key, or EdDSA key and produces secure data that includes the BCT, which can contain the BCT signatures and the public key.
Boot ROM—Tegra devices contain a boot ROM that adds support for the PKC-protected boot sequence.
The NVIDIA Secure Solutions infrastructure and the PKC-protected boot sequence ensure that the device is flashed with a BCT and boot loader that the OEM/Integrator has signed. The signature uses the private key from the RSASSA-PSS key pair, ECDSA key, or EdDSA key. The boot ROM validates the signatures and boot loader with the public key, which is stored in BCT. An SHA-256 hash of the public key is fused into the device.
The fused public key establishes the chain of trust for authenticating the BCT and boot loader. With the fused public key, the boot ROM verifies that the BCT and boot loader are from the OEM and have not modified after they are signed.
A fuse on your board selects the PKC-protected boot sequence.
If the fuse is set to 0x2 (FUSE_BOOT_SECURITY_INFO[7, 1:0]=2), the boot ROM uses the PKC-protected boot with RSA 3K signature.
Similarly, if the fuse is set to 0x83, the boot ROM uses the PKC-protected boot with EdDSA signature.
If bit 2 of the fuse is set to 0x1, the boot ROM uses the SBK-protected boot sequence.
 
Note:
SBK-protected boot is NOT supported in this release.
PKC Secure Boot Requirements
For the PKC-secured boot process to be used, these conditions must be met. These requirements must be implemented in production because secure boot cannot be implemented using OTA onto previously non-secure boot devices.
The fused PKC public key hash must be non-zero.
The FUSE_BOOT_SECURITY_INFO[7,1:0] must set to 0x2 or 0x83.
Where:
0x2 is for RSA 3K
0x83 is for EdDSA
The OEM must amend the BCT and the software components with public keys and digital signatures. Use the NvImageGen for this task.
The ODM Production Mode, Security Mode, fuse must be burned and it must be the last fuse to be burned.
RSA Validation of the BCT and Boot Loader
The boot ROM verification process that ensures the BCT is from the OEM, is as follows. The boot ROM uses this sequence when the conditions in PKC Secure Boot Requirements are satisfied.
Note:
SHA-256 is the hash function used during any RSASSA-PSS operations (signature verification) in the steps below. As recommended by PKCS #1 v2.1: RSA Cryptography Standard, the manufacturer must also use SHA-256 as the same hash function applied to the message. In addition, the salt length used in the RSASSA-PSS signature verification and signature generation is the length of SHA-256 hash.
1. The boot ROM loads the RSA public key modulus into the PKC SE key slot.
2. The boot ROM reads and validates the BCT:
Reads the BCT from secondary storage and validates the public key by computing SHA-256 hash and comparing it with values in fuses. If they match, the public key is stored to the PKC SE slot. The public key is used to decrypt the BCT and boot loader signature. Subsequent steps use fused public key to identify the decrypted version of the fused public key.
The public key as well as the RSASSA-PSS signature S is contained in the BCT.
Note:
The public exponent e is assumed to always be 0x10001, so it is not stored.
For NVIDIA DRIVE AGX Xavier, the public key is 3072 bits.
The boot ROM performs a RSASSA-PSS-VERIFY signature verification operation of the BCT using the verified public key. This step validates the RSASSA-PSS signature S of the BCT. If the result of the signature verification step is a valid signature, it continues the secure boot process. If the hash comparison fails, the boot ROM retries this step with the remaining 63 redundant copies of the BCT that are supported before the boot ROM gives up and goes to RCM.
Note:
Some copies of the BCT may have failed the public key hash compare in the beginning of Step 2, so the number of redundant copies of the BCT still available may be less than the actual number of redundant copies of the BCT written to secondary storage.
3. The Boot ROM reads and validates the boot loader:
Reads the boot loader data from secondary storage and uses the RSA public key to decrypt the boot loader signature.
The RSASSA-PSS signature S gets stored in the beginning of the boot loader image in the generic signature header. The BR performs a RSASSA-PSS-VERIFY signature verification operation of the boot loader. If the result of the signature verification step is a valid signature, it continues the secure boot process and the chain-of-trust is transferred to the validated boot loader. If the signature verification fails, the BR retries this step for up to three additional copies of the boot loader from secondary storage that are supported before the boot ROM gives up and goes to RCM.
Note:
NVIDIA DRIVE AGX Xavier: the signature is verified on the image header; where the header embedded the hash value of the bootloader image.
4. The boot loader is copied to the destination, generally to SDRAM due to size.
5. The boot ROM locks down security features, clears out state information, and then transfers control to the boot loader.
6. The boot loader continues the root of trust:
Write protects mass storage location of the boot loader and OS.
Passes execution to the validated OS image.
ECDSA or EdDSA Authentication of the BCT and Boot Loader
Use these instructions to understand the process the boot ROM uses to verify that the BCT is trusted. The boot ROM performs this process when the conditions in PKC Secure Boot Requirements are satisfied.
Note:
NVIDIA DRIVE AGX Xavier:
Support is provided for EdDSA operations (signature verification) using SHA-512 has function.
Curve25519 is the elliptic curve supported.
1. The boot ROM reads and authenticates the BCT:
First, the boot ROM reads the BCT from secondary storage and verifies the public key by computing the SHA-256 hash and comparing it with the values in the fuses. If they match, the public key is used to verify the BCT and boot loader signature.
Then the boot ROM verifies the BCT’s ECDSA or EdDSA signature using the verified public key. If the signature is verified, the secure boot process continues. If either the SHA-256 hash comparison or the signature comparison fails, the boot ROM retries this step with the remaining 63 redundant copies of the BCT. If verification fails with all 63 copies, the boot ROM gives up and goes to RCM.
2. The Boot ROM reads and verifies the boot loader:
First, the boot ROM reads the boot loader data from secondary storage and uses the ECDSA or EdDSA public key to verify the boot loader signature.
Next, the boot ROM stores the ECDSA or EdDSA signature at the beginning of the boot loader image in the generic signature header.
The boot ROM then verifies the boot loader using the ECDSA or EdDSA signature. If the signature is verified, the secure boot process continues, and the chain-of-trust is transferred to the verified boot loader. If signature verification fails, the boot ROM retries this step for up to three additional copies of the boot loader from secondary storage before it gives up and goes to RCM.
Note:
NVIDIA DRIVE AGX Xavier: the signature is verified on the image header; where the header embedded the hash value of the bootloader image.
3. The boot ROM copies the boot loader to the destination, generally an SDRAM, and then transfers control to the boot loader.
4. The boot loader continues the root of trust by:
Protecting the mass storage location of the boot loader and OS.
Passing execution to the validated OS image.
RSA Secured USB Recovery Mode
RCM can be secured with PKC-based authentication, using the same general authentication flow described in RSA Validation of the BCT and Boot Loader. Use these modifications when securing RCM with an RSA signature:
1. The boot ROM receives an RCM message.
2. The boot ROM authenticates the RSA public key from the RCM header by comparing the SHA-256 hash of the public key in the RCM header with the SHA-256 hash of the public key stored in fuses.
If the public key is authenticated, the boot ROM loads the public key into an RSA key slot for RSASSA-PSS-VERIFY operations.
If the public key in the RCM message header fails authentication, it returns a validation failure message to the USB host. The public key in subsequent RCM messages will not be validated. The boot ROM will use the authenticated public key already loaded in the SE RSA key slot.
3. The boot ROM validates the RCM message with an RSASSA-PSS-VERIFY operation.
If the authentication of the RCM message fails, it returns a validation failure message to the USB host.
If the authentication of the RCM message passes, it executes the RCM command as indicated in the RCM header.
If the RCM message is not a “Download & Execute” command, the boot ROM will receive more RCM messages sent from the USB host.
If the RCM message is a “Download & Execute” command, the boot ROM will exit, and execute the RCM payload.
Note:
As part of the regular boot ROM exit path, the RSA key slots are zeroed out.
ECDSA or EdDSA Secured USB Recovery Mode
RCM can be secured with ECDSA or EdDSA authentication using the same general authentication flow described in ECDSA or EdDSA Authentication of the BCT and Boot Loader. Use these modifications when securing RCM with ECDSA or EdDSA:
1. The boot ROM receives an RCM message.
2. The boot ROM authenticates the public key from the RCM header by comparing the SHA-256 hash of the public key in the RCM header with the SHA-256 hash of the public key stored in the fuses.
If the public key is authenticated, the boot ROM uses the public key for ECDSA or EdDSA operations.
If the public key in the RCM message header fails authentication, the boot ROM returns a validation failure message to the USB host.
3. The boot ROM validates the RCM message with an ECDSA or EdDSA operation.
If RCM message authentication fails, the boot ROM returns a validation failure message to the USB host.
If RCM message authentication succeeds, the boot ROM executes the RCM command indicated in the RCM header.
If the RCM message is not a “Download & Execute” command, the boot ROM receives more RCM messages sent from the USB host.
If the RCM message is a “Download & Execute” command, the boot ROM exits, and the RCM payload executes.
Security Engine Key Slot Usage
The Security Engine key slots that are loaded with various keys by BootROM are as follows:
Key
Key Slot
KEK0
13
KEK1
12
KEK2
11
KEK256
13
SBK
14
SSK
15
Fuse Burning Responsibilities
 
Fusing a Board with a PKC Public Key Hash
Generating a PKC Key Pair Using OpenSSL
Fusing the Board with the Secure Keys
Setting Up the Platform for Secure Boot
BR BCT Signing and Hash Compression
Applications can program a fuse by applying voltage using fuse burning routines found in the boot loader and the kernel APIs. The fuses and ownership required for Secure Boot are as follows:
NVIDIA Programmed
128-bit Unique ID (UID), no two Tegra chips have the same UID.
NVIDIA production mode
Customer Programmed and Owned
FUSE_BOOT_SECURITY_INFO
Public key encoded as SHA-256.
ODM Production Mode (FUSE_SECURITY_MODE)
Caution:
ODM Production Mode fuse disables further fuse burning except reserved ODM fuses. Therefore, burn the ODM Production Mode fuse last.
Fusing a Board with a PKC Public Key Hash
Devices that implement secure boot with PKC protection have certain requirements regarding blowing fuses and boot loader signing. This topic explains how to fuse the PKC public key hash.
To fuse a board with a PKC public key hash you must have performed the following tasks:
1. Choose one of these options:
Generating a PKC Key Pair Using PolarSSL on Parker SoC
—Or—
Generating a PKC Key Pair Using OpenSSL
Note:
EdDSA private key can be generated using OpenSSL Version 1.1.1.
OpenSSL Version 1.1.x changed its default digest from MD5 to SHA256.
Adding the -md md5 option for encryption and decryption resolves unexpected behavior.
2. Generating Signed Binaries and a PKC Hash
3. Fusing the Board with the Secure Keys
Generating a PKC Key Pair Using OpenSSL
Use these procedures to generate a PKC key pair using OpenSSL.
To install OpenSSL
1. If you are generating only the RSA pair, install the OpenSSL package with the command:
sudo apt-get install openssl
2. If you are generating the EdDSA key pair, proceed to the instructions for generating the ECDSA key pair.
To generate a EdDSA key pair for NVIDIA DRIVE AGX Xavier
1. Download and extract the OpenSSL EdDSA/ED25519 key support OpenSSL Version 11.1 Pre-8 available at:
https://openssl.org
2. Build OpenSSL as follows:
In a terminal window, navigate to the directory where you extracted OpenSSL and execute these commands:
./config
make
Once the OpenSSL build is completed, copy libcrypto.so* and libssl.so* to your local /lib/ directory.
To generate the keys, execute OpenSSL from the application folder in the directory where you extracted OpenSSL.
For more information, consult the OpenSSL README file in the extracted source directory.
3. Generate EdDSA private key with the command:
openssl genpkey -algorithm Ed2551 --out keyfile.pem
You are now ready to generate the signed binaries and PKC hash.
To generate a PKC hash
1. Run these commands on the host to generate a public key (for ECDSA or EdDSA) and a PKC hash.
For NVIDIA DRIVE AGX Xavier RSA 3072-bit keys:
$# cd drive-t186ref-foundation
$# ./tools/host/flashtools/flash --pkc <private_key_filename> --chip 0x19
Where <private_key_filename> depends on the tool used to generate the key.
For PolarSSL, use rsa_priv.txt.
For OpenSSL, use rsa_priv.pem.
Where:
<public_key_filename> is the name you want to give the public key file.
<private_key_filename> is depends on the tool used to generate the key.
For PolarSSL, use keyfile.key.
For OpenSSL, use keyfile.pem.
For NVIDIA DRIVE AGX Xavier EdDSA:
$ cd drive-<TBD_platform_ver>-foundation
$ ./tools/host/flashtools/flash/tegrasign_v2 --key <private_key_filename> --pubkeyhash <public_key_filename>
$ ./tools/host/flashtools/flash/tegrakeyhash -ed25519 <public_key_filename> --chip 0x19
Where:
<public_key_filename> is the name you want to give the public key file.
<private_key_filename> is depends on the tool used to generate the key.
For OpenSSL, use keyfile.pem.
Example Output
Example of the output of the tegrakeyhash command, when a PolarSSL key is supplied, is as follows:
# PKC key in PolarSSL format
# sha256 hash:
# bytes:
# 0xef, 0xcd, 0xab, 0x89, 0x67, 0x45, 0x23, 0x01,
# 0xef, 0xcd, 0xab, 0x89, 0x67, 0x45, 0x23, 0x01,
# 0xef, 0xcd, 0xab, 0x89, 0x67, 0x45, 0x23, 0x01,
# 0xef, 0xcd, 0xab, 0x89, 0x67, 0x45, 0x23, 0x01,
#
# tegra-fuse format: 0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
#
# fuse bypass format:
# FAB_ENTRY(PUBLIC_KEY0, PUBLIC_KEY0, 0x89abcdef),
# FAB_ENTRY(PUBLIC_KEY1, PUBLIC_KEY1, 0x01234567),
# FAB_ENTRY(PUBLIC_KEY2, PUBLIC_KEY2, 0x89abcdef),
# FAB_ENTRY(PUBLIC_KEY3, PUBLIC_KEY3, 0x01234567),
# FAB_ENTRY(PUBLIC_KEY4, PUBLIC_KEY4, 0x89abcdef),
# FAB_ENTRY(PUBLIC_KEY5, PUBLIC_KEY5, 0x01234567),
# FAB_ENTRY(PUBLIC_KEY6, PUBLIC_KEY6, 0x89abcdef),
# FAB_ENTRY(PUBLIC_KEY7, PUBLIC_KEY7, 0x01234567),
 
2. The tegra-fuse format can be used in FSKP Fuse Burning Tool.
<fuse name="PublicKeyHash" size="32" value="0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"/>
Fusing the Board with the Secure Keys
The BSP provides Fuse Burning Tool for fusing the board with the PKC hash. Sample XML files to burn secure keys and enable PKC protection are as follows.
For NVIDIA DRIVE AGX Xavier RSA:
<genericfuse MagicId="0x45535546" version="1.0.0">
<fuse name="PublicKeyHash" size="32" value="0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"/>
<fuse name="BootSecurityInfo" size="4" value="0x2"/>
<fuse name="SecurityMode" size="4" value="0x1"/>
</genericfuse>
For NVIDIA DRIVE AGX Xavier EdDSA:
<genericfuse MagicId="0x45535546" version="1.0.0">
<fuse name="PublicKeyHash" size="32" value="0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"/>
<fuse name="BootSecurityInfo" size="4" value="0x83"/>
<fuse name="SecurityMode" size="4" value="0x1"/>
</genericfuse>
 
Warning:
If used, the SecurityMode must be the last fuse command in the XML file. The FSKP fuse burning tool burns fuses in the order specified in the XML file. After burning the SecurityMode fuse, it disables fuse burning.
Setting Up the Platform for Secure Boot
1. Generate the PKC Key and ensure ODM production fuse is burned.
Generate a PKC Key Pair Using PolarSSL
Generate a PKC Key Pair Using OpenSSL
Ensure the ODM production fuse is burned.
2. Consult the instructions for fusing the secure keys in Factory Secure Key Provisioning.
 
Warning:
This step is irreversible, ensure that:
The PKC key pair is a valid key pair.
The PKC key pair is stored in a secure location, because all the binaries must be signed with the private key.
3. Sign and flash the binaries.
Use “-p <private_key_filename>” option when running the bootburn.sh script.
Where <private_key_filename> depends on the tool used to generate the key:
For PolarSSL, use rsa_priv.txt for RSA, or keyfile.key for ECDSA.
For OpenSSL, use rsa_priv.pem for RSA, or keyfile.pem for both ECDSA and EdDSA.
BR BCT Signing and Hash Compression
The data section in BR BCT is signed with a zero-key AES CMAC, and the last 16 bytes of this section are used to store the hash value. If a value has never been stored there, those bytes contain a known pattern that indicates to the update tool that no hash value is present.
During boot the hash value is computed and compared with the stored value. If the update tool does not find a matching stored value, or if it finds that no value is present, the tool stores the computed value.
What is a Trusted OS?
 
Trusted Execution Environment Secure Storage
Development Mode
Secure Storage Flow
A trusted OS is a trusted piece of software that runs in a secure and trusted environment and is based on ARM TrustZone technology. For more information consult:
https://www.arm.com/products/security-on-arm/trustzone
NVIDIA platforms use a customized version of Trusty as the Trusted OS.
For more information consult:
https://source.android.com/security/trusty
A high-level architecture of Trusted OS is as follows.
Trusted OS includes software components that provide a Trusted Execution Environment (TEE) on the platform. The components that are a part of Trusted OS include:
Rich Execution Environment (REE): consists of kernel drivers, client applications, and some user space libraries. All requests originate from the CAs and the kernel helps calling into the other side by executing an smc command.
ARM Trusted FW (ATF): secure monitor firmware. This handles all communications between the non-secure and secure worlds by activating and deactivating the appropriate environment and by routing function calls to the appropriate Trusted OS callbacks.
Trusted Environment trusted OS: consists of trusted kernel, trusted applications (TAs), which act as secure service providers, and a set of kernel and user space libraries.
TAs are identified by a Universal Unique IDs (UUID), their definition can found inside the manifest file of a TA application.
Typically, a TA running in the Trusted Execution Environment (TEE) has a non-secure client application (CA) running in the Rich Execution Environment (REE). All communication from REE to TEE is synchronous and driven by the REE.
To communicate with a specific TA, specify the UUID of that TA as one of the input parameters, in addition to any other context that needs to be passed across. It is worth noting that TA -> TA communication is also supported inside the trusted OS.
Trusted OS supports the following TAs:
Secure storage
Secure counter
Crypto services such as AES variants, RSA modes, various SHA modes, RNG
HW Security Engine to get a HW backed RNG
Program private keys into HW SE key slots to offload crypto operations to SE engine
Trusted Execution Environment Secure Storage
The Trusted Execution Environment secure storage is responsible for securely storing any private data of trusted applications running within the Trusted Execution Environment.
The secure storage solution provides:
Data confidentiality with AES-CTR-128 symmetric encryption.
Client Authentication, SHA-HMAC-256, for data reads and writes.
Protection against data rollback to older versions.
Secure storage software depends on hardware support to provide the necessary security as follows:
KEK1 and KEK2: fuses provisioned for encryption and authentication to work as expected.
RPMB device key: provisioned in eMMC/UFS storage for authentication and rollback protection to work as expected.
SECURITY_MODE_0: enforces authentication and rollback checking in the software.
Warning:
Prior to production, to ensure that secured storage works as expected, program all these keys.
Development Mode
During development, key values may not be identified. Consequently, to unblock development if SECURITY_MODE_0 fuse is not provisioned on the device under test, the software switches to soft-rpmb state where authentication and rollback protection is not enforced. The state-machine and the software paths between soft-rpmb and hw-rpmb are exactly the same except in the soft-rpmb state where the secure storage does not error out and fail the client.
Warning:
Once you move into production phase, the fuses and keys MUST be programmed.
The secure storage service is responsible for encrypting and securely storing data blobs on the guest OS file system. It also provides rollback protection using RPMB device.
The numbered interactions, provided in the secure storage flow diagram, are as follows.
Interaction
Description
1
The Trusted OS (TOS) daemon is blocked on an IOCTL call waiting to service the next secure storage request.
2
A CA makes an smc call into the secure world TA requesting some service.
3
Specific TA receives the call from the CA and over the course of its operation, suppose it needs to store any data securely, it calls secure storage TA to write/read/modify data.
4
SS TA receives the call, processes the request (encrypt/decrypt and packetize) and forwards the request to the TOS driver in NS world.
5
The TOS daemon collects the new request and issues the corresponding file operations and notifies the TOS driver that the request is complete.
Secure Storage Flow
The DRIVE AGX platform provides an interface library called ote_storage that exposes the interfaces to communicate with the secure storage service. The interfaces exposed by the library, and documentation for it, are inside ote_storage.h header file. It is part of the include directory in the Foundation package available at:
drive-t186ref-foundation/firmwares/src/trusted_os/ta-dev/
The sample_service2.c source provides an example of how to write a simple trusted application (TA) using the secure storage interfaces. The sample_service2 is invoked by the sample_client1 to store and read back a test string from storage.
NVIDIA® Trusted OS technology uses this top-level secure storage directory:
/data/ss
The Secure Storage TA places files in subdirectories under the top-level secure storage directory. The Secure Storage TA names subdirectories with the UUID of the secure storage client. It also encrypts and stores secure data in files in those subdirectories, where it can be subsequently decrypted and accessed.
A daemon running in non-secure space provides access to trusted OS. The daemon initiates these basic file operations, which the Secure Storage TA fulfills:
Create/delete
Open/close
Read/write
Getsize
Seek
Truncate
Trusted Operating System Virtualization
Multiple guest virtual machines may request security services from Trusted OS (TOS). TOS virtualization provides several design features to support this capability:
Multiple client applications (CAs) running on multiple VMs can communicate with TOS.
The system can be configured to restrict access to certain trusted applications (TAs) from any VM, using the platform configuration table (PCT).
Multiple CAs running in the same VM or different VMs can request trusted services from the same trusted application.
Secure storage is virtualized, and guest VMs can access only their data blobs.
Each TA manages a guest's context discretely.
By default, all VMs have access to all TAs running in TOS. If TAs are added or removed, the struct in the header file guest_config.h must also be modified.
.tos_cfg = {
.persistent_unique_id = 1,
.num_tos_apps = 7,
.tos_app_uuid[0] = SAMPLE_SERVICE1_UUID,
.tos_app_uuid[1] = SAMPLE_SERVICE2_UUID,
.tos_app_uuid[2] = SERVICE_STORAGE_UUID,
.tos_app_uuid[3] = SERVICE_NVCRYPTO_UUID,
.tos_app_uuid[4] = EFS_CRYPTO_UUID,
.tos_app_uuid[5] = SERVICE_RTC_UUID,
.tos_app_uuid[6] = TESTING_SERVICE_UUID
},
1. Set .num_tos_apps to the number of TAs.
Where n is the number of TAs.
2. Set the elements 0 through n‑1 of .tos_app_uuid to specify the UUID of the TA.
3. After updating guest_config.h, rebuild and re-flash the hypervisor. You need not make any changes on the TOS side to support the new settings.
Global Platform API Wrapper
 
Supported Data Types and Functions
Header files
Usage and Examples
Information about the GlobalPlatform APIs
Use the Global Platform API (GP API) wrapper to interface applications to the NVIDIA Trusted OS through the APIs defined by the GlobalPlatform TEE communication standard.
The GP API wrapper is implemented as a set of libraries that client applications (CAs) and trusted applications (TAs) can link to. These libraries support the functions defined by some of the GP APIs by calling native functions in the NVIDIA OTE library.
The GlobalPlatform API wrapper libraries support limited functionality.
Consult the list of supported CA-to-TA APIs
Consult the list of supported TA-to-TA APIs
Supported Data Types and Functions
The current implementation of the GP API wrapper libraries only support the following GP data types and GP API calls. Data types and API calls described as “implemented in wrapper” are implemented entirely inside the GP API wrapper libraries.
The GP API wrapper libraries also support the ability for TAs to access, store and manipulate Trusted Storage Data Objects. For the full list of supported Trusted Storage APIs, refer to the GP Trusted Storage APIs for Data table below. The current implementation of Trusted OS only supports Persistent Data Objects. Transient Objects and buffer/value attributes associated with Persistent Objects as part of the GP specification are currently unsupported.
Global Platform API Data Types
GP API Data Types
Equivalent OTE Data Types
TEEC_Result
te_error_t
TEEC_Context
Implemented in wrapper.
TEEC_Operation
te_operation_t
TEEC_Session
te_session_t
TEEC_UUID
te_uuid_t
TEEC_Value
Implemented in wrapper.
The OTE layer currently does not support two sub-values within one parameter. Only the value_a member is supported.
TEEC_SharedMemory
Implemented in wrapper.
TEEC_Parameter
Implemented in wrapper.
Supported CA to TA Communication APIs
GP CA to TA Communication APIs
Equivalent OTE APIs
TEEC_InitializeContext
Not currently supported.
TEEC_OpenSession
te_open_session
TEEC_CloseSession
te_close_session
TEEC_InvokeCommand
te_launch_operation
TEEC_FinalizeContext
Not currently supported.
TEEC_RegisterSharedMemory
Not currently supported.
TEEC_AllocateSharedMemory
Implemented in wrapper.
TEEC_ReleaseSharedMemory
Implemented in wrapper.
TEEC_RequestCancellation
Not currently supported.
Supported TA to TA Communication APIs
GP TA to TA Communication APIs
Equivalent OTE APIs
TA_CreateEntryPoint()
te_create_instance_iface()
TA_DestroyEntryPoint()
te_destroy_session_iface()
TA_OpenSessionEntryPoint()
te_open_session_iface()
TA_CloseSessionEntryPoint()
te_close_session_iface()
TA_InvokeCommandEntryPoint()
te_receive_operation_iface()
Global Platform Memory Management APIs
 
GP Memory Management APIs
Equivalent OTE APIs
TEE_Malloc
Implemented in wrapper.
TEE_Realloc
Implemented in wrapper.
TEE_Free
Implemented in wrapper.
TEE_MemMove
Implemented in wrapper.
TEE_MemFill
Implemented in wrapper.
Global Platform Trusted Storage Data Types
GP Trusted Storage Data Types
Equivalent OTE Data Types
TEE_Attribute
te_attribute_t
TEE_ObjectInfo
Implemented in wrapper.
TEE_Whence
te_storage_whence_t
TEE_ObjectHandle
Implemented in wrapper.
TEE_ObjectEnumHandle
Not currently supported.
TEE_Result
te_error_t
GP Trusted Storage APIs for Data
Equivalent OTE APIs
Generic Object Functions
TEE_GetObjectInfo1
Implemented in wrapper.
TEE_RestrictObjectUsage
Not currently supported.
TEE_GetObjectBufferAttribute
Not currently supported.
TEE_GetObjectValueAttribute
Not currently supported.
TEE_CloseObject
te_close_storage_object
Transient Object Functions
TEE_AllocateTransientObject
te_allocate_object
TEE_FreeTransientObject
te_free_object
TEE_PopulateTransientObject
te_free_object
TEE_InitRefAttribute
te_set_mem_attribute
TEE_InitValueAttribute
te_set_int_attribute
Persistent Object Functions
TEE_OpenPersistentObject
te_open_storage_object
TEE_CreatePersistentObject
te_create_storage_object
TEE_CloseAndDeletePersistentObject1
te_close_storage_object
te_delete_named_storage_object
TEE_RenamePersistentObject
Not currently supported.
Data Stream Access Functions
TEE_ReadObjectData
te_read_storage_object
TEE_Write_ObjectData
te_write_storage_object
TEE_TruncateObjectData
te_trunc_storage_object
TEE_SeekObjectData
te_seek_storage_object
Global Platform Cryptographic Data Types
GP Cryptographic Data Types
Equivalent OTE Data Types
TEE_OperationClass
Not currently supported.
TEE_OperationAlgorithm
Implemented in wrapper.
TEE_OperationMode
te_crypto_oper_algo_t
TEE_OperationMode
te_crypto_oper_algo_mode_t
TEE_OperationHandle
Implemented in wrapper.
GP Cryptographic APIs for Data
Equivalent OTE APIs
Generic Operation Functions
TEE_AllocateOperation
te_allocate_operation
TEE_FreeOperation
te_free_operation
TEE_GetOperationInfo
Implemented in wrapper.
TEE_SetOperationKey
te_set_operation_key
Symmetric Cipher Functions
TEE_CipherInit
te_cipher_init
TEE_CipherUpdate
te_cipher_update
TEE_CipherDoFinal
te_cipher_dofinal
Random Data Generation Functions
TEE_GenerateRandom
te_generate_random
Header files
The GlobalPlatform API wrapper header files are available at:
<top>/drive-t186ref-foundation/firmwares/src/trusted_os/ta-dev/include/lib/tee_lib
Usage and Examples
The NVIDIA Foundation Services provide two sample applications that illustrate usage of the GP API wrapper.
sample_client1_gp.c demonstrates usage of the GP API wrapper in a Client Application (CA). Refer to inline documentation in the source file for more verbose instructions about how to use these APIs. It is in the same directory as its OTE counterpart:
<top>/drive-t186ref-linux/tos/app/ote/client/sample_client1_gp/
 
sample_service3_gp.c demonstrates usage of the GP API wrapper in a Trusted Application (TA). Refer to inline documentation in the source files for more verbose instructions about how to use these APIs.
<top>/drive-t186ref-foundation/firmwares/src/trusted_os/ta-dev/src/ta3/
Information about the GlobalPlatform APIs
The home page for the GlobalPlatform API specifications is at:
https://www.globalplatform.org/specifications.asp
The GlobalPlatform API wrapper implements the TEE Client API Specification and parts of the TEE Internal API Specification. Both are available through the GlobalPlatform specification page at:
https://www.globalplatform.org/specificationsdevice.asp
TEE Secure Storage
TEE Secure storage (SS) is responsible for securely storing private context (data) of Trusted applications running within the Trusted Execution Environment. Secure storage solution provides:
Data confidentiality (AES-CTR-128 symmetric encryption).
Client Authentication (SHA-HMAC-256) for data read and writes.
Protection against data rollback to older versions.
Secure Storage software depends on hardware support to provide the necessary security as shown below:
KEK1, KEK2: fuses provisioned for encryption and authentication to work as expected.
RPMB device key: RPMB device key provisioned in EMMC/UFS storage for authentication and rollback protection to work.
SECURITY_MODE_0: This fuse enforces authentication and rollback check in the software.
Prior to production, it is absolutely necessary to program all these keys to ensure secure storage behaves and works as expected.
Development Mode
If SECURITY_MODE_0 fuse is not provisioned on the device-under-test/development, the software switches to soft-rpmb state, where authentication and rollback protection is not enforced. The state-machine and the software paths between soft-rpmb and hw-rpmb are exactly the same except in soft-rpmb state. The secure storage software does not error out and fail the client.
This unblocks the TA developers that may not have finalized the key values or are waiting on the necessary tools for provisioning. Once the project phase moves from development to production, these fuses and keys must be programmed.
Functionality Overview
The numbered interactions in the secure data storage flow diagram is as follows.
Interaction
Description
1
The Trusted OS (TOS) daemon is blocked on an IOCTL call waiting to service the next secure storage request.
2
A CA makes an SMC call into the secure world TA requesting some service.
3
Specific TA receives the call from the CA and over the course of its operation, suppose it needs to store any data securely. It calls secure storage TA to write/read/modify data.
4
SS TA receives the call, processes the request (encrypt/decrypt and packetize), and forwards the request to the TOS driver in NS world.
5
The TOS daemon collects the new request, issues the corresponding file operations, and notifies the TOS driver that the request is complete.
Secure storage flow
The platform provides an interface library called ote_storage that exposes the interfaces to communicate with the secure storage service. The interfaces exposed by the library and documentation for it is inside ote_storage.h and is a part of the include/ in the following package in the foundation:
drive-t186ref-foundation/firmwares/src/trusted_os/ta-dev/
The sample_service2.c source provided in the SDK/PDK shows an example of how to write a simple trusted application (TA) using the secure storage interfaces. The sample_service2 is invoked by the sample_client1 to store and read back a test string from storage.
NVIDIA® Trusted OS technology uses the following directory as the top-level secure storage directory:
/data/ss
The Secure Storage TA places files in subdirectories under the top-level secure storage directory. The Secure Storage TA names subdirectories with the secure storage client's UUID. It also encrypts and then stores secure data to files in those subdirectories, where it can be subsequently decrypted and accessed.
A daemon running in non-secure space provides access to trusted OS. The daemon initiates the following basic file operations, which the Secure Storage TA fulfills:
Create/delete
Open/close
Read/write
Getsize
Seek
Truncate
Secure Counter
The Trusted OS library exposes the Tegra Secure Counter (TSC) service for incorporation into TAs that provide a secure incrementing count. Like Secure Storage, TSC runs as a service in the secure world.
TSC has a 56-bit free-running timestamp counter for the oscillator (osc) clock. The architecture supports TSC continually incrementing at the osc frequency. This cannot be modified by the normal world.
Note:
The counter resets when the platform is rebooted.
TSC is exposed in:
<top>/drive-t186ref-foundation/firmwares/src/trusted_os/ta-dev/include/lib/ote/service/ote_tsc.h
For detailed information on the API, see Secure Counter Services in Trusted OS APIs.
Secure Counter Sample
Service1 shows how to call the TSC service to get the counter value using these TSC APIs:
te_error_t ote_tsc_init(void);
te_error_t ote_tsc_deinit(void);
te_error_t ote_tsc_get_msecs(uint64_t *tsc_msecs);
Installing the Infrastructure
 
Trusted and Client Application Development
Building Client Applications on Linux
Before using the sample Client Applications (CAs) and Trusted Applications (TAs), use SDK Manager to install the development tools for your target operating system and the Foundation package. The Foundation package provides the infrastructure to build client and trusted applications using make files.
Consult the SDK Manager documentation for installation requirements and detailed procedures.
Trusted and Client Application Development
The DRIVE AGX platform provides trusted and client applications at:
drive-t186ref-linux/samples/security/ca-dev
drive-t186ref-foundation/firmwares/src/trusted_os/ta-dev
Two trusted application samples perform these functions:
Crypto operations on sample buffers (AES CBC Encrypt and HMAC-SHA-512 bit)
Secure Timer reads
Secure storage interface calls
The sample source files are provided for reference.
To add one or more trusted application to the trusted OS
1. Follow the example in the make file to add a new source and manifest.
2. Examine the make file to:
Build the source into object files
Link with libraries
Make an application
Concatenate the application binaries into the big tos.img
The tos.img built by the make file is available at:
/drive-t186ref-foundation/firmwares/src/trusted_os/ta-dev/build-ta/t19x/tos.img
3. Flash the newly built tos.img, by replacing it with the one inside drive-t186ref-foundation/firmwares/bin/t19x/tos.img
Consult Flashing Basics for details on flashing the platform.
Building Client Applications on Linux
The process is similar to building trusted applications. The make file for client application is available at:
t186ref-linux/samples/security/ca-dev/build_ca.makefile.mk
The sample shows how to build rich OS applications.
After running the make command, the executables that are built are located at:
drive-t186ref-linux/samples/security/ca-dev/build-ca/
To execute the application to build rich OS
1. Select one of these options:
Using a USB or SCP, copy the executable to the target device.
Copy the executable to the target file system on the host machine at:
drive-t186ref-linux/targetfs/usr/local/bin/
2. Reflash the system.
Consult Flashing Basics for details on flashing the platform.
The resulting output of the sample_client1 sample is similar to the following:
root@tegra-ubuntu:/home/nvidia# ./sample_client1
Calling sample_service1
test_ss1 initializing: value_a = 0x55555555, value_b = 0x88888888
test_ss1: Calling te_open_session to increment values a,b
value_a = 0x55555556, value_b = 0x88888889
SS1: Perform CBC Encrypt
[92479.565453] trusty: log overflow.o/p data len = 32
data : e7 66 4c 13 ff 28 c9 65 b0 d2 a0 e7 ec 35 37 6 a5 31 63 63 0 ce dc fa 4e 95 f3 a2 b5 a 56 ed
SS1: Perform SHA-HMAC 512
o/p data len = 64
data : 16 4b 7a 7b fc f8 19 e2 e3 95 fb e7 3b 56 e0 a3 87 bd 64 22 2e 83 1f d6 10 27 c d7 ea 25 5 54 97 58 bf 75 c0 5a 99 4a 6d 3 4f 65 f8 f0 e6 fd
SS1 tests SUCCESSFUL
 
Calling sample_service2: Secure storage Test
test_ss2 initializing: value_a = 0x33333333, value_b = 0x99999999
test_ss2: Calling te_open_session to increment values a,b
value_a = 0x33333334, value_b = 0x9999999a
te_launch_operation SS2: secure storage buffer size = 43
buffer: Hello, Hello, from secure storage demo app.
SS2 tests SUCCESSFUL
 
Calling EFS TA
Computing HMAC-SHA 256 of a test i/p buffer:[92479.777010] trusty: log overflow. <This is a test buffer>
HMAC signature computed suffessfully!
o/p data len = 32
data : a3 61 f2 1d e 34 4c 34 d8 39 55 b2 b 7c cc b8 62 e0 1f 49 60 13 e2 29 d1 8 21 13 3f c4 3f bc
Computing RSA-2K of a test i/p buffer: [0,1,2,3,....,255]
o/p data len = 256
data : 4c ab fb 20 e2 1e fd 3d 94 4b c8 2c 20 7c eb 14 a4 54 1b 25 56 37 42 f6 aa cd db cc 63 1c 69 81 97 5a 69 cb ae 45 45 c7 79 9f a3 17 6a 91 15
EFS crypto tests SUCCESSFUL
User Data Encryption on Linux
 
Cryptsetup
User Data Encryption
Changing the Linux DTS
Data Encryption Impact on Boot Times
Encryption Algorithm
Disk Encryption Key Management
Hardware Backed Disk Encryption Key
Passphrase/Password
Building Cryptsetup with Hardware Backed Changes
Building Cryptsetup with OTE Changes
Disk encryption, on the Linux operating system, ensures that files are always stored on in an encrypted form. The files become available to the operating system and applications in readable form while the system is running and unlocked by a trusted user. An unauthorized user inspecting the contents of the disk directly finds garbled random-looking data instead of the actual files.
With user data encryption enabled, the /home directory in the file system is encrypted and user data is available when the system is running. The user /home partition is mounted on a separate disk partition and block level encryption is enabled for that disk.
The NVIDIA implementation uses the dm-crypt kernel module, which is the standard device-mapper interface for encryption functionality provided by the Linux kernel. It inserts itself between the disk driver and the file system to transparently encrypt and decrypt the data blocks.
The management of dm-crypt is performed with the cryptsetup user-space utility.
For more information about dm-crypt, see:
https://wiki.archlinux.org/index.php/Disk_encryption
Cryptsetup
The cryptsetup utility sets up disk encryption based on the DMCrypt kernel module. The NVIDIA implementation sets up the encrypted data disk as a LUKS partition and configures it with a random passphrase.
For more information about cryptsetup, see:
https://gitlab.com/cryptsetup/cryptsetup
User Data Encryption
For the e3550b01-t194a, e3550b01-t194ia, and p2382-t186 with L+EBP, and p2382-t186 with linux-ebp-ohara-gfx platforms, encrypted home directory is supported. To have an encrypted home setup, follow these steps:
PCT Configuration Changes
For e3550b01:
Go to the PCT cfg directory. For example, for e3550b01-t194 L+EBP:
cd <top>/drive-t186ref-foundation/virtualization/pct/e3550b01-t194a/linux-ebp/
Copy:
cp global_efs_storage_qspi.cfg global_storage_qspi.cfg
cp boot_chain_efs_storage_qspi.cfg boot_chain_storage_qspi.cfg
cp linux1_efs_storage_emmc.cfg linux1_storage_emmc.cfg
For p2382-t186:
Go to the PCT cfg directory. For example, for p2382-t186 L+EBP:
cd <top>/drive-t186ref-foundation/virtualization/pct/p2382-t186/linux-ebp
Copy:
cp global_efs_storage.cfg global_storage.cfg
cp boot_chain_efs_storage.cfg boot_chain_storage.cfg
cp linux1_efs_storage.cfg linux1_storage.cfg
Changing the Linux DTS
1. Decompile your Linux DTB to DTS using the device tree compiler (DTC) tool:
dtc -I dtb -O dts -o <DTS file path> <The linux DTB path>
The device node should have an instance of 50 and look as follows:
tegra_virt_storage8 {
/* Virtual block device for EFS partition */
compatible = "nvidia,tegra-hv-storage";
status = "disabled";
instance = <50>;
...
2. Change the status from disabled to okay. This enables the virtual device that corresponds to the EFS node.
3. Recompile the DTS to DTB using the DTC tool:
dtc -I dts -O dtb -o <The linux DTB path> <DTS file path>
Use produced dtb as the Linux dtb.
4. Flash the board.
All read and writes to /home directory are encrypted.
On boot, during file system setup, the startup scripts mount the user data in the encrypted /home folder.
The default data disk size 10 GB. to change the default size, modify the size parameter for the EFS_USR_DAT_ECRYPT_PART partition.
After boot, dump the disk partitions with the command:
$mount
You will see the following entry
/dev/mapper/dev-32e7bcd8-0561-4946-9c3e-8a0f314357a2 on /home…
To obtain more information about the encrypted partition, execute either of these commands:
$cryptsetup status /dev/mapper/dev-32e7bcd8-0561-4946-9c3e-8a0f314357a2
$dmsetup status
A systemd service mounts the encrypted disk at /home on every boot. All accesses to the disk are encrypted. This occurs transparently without any user interference.
Data Encryption Impact on Boot Times
On the first boot after flashing, setting up the encrypted partition takes about 15 minutes. The setup involves initializing the encrypted partition with random data and mounting it on /home. After the first boot, subsequent reboots have no visible impact on boot times.
Encryption Algorithm
The cipher mode used for disk encryption is aes-cbc-essiv:sha256. The cipher generator consists of three parts: cipher-chainmode-IV.
For more information on these settings, see:
https://wiki.archlinux.org/index.php/Disk_encryption#Ciphers_and_modes_of_operation
Disk Encryption Key Management
There are two types of keys for EFS functionality:
Disk Encryption Key (DEK) also known as the master key: the key used where the data flowing between the file system and the disk is encrypted and decrypted.
Passphrase/Password: the string or pattern input by the user to set up disk encryption. The same input is later used to enter, unlock, and decrypt the user data. It is assumed that there is no user interaction to setup or enter a passphrase each time. Therefore, the system sets and stores a passphrase which is used on every boot.
Hardware Backed Disk Encryption Key
The Disk Encryption Key (DEK) is derived from a /dev/urandom buffer with 32 bytes of random data. To enhance security and add randomness, the random buffer is then HMAC-SHA-256 signed in the secure world and returned back to cryptsetup. The secret key portion for HMAC signature is derived from the EKS blob provisioned into the device.
Passphrase/Password
For the passphrase, call into secure world to get the user passphrase. The hardware-backed passphrase is derived with a two-step process.
Getting the initial passphrase
Using the initial passphrase to derive Hardware-backed passphrase
Getting the initial passphrase
The initial passphrase is derived by performing an AES-CBC-128 encryption of a fixed known buffer, known IV, and the key stored in the KEK2 HW fuse provisioned by the OEM.
It is assumed that the OEM has some MAC layer, such as SE Linux, to verify the clients calling into trusted OS are validated and access controlled to ensure that a passphrase is not given out to unknown clients.
 
Note:
A keyfile is also created during the first boot with a 32 byte random vector from /dev/urandom, accessible only by the kernel.
If the TZ call to get a passphrase is not supported on your platform, it uses the passphrase in the keyfile as a secondary/backup option for the initial passphrase. The keyfile is stored in the user partition of the root-file system.
Deriving the hardware-backed passphrase
To derive the hardware-backed passphrase, the initial passphrase is run through the state machine as follows:
The cryptsetup encrypts the hardware-backed DEK using the hardware-backed passphrase and stores the encrypted DEK on the encrypted partition.
Building Cryptsetup with Hardware Backed Changes
The native cryptsetup code and the changes made by NVIDIA to support hardware-backed passphrase and DEK, including the sources, headers, and build scripts are available at:
drive-t186ref-linux/samples/security/cryptsetup
To build cryptsetup from the source code
Execute this command:
$./build_cryptsetup.sh
Upon a successful build, a message similar to the following is displayed:
Cryptsetup build complete. Check src/.libs/ for the executables
To rebuild cryptsetup or perform incremental builds
For incremental builds, enter these commands:
$cd cryptsetup-1.6.3
$make
For clean builds, enter these commands:
$cd cryptsetup-1.6.3
$make clean
$make
Building Cryptsetup with OTE Changes
The original cryptsetup source files are provided as part of the platform. Additionally, NVIDIA provides a cryptsetup application that calls Trusted OS and generates a device-bound key. The original cryptsetup source files and the cryptsetup application are available at:
<top>/drive-t186ref-linux/samples/security/cryptsetup
The platform includes make files and scripts that expand the original tarball and build the application with the NVIDIA changes. To customize the source further, use the script to build your cryptsetup application.
Note:
The root file system provided with the platform has all of the changes necessary for an Encrypted User data partition to work with device-bound keys. Rebuilding the application or copying the build files into the root file system is NOT required.
To build the cryptsetup application
1. Download the original cryptsetup source tarball from:
https://www.kernel.org/pub/linux/utils/cryptsetup/v1.6/cryptsetup-1.6.3.tar.gz
2. Run these commands on your host, if necessary, to install shared libraries used to build cryptsetup.
sudo apt-get install libdevmapper-dev
sudo apt-get install build-essential
sudo apt-get install uuid-dev
sudo apt-get install libpopt-dev
sudo apt-get install libgcrypt11-dev
3. Execute the command:
./build_cryptsetup_pdk.sh
Upon successful build, the output is similar to the following:
Cryptsetup build successful. Check cryptsetup-1.6.3/src/.libs/ for executable
To perform an incremental build
Enter the commands:
cd cryptsetup-1.6.3
make
To perform a clean build
Enter the commands:
cd cryptsetup-1.6.3
make clean
make
Enabling JTAG Support on Secure Targets
On secure targets, where the ODM production fuse has been blown, BootROM locks the JTAG connection interface. To enable the JTAG interface on such a target, a special BCT is required where certain parameters are set.
To enable the JTAG interface on a secure target
1. Set the desired debugging features through the BCT section of the flashing configuration file.
2. Generate a new BCT image.
To enable debugging features through the BCT configuration file
1. In the BCT partition of the flashing configuration file, set the uid attribute to the UID of the target device.
2. Set the sec_dbg_ctrl attribute to specify the debugging features desired.
The sec_dbg_ctrl attribute collection of bit fields are as follows.
Bits
Feature enabled by a ‘1’ bit
31
Ramdump
30:11
Reserved
10
SCE secure debug
9
SPE secure debug
8
BPMP secure debug
7:6
Reserved
5
DBGEN
4
NIDEN
3
SPIDEN
2
SPNIDEN
1
DEVICEEN
0
JTAG_ENABLE (must be 1 to enable the JTAG interface)
On secure targets BootROM compares the UID of the chip to the UID in the BCT, and enables debug features for bits 0, 1, 2, 3, 5 and 31 if the UIDs match.
An example of a flashing configuration file, that specifies the UID value for a specific target device, to enable the JTAG interface with all features except Ramdump, is as follows:
[partition]
name=bct
allocation_policy=sequential
filesystem_type=basic
uid=0xa18010016419f105000000000a010380
sec_dbg_ctrl=0x73F
size=0x80000
partition_attribute=0
To update the BCT and bootloader images
1. Enable any required debugging features through the configuration file.
2. Navigate to the flashing scripts directory:
cd drive-t186ref-foundation/tools/host/flashtools/bootburn_t19x
3. Create offline images that incorporate your changes using create_bsp_image.sh.
4. Update the newly generated BCT and bootloader images , MB1 and MB1 recovery, by either of these methods:
Use the Update Tool to compile update_sample and copy it to the target.
Flash the complete images by running flash_bsp_images.sh.
Encrypted Key Storage in eMMC
The NVDIA Trusted OS solution supports a simple way to provide and update platform secrets, such as keys, and certificated through an Encrypted Key Storage (EKS) mechanism.
The users can generate and store an encrypted partition of platform secrets, for example Encrypted blob of keys, in the eMMC memory which are encrypted using the Secure Boot Key.
These platform secrets are copied over, from eMMC, during boot and are accessible from Trusted OS at runtime through API calls to the crypto service Trusted Application.
The MAX_SIZE for the EKS partition in eMMC is 32KB.
Updated versions of this key material can be flashed using the Nvidia bootburn flash tool.
For more information on how to generate a custom EKS partition or extract keys from a pre-generated EKS partition, consult:
<top>/drive-t186ref-foundation/firmwares/src/trusted_os/ta-dev/tools/eks_gen/README