Merge pull request #31 from tropicsquare/26-implement-functions-for-t…

…ypical-chip-usage

26 implement functions for typical chip usage

.github/workflows/build_docs_release.yml

@@ -24,8 +24,8 @@ jobs:
           source-dir: ./
           build-dir: build
           options: |
-            BUILD_DOCS=ON
-            USE_TREZOR_CRYPTO=ON
+            LT_BUILD_DOCS=ON
+            LT_USE_TREZOR_CRYPTO=ON
 
       - name: Upload built html as artifact
         id: html_artifact

.github/workflows/build_docs_upload_artifacts.yml

@@ -24,8 +24,8 @@ jobs:
           source-dir: ./
           build-dir: build
           options: |
-            BUILD_DOCS=ON
-            USE_TREZOR_CRYPTO=ON
+            LT_BUILD_DOCS=ON
+            LT_USE_TREZOR_CRYPTO=ON
 
       - name: Upload HTML docs artifact
         uses: actions/[email protected]

.gitlab-ci.yml

@@ -38,7 +38,7 @@ build_library:
     - rm -rf build/
     - mkdir build
     - cd build
-    - cmake -DUSE_TREZOR_CRYPTO=1 ..
+    - cmake -DLT_USE_TREZOR_CRYPTO=1 ..
     - make
 
 build_integration_tests:
@@ -50,10 +50,10 @@ build_integration_tests:
     - cd tests/integration/
     - mkdir build
     - cd build
-    - cmake -DUSE_TREZOR_CRYPTO=1 ..
+    - cmake -DLT_USE_TREZOR_CRYPTO=1 ..
     - make
 
-build_docs:
+LT_BUILD_DOCS:
   stage: docs
   tags:
     - shell
@@ -62,7 +62,7 @@ build_docs:
     - rm -rf build/
     - mkdir build
     - cd build
-    - cmake -DBUILD_DOCS=1 ..
+    - cmake -DLT_BUILD_DOCS=1 ..
     - make doc_doxygen
     - cd docs/doxygen/latex
     - make

CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Included lt_l2_api_structs.h and lt_l3_api_structs.h are automatically generated
 - SH0 pairing keypair now reflects first batch of TROPIC01 devices
 - Changed logging format in examples.
+- Renamed cmake switches: LT_USE_TREZOR_CRYPTO, LT_BUILD_DOCS, LT_EXPERIMENTAL_SPI_UART
 
 ### Added
 

CMakeLists.txt

@@ -6,20 +6,24 @@ cmake_minimum_required(VERSION 3.21.0)
 #                                                                         #
 ###########################################################################
 
-option(USE_TREZOR_CRYPTO "Use trezor_crypto as a cryptography provider" OFF)
+option(LT_USE_TREZOR_CRYPTO "Use trezor_crypto as a cryptography provider" OFF)
 option(LT_CRYPTO_MBEDTLS "Use mbedtls as a cryptography provider" OFF)
-option(BUILD_DOCS "Build documentation" OFF)
-option(EXPERIMENTAL_SPI_UART "Experimental feature for spi slave to serial hw convertor" OFF)
-option(EXPERIMENTAL_SPI_RASPBERRYPI "Experimental feature for spi slave on rpi 4" OFF)
+option(LT_BUILD_DOCS "Build documentation" OFF)
+option(LT_EXPERIMENTAL_SPI_UART "Experimental feature for spi slave to serial hw convertor" OFF)
 option(LT_ADD_EXAMPLES "Compile example code as part of libtropic library" OFF)
 option(LT_ENABLE_FW_UPDATE "Enable firmware update functions and compile firmware update in a form of byte array" OFF)
+# This switch controls if helper utilities are compiled in. In most cases this should be ON,
+# examples and tests need to have helpers utilities compiled.
+# Switch it off to compile only basic libtropic API.
+option(LT_UTILS "Compile helper function" ON)
+
 ###########################################################################
 #                                                                         #
 #   Building documentation                                                #
 #                                                                         #
 ###########################################################################
 
-if(BUILD_DOCS)
+if(LT_BUILD_DOCS)
     find_package(Doxygen)
     if(Doxygen_FOUND)
         add_subdirectory(docs)
@@ -30,7 +34,7 @@ if(BUILD_DOCS)
 endif()
 
 # Check if cryptography provider is defined
