Some applications require security features beyond those provided by the Bluetooth specification. This article describes the steps necessary for a building a BLE project with mbedtls.
Mbedtls is a library of cryptographic functions, defined here https://tls.mbed.org/api/, which are used by the Silicon Laboratories Bluetooth Low Energy stack. Silicon Labs provides low level drivers for the cryptographic engines in it SoCs to allow mbedtls to run efficiently.
Any application that needs to use mbedtls must remove the prebuilt mbedtls library and build the mbedtls library from source to avoid conflicts. Mbedtls is a highly configurable library with features that can be enabled by defining preprocessor symbols to a configuration file. The basic setup is described below
At a minimum, the following files must be added to the project. These are found in the SDK folder under util\third_party\mbedtls
Add the following to your project's include paths
util/third_party/mbedtls/include util/third_party/mbedtls/include/mbedtls util/third_party/mbedtls/sl_crypto/include util/silicon_labs/silabs_core/memory_manager
Add the following definition to the preprocessor symbols
Copy protocol\bluetooth\ble_stack\inc\soc\mbedtls_config.h from the SDK to the project's protocol\bluetooth\ble_stack\inc\soc folder. This ensures that the project enables all of the mbedtls features that the Bluetooth stack requires. Additional features can be enabled in this file but none of the existing features can be disabled.
Add the following to your application code
#if !defined(MBEDTLS_CONFIG_FILE) #include "mbedtls/config.h" #else #include MBEDTLS_CONFIG_FILE #endif
Now you can begin using mbedtls in your application code.
I have followed this article step by step but I am getting undefined reference to several mbedtls APIs as some of the macros are not defined. Such as MBEDTLS_CTR_DRBG_C, MBEDTLS_ENTROPY_C and many others.
Please guide if there is any steps needs to be done.
It work, thank you!
I was trying to find the SDK folder under util\third_party\mbedtls. Where can I find the SDK folder?.
@Mohan Vinnakota: At the time of writing, on my machine with Simplicity Studio installed with default settings, my SDK folder is at:
This folder contains util, and other yummy things. mbedtls does not contain an SDK folder, think you misunderstood something.
@Everyone trying to get started with mbedTLS
My hardware: Blue Gecko Wireless Starter Kit with Mainboard BRD4001A Rev A01, with socketed module EFR32xG22 2.4 GHz 6 dBm Radio Board BRD4001A Rev B04. This board has the EFR32MG22C224F512IM40 chip on it.
I also followed this article step by step, and I found it incomplete. I added dependencies, searching mbedtls, sl_crypto, and cryptoacc with fgrep to find missing definitions, and ultimately ended up in a place where the only error was a linker error for undefined symbols that should have been defined within sl_crypto/src/crypto_ble.c (and another I can't remember), except it was masked out by an #ifdef(CRYPTO_PRESENT). I thought "of course crypto is present, let me add CRYPTO_PRESENT=1 to the compiler flags and get a cup of coffee". That was the wrong move, don't do it. Your board file (for me, platform/Device/SiliconLabs/EFR32MG22/include/efr32mg22c224f512im40.h, included from em_device.h, switched by compiler flag EFR32MG22C224F512IM40=1, if you were curious) defines the hardware available, and in this case it specifically does NOT define CRYPTO_PRESENT (I think that flag implies no hardware acceleration), but it does define CRYPTOACC_PRESENT.What ultimately got it working for me was more nuclear than I prefer, but I was done burning time on minimizing the source code. The linker should cull unused symbols anyway, I expect. Here's what I added in addition to the source mentioned by the author:
- mbedtls/library/md.c and sha256.c
- ALL of sl_crypto .c/.h
Step 6: This block of code that imports the mbedTLS config file is present at the top of every .c file in mbedTLS. I ignored this step and I'm fine.
Step 7: "Now you can use mbedTLS" Wonderful, but how? I wish there were better tutorials on this, but I figured it out the hard way. Here's how I got configured and used mbedTLS, adding ECDSA functionality that wasn't there in the minimal library provided:
1. Browse the holy grail mbedtls/include/mbedtls/config.h. This file is both a template and documentation. I knew I wanted ECDSA, so I searched for that, and found:
* \def MBEDTLS_ECDSA_C
* Enable the elliptic curve DSA library.
* Module: library/ecdsa.c
* Requires: MBEDTLS_ECP_C, MBEDTLS_ASN1_WRITE_C, MBEDTLS_ASN1_PARSE_C
This tells you how to enable the feature and its prerequisites, and indirectly tells you the other sources you need to add.
2. Edit the active config file in protocol/bluetooth/ble_stack/inc/soc/mbedtls_config.h. Find the section /* mbed TLS modules */ and add the missing #defines we learned in Step 1: MBEDTLS_ECDSA_C, MBEDTLS_ASN1_WRITE_C, MBEDTLS_ASN1_PARSE_C. Note that MBEDTLS_ECP_C is already included.
3. Add dependency sources: mbedtls/library/asn1parse.c and asn1write.c. If you didn't go nuclear option and import all headers, you'll have to import mbedtls/include/mbedtls/asn1.h and asn1write.h
4. To use ECDSA, I can now #include "mbedtls/ecdsa.h", then call its functions.
I have auth.h do that #include and declare my wrapper functions, and auth.c includes auth.h and calls mbedtls_ecdsa_init(&ctx); etc.
A. I am just beginning to learn how to use their ECDSA library (and ECDSA is still just theory to me), and all I can say is I made a successful call to that function, it compiled and ran. Fingers crossed it all works correctly when I flesh out the details.
B. I suspect this method of including ECDSA may not be hardware-accelerated. I see some ECDSA sources in the cryptoacc folder, but I haven't put the time into that, and may not at this point.
Other notes on what I learned the hard way in the past week:
What I learned along the way:
- mbedTLS is very modular, and allows for cherry-picking the features that are enabled
in a build. Furthermore, it enables manufacturers (e.g. SiLabs) to provide their own
alternate implementations of cryptographic functions that make use of their hardware.
This is done using the *_ALT family of #defines in the config file.
The config file by default is mbedtls/include/mbedtls/config.h, but most .c files
contain an #ifdef MBEDTLS_CONFIG_FILE block at the top to use an alternate config file.
SiliconLabs provides their own in protocol/bluetooth/ble_stack/inc/soc/mbedtls_config.h
- Silicon Labs provides their own alternate hardware-accelerated implementations of
common cryptographic functions in the sl_crypto folder
- The functionality built into the pre-built library libmbedtls.a is minimal, limited to the
needs of the BLE stack. Presumably it was built as configured by mbedtls_config.h
- To use features that are not included by the provided mbedTLS library, it must be expanded.
This can be done by modifying the project local copy of mbedtls_config.h and including
the source code in the project. (Alternatively, mbedTLS could be modified as a separate
project and rebuilt as libmbedtls.a, then only the headers would be needed in the application.)
I hope this helps somebody. It would have helped me tremendously a week ago. Cheers!