Add README with instructions for build and usage

README.md

+# Secure Element Examples
+
+[[_TOC_]]
+
+Many SECO boards are equipped with a secure element (SE) IC that can improve
+security in various use cases.
+E.g. the SE050 SE of NXP:
+https://www.nxp.com/products/security-and-authentication/authentication/edgelock-se050-plug-trust-secure-element-family-enhanced-iot-security-with-high-flexibility:SE050
+
+This repository is a collection of sample applications intended to demonstrate
+some of the SE features and development.
+
+## se05x-aes-key example application
+
+To integrate a SE05x SE into a specific application, the vendor provided
+a middleware package to interact with the SE. This middleware package is
+available in different versions. The open source Plug & Trust Middleware
+Mini Package has been integrated into the Yocto BSP and SDK as a library
+(since kirkstone-9.0).
+https://github.com/NXP/plug-and-trust
+
+To demonstrate the developement with the SE05x and the use of the
+library, the *se05x-aes-key* example application was introduced.
+The application is able to execute some basic AES operations on the SE.
+
+**This example application should not be used in series or in productive uses
+cases because it does not meet any specific security criteria.**
+
+### SDK build
+
+The application can be build directly using the SDK:
+
+```sh
+git clone https://git.seco.com/seco-ne/tools/secure-element-examples.git
+cd secure-element-examples
+source <SDK-Path>/environment-xxx
+mkdir build
+cd build
+cmake ..
+cmake --build .
+```
+
+### Read and write a AES key as binary
+
+It is possible to write and read an AES key as binary to/from a specific
+address in the SE. The default policies of the cipher type
+(*cipherType = kSSS_CipherType_Binary*) allow to erase and read back the key
+from the SE:
+
+```
+openssl rand -hex 16 | tr -d '\n' > aes.key
+se05x-aes-key setbinkey 0xF0000040 aes.key /dev/i2c-2
+se05x-aes-key getbinkey 0xF0000040 getaes.key /dev/i2c-2
+```
+The key address *0xF0000040* can be replaced by another valid key adresse.
+The i2c bus (last argument) must be the bus the SE is connected to.
+
+### AES key write and decryption on the SE
+
+If a AES key is injected using the *setaeskey* function, the cipher type
+*kSSS_CipherType_AES* is used. The default policies of this cipher type prevent
+the key from being read back from the SE (erasing is still possible). The
+*decryptaes* function is meant to load a file via I2C in the SE and run a AES
+CBC decryption using a key at a provided key and initial vector. In the
+following example a file is encrypted using a generated openssl key file, the
+AES key is written to the SE and used for the decryption on SE:
+
+```
+# Generate key file
+root@seco-mx8mp:~# openssl rand -hex 16 | tr -d '\n' > aes-kfile
+# Create test data file
+root@seco-mx8mp:~# echo "Test data: 123456789" > testdata
+# Encrypt test data with the key file and print the corresponding AES key and initial vector
+root@seco-mx8mp:~# openssl enc -in testdata -out testdata.crypt -e -aes-128-cbc -pbkdf2 -nosalt -p -kfile aes-kfile
+key=F67E507518B58B82239C72ADFF703A20
+iv =B8EC63102697026D388EF889DFC0FBB9
+
+# Create AES key file
+root@seco-mx8mp:~# echo F67E507518B58B82239C72ADFF703A20 | tr -d "\n" > aes.key
+# Create Initial Vector file
+root@seco-mx8mp:~# echo B8EC63102697026D388EF889DFC0FBB9 | tr -d "\n" > ivfile
+# Store key in SE as AES key
+root@seco-mx8mp:~# se05x-aes-key setaeskey 0xF0000048 aes.key /dev/i2c-2
+
+# Decrypt test data
+root@seco-mx8mp:~# se05x-aes-key decryptaes 0xF0000048 ivfile testdata.crypt testdata.decrypt /dev/i2c-2
+
+# With archive
+root@seco-mx8mp:~# tar cfvj archive.tar.bz2 testdata
+root@seco-mx8mp:~# openssl enc -in archive.tar.bz2 -out archive.tar.bz2.crypt -e -aes-128-cbc -pbkdf2 -nosalt -p -kfile aes-kfile
+root@seco-mx8mp:~# rm archive.tar.bz2
+root@seco-mx8mp:~# rm testdata
+root@seco-mx8mp:~# se05x-aes-key decryptaes 0xF0000048 ivfile archive.tar.bz2.crypt archive.tar.bz2 /dev/i2c-2
+root@seco-mx8mp:~# tar xf archive.tar.bz2
+root@seco-mx8mp:~# cat testdata
+Test data: 123456789
+```
+The key address *0xF0000048* can be replaced by another valid key adresse.
+The i2c bus (last argument) must be the bus the SE is connected to.
+The steps are also applicable for the 256 CBC algorithm (*-aes-256-cbc*).
+
+### Erase keys
+
+The *erasekey* function erases a key at a specified adresse:
+
+```sh
+se05x-aes-key erasekey <key-address> /dev/i2c-<bus_nr>
+```
+
+### Known limitations
+
+* *decryptaes*: It is only possible to decrypt files smaller than 512 bytes
+* *decryptaes*: It is not possible to decrypt files that are encrypted with a
+"salted" signature