**********************************************************************
                           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: A symmetric key file in hex format [t194: 16-bytes | t234: 32-bytes]
-in_sym_key2: 16-bytes symmetric key file in hex format
-in_auth_key: 16-bytes symmetric key file in hex format
-in_device_id: A device ID cert in DER format [t234 only]
-in_ftpm_sn: 20 bytes fTPM serial number in hex string [t234 only]
-in_ftpm_eps_seed: fTPM EPS seed file in hex format [t234 only]
-in_ftpm_rsa_ek_cert: fTPM RSA EK cert in DER format [t234 only]
-in_ftpm_ec_ek_cert: fTPM EC EK cert in DER format [t234 only]
-out: where the eks image file is stored

Following the command for example.
$ python3 gen_ekb.py
	-chip t194 \
	-kek2_key kek2.key \
	-fv fv_ekb_t194 \
	-in_sym_key sym_t194.key \
	-in_sym_key2 sym2_t194.key \
	-in_auth_key auth_t194.key \
	-out eks_t194.img

$ python3 gen_ekb.py
	-chip t234 \
	-oem_k1_key oem_k1.key \
	-fv fv_ekb_t234 \
	-in_sym_key sym_t234.key \
	-in_sym_key2 sym2_t234.key \
	-in_auth_key auth_t234.key \
	-in_device_id device_id_cert.der \
	-in_ftpm_sn 00000000000000000000 \
	-in_ftpm_eps_seed ftpm_eps_seed_file \
	-in_ftpm_rsa_ek_cert ftpm_rsa_ek_cert.der \
	-in_ftpm_ec_ek_cert ftpm_ec_ek_cert.der \
	-out eks_t234.img