-if((NOT USE_TREZOR_CRYPTO) AND (NOT LT_CRYPTO_MBEDTLS) AND (NOT BUILD_DOCS))
+if((NOT LT_USE_TREZOR_CRYPTO) AND (NOT LT_CRYPTO_MBEDTLS) AND (NOT LT_BUILD_DOCS))
     message(FATAL_ERROR "Mbed TLS or trezor_crypto must be enabled!")
 endif()
 
@@ -132,17 +136,18 @@ target_compile_definitions(tropic PRIVATE "$<$<CONFIG:DEBUG>:LIBT_DEBUG>")
 
 # This options just add 10ms synchronisation delay before read and write functions.
 # Needed for hardware spi slave to uart converter.
-if(EXPERIMENTAL_SPI_UART)
-    target_compile_definitions(tropic PRIVATE EXPERIMENTAL_SPI_UART=1)
-endif()
-
-if(EXPERIMENTAL_SPI_RASPBERRYPI)
-    target_compile_definitions(tropic PRIVATE EXPERIMENTAL_SPI_RASPBERRYPI=1)
+if(LT_EXPERIMENTAL_SPI_UART)
+    target_compile_definitions(tropic PRIVATE LT_EXPERIMENTAL_SPI_UART=1)
 endif()
 
-if(USE_TREZOR_CRYPTO)
+if(LT_USE_TREZOR_CRYPTO)
     add_subdirectory(vendor/trezor_crypto/ "trezor_crypto")
     target_compile_definitions(trezor_crypto PRIVATE AES_VAR USE_INSECURE_PRNG)
     target_link_libraries(tropic PRIVATE trezor_crypto)
-    target_compile_definitions(tropic PRIVATE USE_TREZOR_CRYPTO)
+    target_compile_definitions(tropic PRIVATE LT_USE_TREZOR_CRYPTO)
 endif()
+
+if(LT_UTILS)
+    target_compile_definitions(tropic PRIVATE LT_UTILS)
+endif()
+

docs/index.md

@@ -33,9 +33,9 @@ This library was designed to be compiled during the build of a parent project.
 It provides following options to be defined during building:
 
 ```
-option(USE_TREZOR_CRYPTO "Use trezor_crypto as a cryptography provider" OFF)
+option(LT_USE_TREZOR_CRYPTO "Use trezor_crypto as a cryptography provider" OFF)
 option(LT_CRYPTO_MBEDTLS "Use mbedtls as a cryptography provider"       OFF)
-option(BUILD_DOCS        "Build documentation"                          OFF)
+option(LT_BUILD_DOCS        "Build documentation"                          OFF)
 ```
 
 Options could be passed as a command line argument, or they could be defined in main project's cmake files when this library is added to its build tree.
@@ -56,7 +56,7 @@ Compile `libtropic` as a static archive under Unix:
 ```
 $ mkdir build
 $ cd build
-$ cmake -DUSE_TREZOR_CRYPTO=1 ..
+$ cmake -DLT_USE_TREZOR_CRYPTO=1 ..
 $ make
 ```
 
@@ -65,7 +65,7 @@ Cross-compile `libtropic` as a static archive:
 ```
 $ mkdir build
 $ cd build
-$ cmake -DUSE_TREZOR_CRYPTO=1 -DCMAKE_TOOLCHAIN_FILE=<ABSOLUTE PATH>/toolchain.cmake -DLINKER_SCRIPT=<ABSOLUTE PATH>/linker_script.ld ..
+$ cmake -DLT_USE_TREZOR_CRYPTO=1 -DCMAKE_TOOLCHAIN_FILE=<ABSOLUTE PATH>/toolchain.cmake -DLINKER_SCRIPT=<ABSOLUTE PATH>/linker_script.ld ..
 $ make
 ```
 
@@ -74,7 +74,7 @@ To build html documentation, you need Doxygen. The documentation is built using
 ```sh
 $ mkdir build/
 $ cd build/
-$ cmake -DBUILD_DOCS=1 ..
+$ cmake -DLT_BUILD_DOCS=1 ..
 $ make doc_doxygen
 ```
 

examples/keys.c

@@ -2,8 +2,12 @@
 
 // Default factory pairing keys
 int8_t pkey_index_0 =  PAIRING_KEY_SLOT_INDEX_0;
