architecture/subkeys.rst

.. _subkeys:

#######
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:


.. uml::
	:width: 800

	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 [#f1]_ 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   | Field Name        | Protected by field  |                       |
| bytes     |                   |                     |                       |
+-----------+-------------------+---------------------+-----------------------+
| .. centered:: 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                 |
+-----------+-------------------+---------------------+-----------------------+
| .. centered:: 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               |                       |
+-----------+-------------------+---------------------+-----------------------+
|           | .. centered:: 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   |  hash               | The subkey attributes |
| binary to img_size            |                     | 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   | Not signed, used to prove that    |
|                  | for the next subkey  | 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   | Not signed used to prove that     |
|                  | for the TA           | 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


.. rubric:: Footnotes

.. [#f1] UUIDv5 and namespaces are described in
	`RFC4122 <https://datatracker.ietf.org/doc/html/rfc4122>`_.
	Note that OP-TEE uses a truncated SHA-512 instead of the
        weak SHA-1 hash when when deriving a new UUID from a
        namespace and name.