Subkeys

Subkeys is an OP-TEE-specific implementation to provide a public key hierarchy. Subkeys can be delegated to allow different actors to sign different TAs without sharing a private key.

The first key in the chain is verified using a root key. Example Subkey hierarchy:

object "Root key" as root
object "First-level subkey" as first
object "Second-level subkey" as second

object root {
        PublicKey
}

object first {
        Signature
        UUID
        PublicKey
}

object second {
        Signature
        UUID
        PublicKey
}

root -> first
first -> second

Each subkey defines a UUIDv5 namespace [1] to which another signed subkey or TA must belong. This avoids that one subkey can be used to sign TAs which should be signed with a different key. Since the UUIDs are restricted by this there is also a special kind of subkey, called identity subkey, which uses the same UUID as the TA it is supposed to sign.

A subkey consists of two files, a private key pair in a .pem file and the signed public key in a .bin file. Subkeys reuse the signed header (SHDR) format used for signed TAs, followed by a payload holding a public key and UUID among other fields. A subkey is formatted with all fields in little endian as:

Size in bytes

Field Name

Protected by field

Signed header (struct shdr)

4

magic

hash

0x4f545348

4

img_type

hash

3, SHDR_SUBKEY

4

img_size

hash

4

algo

hash

Signature algorithm, GP TEE_ALG_*

4

hash_size

hash

4

sig_size

hash

hash_size

hash

sig

sig_size

sig

previous pub key

Root key or a subkey higher up in the chain

Subkey header (struct shdr_subkey)

16

UUID

hash

UUIDv5 namespace for next subkey or TA

4

name_size

hash

Size of the UUIDv5 name for the next subkey or TA, 0 for identiy subkeys

4

subkey_version

hash

4

max_depth

hash

4

algo

hash

Signature algorithm for the next subkey or TA

4

attr_count

hash

Subkey attrs * attr_count

Attributes of the public key in this subkey

4

id

hash

GP TEE_ATTR_*

4

offs

hash

4

size

hash

opaque data padding up this binary to img_size

hash

The subkey attributes above point into this area using offset and size

All subkeys included in the subkey hierarchy are added in front when a TA is signed using a subkey. For example, if a TA is signed using the second-level subkey above it would look like this:

Size in bytes

Binary

first.img_size

First-level subkey | Signed by Root key

first.name_size

UUIDv5 name string for the next subkey

Not signed, used to prove that the next UUID is in the namespace of the First-level subkey. This size is from “name_size” of the previous subkey (First-level).

second.img_size

Second-level subkey

Signed by First-level subkey

second.name_size

UUIDv5 name string for the TA

Not signed used to prove that the next UUID is in the namespace of the Second-level subkey. This size is from “name_size” of the previous subkey (Second-level).

second.img_size

TA

Signed by Second-level subkey

The signed TA binary is self-contained with all the public keys needed for verification included, except the public root key which is embedded in the TEE core binary.

The UUIDv5 name string is a separate field between subkeys and the next subkey or TA to allow a subkey to be used to sign more than one other subkey or TA.

A signed TA or subkey can be inspected using the sign_encrypt.py script, for example:

$ scripts/sign_encrypt.py display --in 5c206987-16a3-59cc-ab0f-64b9cfc9e758.ta
Subkey
 struct shdr
  magic:      0x4f545348
  img_type:   3 (SHDR_SUBKEY)
  img_size:   320 bytes
  algo:       0x70414930 (TEE_ALG_RSASSA_PKCS1_PSS_MGF1_SHA256)
  hash_size:  32 bytes
  sig_size:   256 bytes
  hash:       f573f329fe77be686ce71647909c4ea35b5e1cd7de86369bd7d9fca31f6a4d65
 struct shdr_subkey
  uuid:       f04fa996-148a-453c-b037-1dcfbad120a6
  name_size:  64
  subkey_version: 1
  max_depth:  4
  algo:       0x70414930 (TEE_ALG_RSASSA_PKCS1_PSS_MGF1_SHA256)
  attr_count: 2
  next name:  "mid_level_subkey"
Next header at offset: 692 (0x2b4)
Subkey
 struct shdr
  magic:      0x4f545348
  img_type:   3 (SHDR_SUBKEY)
  img_size:   320 bytes
  algo:       0x70414930 (TEE_ALG_RSASSA_PKCS1_PSS_MGF1_SHA256)
  hash_size:  32 bytes
  sig_size:   256 bytes
  hash:       233a6dcf1a2cf69e50cde8e20c4129157da707c76fa86ce12ee31037edef02d7
 struct shdr_subkey
  uuid:       1a5948c5-1aa0-518c-86f4-be6f6a057b16
  name_size:  64
  subkey_version: 1
  max_depth:  3
  algo:       0x70414930 (TEE_ALG_RSASSA_PKCS1_PSS_MGF1_SHA256)
  attr_count: 2
  next name:  "subkey1_ta"
Next header at offset: 1384 (0x568)
Bootstrap TA
 struct shdr
  magic:      0x4f545348
  img_type:   1 (SHDR_BOOTSTRAP_TA)
  img_size:   84576 bytes
  algo:       0x70414930 (TEE_ALG_RSASSA_PKCS1_PSS_MGF1_SHA256)
  hash_size:  32 bytes
  sig_size:   256 bytes
  hash:       ea31ac7dc2cc06a9dc2853cd791dd00f784b5edc062ecfa274deeb66589b4ca5
 struct shdr_bootstrap_ta
  uuid:       5c206987-16a3-59cc-ab0f-64b9cfc9e758
  ta_version: 0
 TA offset:  1712 (0x6b0) bytes
 TA size:    84576 (0x14a60) bytes

Footnotes