**********************************************************************
                           Linux for Tegra
                          Tool: gen_ekb.py
                                README
**********************************************************************
This README provides an overview of the "gen_ekb.py" tool to generate
an EKS image file "eks.img". It has a pre-defined layout of EKB that
includes a CMAC text, a random IV, and encrypted user data. The Jetson
user key PTA in OP-TEE extracts the EKB that generated by this script.

----------------------------------------------------------------------
Dependency
----------------------------------------------------------------------
- Python version 3.6 or above
- Python cryptography modules pyca/cryptography and pycrypto. You can
install that via "apt" or "pip" command on your Linux host machine.

$> apt-get install python3-cryptography
or
$> pip install cryptography

and

$> pip install pycrypto
----------------------------------------------------------------------
Tool: gen_ekb.py overview
----------------------------------------------------------------------

Note that You can define a specific mechanism to encapsulate the EKB
contents depending on the requirement. This tool will introduce a demo
that shows how to encrypt a symmetric key with a random IV
(initial vector) that is used to encrypt the key with AES-CBC
algorithm and generate an authentication code EKB_cmac that can be
used to verify the EKB content to make sure it's not modified.

The script shows how to perform the following steps to generate the
EKB blob.

The EKB layout:
----------------------------------------------------------
|    ekb-size   |    magic-id   |  ver-major | ver-minor  |
----------------------------------------------------------
|                             cmac                        |
----------------------------------------------------------
| cont-data-len | cont-magic-id |        reserved         |
----------------------------------------------------------
|                              iv                         |
----------------------------------------------------------
|    tag1       |    key1-len   |         key1            |
----------------------------------------------------------
|  key1(continued)  |    tag2   |         key2-len        |
----------------------------------------------------------
|                   key2(continued)                       |
----------------------------------------------------------
|  key2(continued)  |    tag3   |         key3-len        |
----------------------------------------------------------
|                               ...                       |
----------------------------------------------------------
|    end-tag(\0\0\0\0)    |    end-tag-len(\0\0\0\0)      |
----------------------------------------------------------

* Each row in the first four rows occupies 16 bytes
* The tag, key length and key data are encrypted and saved after "iv"
* The zeroes at the end of the EKB image indicate the end of user data
* Normally EKB saves user keys so the term "key" is used in above diagram.
  Technically any user data can be saved in EKB.

The steps of EKB generation:
* Derive RK (Root Key)
  * Need a fixed vector FV_for_ekb
  * Deriving RK (Root Key) from fuse key(T194: KEK2, T234: OEM_K2)
    * EKB_RK = AES-128-ECB(fuse_key, FV_for_ekb)
* Generate DKs (Derived keys) that follows NIST-SP-800-108 KDF scheme
  * EKB_EK = NIST-SP-800-108(EKB_RK, ...)
  * EKB_AK = NIST-SP-800-108(EKB_RK, ...)
* Acquire EKB content ciphertext
  * EKB_ciphertext = AES-128-CBC(iv=Random_IV, key=EKB_EK,
		                 user data)
* Acquire EKB_cmac code
  * EKB_content = Random_IV + EKB_ciphertext
  * EKB_cmac = AES-CMAC(key=EKB_AK, EKB_content)
* Generate EKB blob (eks.img)
  * EKB_blob = EKB_header + EKB_cmac + EKB_content

----------------------------------------------------------------------
Default EKB Binary
----------------------------------------------------------------------

The default EKB binary is located at:
<Linux_for_Tegra>/bootloader/eks_t194.img
<Linux_for_Tegra>/bootloader/eks_t234.img

----------------------------------------------------------------------
How to use the script
----------------------------------------------------------------------

This program is a sample program that generates the EKB that works with
TEE sample: sample/hwkey-agent

To generate the sample EKB for EKS partition yourself, run "example.sh".

To view usage:
$ python gen_ekb.py --help

The input options:
-chip: specify chip: t194|t234
-kek2_kek: kek2 key (16 bytes) file in hex format [t194 only]
-oem_k1_key: oem_k1 key (32 bytes) file in hex format [t234 only]
-fv: fixed vectors (16 bytes) file for ekb in hex format
-in_sym_key:  16-bytes symmetric key file in hex format
-in_sym_key2: 16-bytes symmetric key file in hex format
-out: where the eks image file is stored

Following the command for example.
$ python3 gen_ekb.py
	-chip t194 \
	-key2_key kek2_key_file \
	-fv fv_for_ekb_file \
	-in_sym_key user_key_file \
	-in_sym_key2 user2_key_file \
	-out eks.img

$ python3 gen_ekb.py
	-chip t234 \
	-oem_k1_key oem_k1_key_file \
	-fv fv_for_ekb_file \
	-in_sym_key user_key_file \
	-in_sym_key2 user2_key_file \
	-out eks.img