+// Engineering samples 01:
 uint8_t sh0priv[] = {0xd0,0x99,0x92,0xb1,0xf1,0x7a,0xbc,0x4d,0xb9,0x37,0x17,0x68,0xa2,0x7d,0xa0,0x5b,0x18,0xfa,0xb8,0x56,0x13,0xa7,0x84,0x2c,0xa6,0x4c,0x79,0x10,0xf2,0x2e,0x71,0x6b};
 uint8_t sh0pub[]  = {0xe7,0xf7,0x35,0xba,0x19,0xa3,0x3f,0xd6,0x73,0x23,0xab,0x37,0x26,0x2d,0xe5,0x36,0x08,0xca,0x57,0x85,0x76,0x53,0x43,0x52,0xe1,0x8f,0x64,0xe6,0x13,0xd3,0x8d,0x54};
+// Python model:
+//uint8_t sh0priv[] = {0xf0,0xc4,0xaa,0x04,0x8f,0x00,0x13,0xa0,0x96,0x84,0xdf,0x05,0xe8,0xa2,0x2e,0xf7,0x21,0x38,0x98,0x28,0x2b,0xa9,0x43,0x12,0xf3,0x13,0xdf,0x2d,0xce,0x8d,0x41,0x64};
+//uint8_t sh0pub[]  = {0x84,0x2f,0xe3,0x21,0xa8,0x24,0x74,0x08,0x37,0x37,0xff,0x2b,0x9b,0x88,0xa2,0xaf,0x42,0x44,0x2d,0xb0,0xd8,0xaa,0xcc,0x6d,0xc6,0x9e,0x99,0x53,0x33,0x44,0xb2,0x46};
 // Keys with acces to write attestation key in slot 1
 uint8_t pkey_index_1 =  PAIRING_KEY_SLOT_INDEX_1;
 uint8_t sh1priv[] = {0x58,0xc4,0x81,0x88,0xf8,0xb1,0xcb,0xd4,0x19,0x00,0x2e,0x9c,0x8d,0xf8,0xce,0xea,0xf3,0xa9,0x11,0xde,0xb6,0x6b,0xc8,0x87,0xae,0xe7,0x88,0x10,0xfb,0x48,0xb6,0x74};

examples/lt_ex_hello_world.c

@@ -18,60 +18,6 @@
  * @par
  */
 
-/**
- * @brief This function establish a secure channel between host MCU and TROPIC01 chip
- *
- * @param h           Device's handle
- * @param shipriv     Host's private pairing key (SHiPUB)
- * @param shipub      Host's public pairing key  (SHiPUB)
- * @param pkey_index  Pairing key's index
- * @return            LT_OK if success, otherwise returns other error code.
- */
-static lt_ret_t verify_chip_and_start_secure_session(lt_handle_t *h, uint8_t *shipriv, uint8_t *shipub, uint8_t pkey_index)
-{
-    lt_ret_t ret = LT_FAIL;
-
-    // This is not used in this example, but let's read it anyway
-    uint8_t chip_id[LT_L2_GET_INFO_CHIP_ID_SIZE] = {0};
-    ret = lt_get_info_chip_id(h, chip_id, LT_L2_GET_INFO_CHIP_ID_SIZE);
-    if (ret != LT_OK) {
-        return ret;
-    }
-
-    // This is not used in this example, but let's read it anyway
-    uint8_t riscv_fw_ver[LT_L2_GET_INFO_RISCV_FW_SIZE] = {0};
-    ret = lt_get_info_riscv_fw_ver(h, riscv_fw_ver, LT_L2_GET_INFO_RISCV_FW_SIZE);
-    if (ret != LT_OK) {
-        return ret;
-    }
-
-    // This is not used in this example, but let's read it anyway
-    uint8_t spect_fw_ver[LT_L2_GET_INFO_SPECT_FW_SIZE] = {0};
-    ret = lt_get_info_spect_fw_ver(h, spect_fw_ver, LT_L2_GET_INFO_SPECT_FW_SIZE);
-    if (ret != LT_OK) {
-        return ret;
-    }
-
-    uint8_t X509_cert[LT_L2_GET_INFO_REQ_CERT_SIZE] = {0};
-    ret = lt_get_info_cert(h, X509_cert, LT_L2_GET_INFO_REQ_CERT_SIZE);
-    if (ret != LT_OK) {
-        return ret;
-    }
-
-    uint8_t stpub[32] = {0};
-    ret = lt_cert_verify_and_parse(X509_cert, LT_L2_GET_INFO_REQ_CERT_SIZE, stpub);
-    if (ret != LT_OK) {
-        return ret;
-    }
-
-    ret = lt_session_start(h, stpub, pkey_index, shipriv, shipub);
-    if (ret != LT_OK) {
-        return ret;
-    }
-
-    return LT_OK;
-}
-
 /**
  * @brief Session with H0 pairing keys
  *