Dear Mbed TLS users,
Mbed TLS has contained the reference implementation of the PSA Crypto API since the early days of the standard. This implementation was experimental at first, but over years of development it reached maturity, and the experimental status was removed three years ago (in version 3.6.1.).
Shortly after that, in 2022, the TF-PSA-Crypto<https://github.com/Mbed-TLS/TF-PSA-Crypto> repository was created just for the PSA Crypto API implementation to make it more accessible for users only interested in that. This repository was only a mirror of the main one and the development of the PSA Crypto API implementation remained integral part of Mbed TLS.
In the background, work has been started to make this repository the place where the development of the PSA Crypto API reference implementation happens. This work has finally been completed and from now on TF-PSA-Crypto<https://github.com/Mbed-TLS/TF-PSA-Crypto> is ready to receive contributions, bug reports and enhancement requests. TF-PSA-Crypto<https://github.com/Mbed-TLS/TF-PSA-Crypto> will now be the development repository for the PSA Crypto reference implementation.
Mbed TLS will continue to rely on TF-PSA-Crypto<https://github.com/Mbed-TLS/TF-PSA-Crypto> and will be using it as a submodule.
Many thanks,
Janos Follath
Mbed TLS developer
Hi,
Can you give me a little advice on how v3 works?
I've updated our mbed library from 2.16.1 to 3.6.2 which was mostly a very
smooth experience, thanks.
The one question in my mind relates to making p_bio private in
mbedtls_ssl_context
*I used to free it before calling mbedtls_ssl_free - is it ok to skip this
now? ie:*
//mbedtls_net_free((mbedtls_net_context *) m_ssl.p_bio);
mbedtls_ssl_free(&m_ssl);
*I also used to poll it before calling mbedtls_ssl_close_notify - is ok to
skip this now? ie:*
//if(mbedtls_net_poll((mbedtls_net_context *) m_ssl.p_bio,
MBEDTLS_NET_POLL_WRITE, 0) < 0)
// return;
int ret;
while((ret = mbedtls_ssl_close_notify(&m_ssl)) < 0)
{
if(ret != MBEDTLS_ERR_SSL_WANT_READ &&
ret != MBEDTLS_ERR_SSL_WANT_WRITE)
return;
}
It all seems to run just fine like this, but I could really do with some
confidence boosting validation of my cavalier commenting.
Thank you
Daniel
Dear Mbed TLS team,
I am trying to integrate Mbed TLS in our platform:
- nxp imx rt 1024 CPU (arm based)
- FreeRTOS (10.6)
- Lwip (2.2)
- Mbed TLS (3.6.2)
LWIP supports Mbed TLS when adding defines in their configuration:
/* ---------- TLS ------------------------- */
#define LWIP_ALTCP 1
#define LWIP_ALTCP_TLS 1
#define LWIP_ALTCP_TLS_MBEDTLS 1
But, unfortunately this supports an older version of Mbed TLS (I believe
2.2.x).
When I try to compile against the Mbed TLS 3.6.2 libraries, I get a bunch
of compiler warnings / errors. Most of them are mentioned in the migration
guide, but even then, I have a hard time figuring out how to resolve them
"the right way".
1. Private fields
The migration guide
<https://github.com/Mbed-TLS/mbedtls/blob/mbedtls-3.6/docs/3.0-migration-gui…>
explains that most structs are now considered private.
1.1: The altcp_mbed module in LWIP relies on the *out_left* field of the *ssl
context* struct.
/* calculate TLS overhead part to not send it to application */
overhead = state->overhead_bytes_adjust + state->ssl_context.out_left;
I am correct that this field is simply not exposed through accessor
functions? I can find functions like mbedtls_ssl_get_avail, so I would
expect something like mbedtls_ssl_get_bytes_to_write or something like that?
1.2: The altcp_mbed module in LWIP relies on the *start* field of the *ssl
session* struct.
err_t
altcp_tls_set_session(struct altcp_pcb *conn, struct altcp_tls_session
*session)
{
if (session && conn && conn->state) {
altcp_mbedtls_state_t *state = (altcp_mbedtls_state_t *)conn->state;
int ret = -1;
* if (session->data.start)*
ret = mbedtls_ssl_set_session(&state->ssl_context, &session->data);
return ret < 0 ? ERR_VAL : ERR_OK;
}
return ERR_ARG;
}
I also don't know how to obtain this field "the right way". I know this is
a bad idea, but it's all I got
if (session->data.*private_start)* ...
2. parse key expects a RNG function
This is also explained in the migration guide:
*Some functions gained an RNG parameterThis affects users of the following
functions: `mbedtls_ecp_check_pub_priv()`,`mbedtls_pk_check_pair()`,
`mbedtls_pk_parse_key()`, and`mbedtls_pk_parse_keyfile()`.You now need to
pass a properly seeded, cryptographically secure RNG whencalling these
functions. It is used for blinding, a countermeasure againstside-channel
attacks.*
Can you please give me some guidance here? I looked for examples in Mbed
TLS repo and ended up with this (bold parts are added, using the key_app.c
in your repo as leading example):
* mbedtls_entropy_context entropy; mbedtls_ctr_drbg_context ctr_drbg;
mbedtls_entropy_init(&entropy); mbedtls_ctr_drbg_init(&ctr_drbg); if
((ret = mbedtls_ctr_drbg_seed( &ctr_drbg,
mbedtls_entropy_func, &entropy, privkey,
privkey_len)) != 0) { // TODO: handle error } *
ret = mbedtls_pk_parse_key(
conf->pkey, privkey,
privkey_len,
privkey_pass,
privkey_pass_len,
*mbedtls_ctr_drbg_random, &ctr_drbg*);
3. The altcp_mbed module in LWIP relies on mbedtls_ssl_flush_output
The altcp_mbed module had an include on ssl internal.
#include "mbedtls/ssl_internal.h" /* to call mbedtls_flush_output after
ERR_MEM */
This header seems no longer part of the library. But the prototype of the
function is now part of ssl_misc.h, but I don't think I am supposed to rely
on this header either.
I have a couple of options:
- ignore the compiler warning
/home/dev_container/app/thirdparty/lwip/src/apps/altcp_tls/altcp_tls_mbedtls.c:535:5:
warning: implicit declaration of function 'mbedtls_ssl_flush_output'; did
you mean 'mbedtls_ssl_tls_prf'? [-Wimplicit-function-declaration]
535 | mbedtls_ssl_flush_output(&state->ssl_context);
- copy paste the declaration in the LWIP source file
- Or.... don't flush any buffers managed by Mbed TLS in the first place?
For the last one, I could really use your input. Can you say anything
meaningful about the flush (line in bold) In the below function, Is it
mandatory? Or can I trust the Mbed TLS will flush the output buffer
whenever it needs to get flushed?
/** Sent callback from lower connection (i.e. TCP)
* This only informs the upper layer the number of ACKed bytes.
* This now take care of TLS added bytes so application receive
* correct ACKed bytes.
*/
static err_t
altcp_mbedtls_lower_sent(void *arg, struct altcp_pcb *inner_conn, u16_t len)
{
struct altcp_pcb *conn = (struct altcp_pcb *)arg;
LWIP_UNUSED_ARG(inner_conn); /* for LWIP_NOASSERT */
if (conn) {
int overhead;
u16_t app_len;
altcp_mbedtls_state_t *state = (altcp_mbedtls_state_t *)conn->state;
LWIP_ASSERT("state", state != NULL);
LWIP_ASSERT("pcb mismatch", conn->inner_conn == inner_conn);
/* calculate TLS overhead part to not send it to application */
mbedtls_ssl_get_bytes_avail(&state->ssl_context);
overhead = state->overhead_bytes_adjust +
state->ssl_context.private_out_left;
if ((unsigned)overhead > len) {
overhead = len;
}
/* remove ACKed bytes from overhead adjust counter */
state->overhead_bytes_adjust -= len;
/* try to send more if we failed before (may increase overhead adjust
counter) */
*mbedtls_ssl_flush_output(&state->ssl_context); // Does it make sense
this LWIP port is responsible for flushing here??*
/* remove calculated overhead from ACKed bytes len */
app_len = len - (u16_t)overhead;
/* update application write counter and inform application */
if (app_len) {
state->overhead_bytes_adjust += app_len;
if (conn->sent)
return conn->sent(conn->arg, conn, app_len);
}
}
return ERR_OK;
}
After applying the changes I mentioned above, the software compiles against
Mbed TLS. I haven't dared to run anything, I just want to enjoy this short
moment where I have the feeling I achieved something before runtime errors
ruin my day :).
Many thanks in advance for any reply!
Best regards, Bas
[image: image.png]
Hi Team
I am investigating the move from MbedTLS 2.25 to 3.6, however, our client uses the 2.25 currently (looks like they prefer to stay with it) and I need to provide convincing proof to move to 3.6 considering the upgrade issues that might arise. Any suggestions here that is convincing proof to do the migration to 3.6? I would appreciate your comments. Thanks
Michael
Dear Mbed TLS team,
I am at the early steps of trying to integrate Mbed TLS with LWIP for our
project (imx rt 1024 NXP micro, arm M7, running FreeRTOS and LWIP). I
understand the basics of TLS, but I am far from an expert.
Let me first apologise for the lengthy first email. I am afraid to leave
out details. Feel free to skip directly to the end marked with:
=============================
My questions:
=============================
Some background / translation of how I think it (should) work:
From a distance, I understand that LWIP has an abstraction layer on their
TCP module, which can be used to integrate Mbed TLS.
In fact, LWIP already did this, all I need to do is enable some directives
(LWIP_ALTCP_TLS and LWIP_ALTCP_TLS_MBEDTLS).
The implemented integration assumes a somewhat older version of Mbed TLS,
so I have to adjust a couple to cope with the breaking changes from Mbed
TLS 2.x to Mbed TLS 3.6.2.
But other than that, integrating Mbed TLS would mean:
- figure out which options i want to enable in Mbed TLS
- cross compile it for our arm toolchain
- extend our build scripts to compile against 3 static Mbed TLS libraries
- figure out how to read the CA certificates, and provide them to Mbed TLS
- test and fail, and hopefully be man enough to solve the challenges
ahead...
I haven't achieved much yet, but at least I managed to compile Mbed TLS
with our toolchain and recompile our project against the linked libraries.
This steps fails though, I get a bunch of linker errors :
[100%] Linking CXX executable app.axf
/opt/gcc-arm-none-eabi/bin/../lib/gcc/arm-none-eabi/13.2.1/../../../../arm-none-eabi/bin/ld:
/home/dev/app/source/iobox-app/../../thirdparty/mbedtls/build/library/libmbedtls.a(ssl_msg.c.obj):
in function `mbedtls_ssl_encrypt_buf':
/home/dev/app/thirdparty/mbedtls/library/ssl_msg.c:1211:(.text.mbedtls_ssl_encrypt_buf+0x1b4):
undefined reference to `mbedtls_cipher_auth_encrypt_ext'
/opt/gcc-arm-none-eabi/bin/../lib/gcc/arm-none-eabi/13.2.1/../../../../arm-none-eabi/bin/ld:
/home/dev/app/source/iobox-app/../../thirdparty/mbedtls/build/library/libmbedtls.a(ssl_msg.c.obj):
in function `mbedtls_ssl_decrypt_buf':
/home/dev/app/thirdparty/mbedtls/library/ssl_msg.c:1638:(.text.mbedtls_ssl_decrypt_buf+0x180):
undefined reference to `mbedtls_cipher_auth_decrypt_ext'
/opt/gcc-arm-none-eabi/bin/../lib/gcc/arm-none-eabi/13.2.1/../../../../arm-none-eabi/bin/ld:
/home/dev/app/source/iobox-app/../../thirdparty/mbedtls/build/library/libmbedtls.a(ssl_msg.c.obj):
in function `mbedtls_ssl_transform_free':
/home/dev/app/thirdparty/mbedtls/library/ssl_msg.c:6213:(.text.mbedtls_ssl_transform_free+0x14):
undefined reference to `mbedtls_cipher_free'
/opt/gcc-arm-none-eabi/bin/../lib/gcc/arm-none-eabi/13.2.1/../../../../arm-none-eabi/bin/ld:
/home/dev/app/thirdparty/mbedtls/library/ssl_msg.c:6214:(.text.mbedtls_ssl_transform_free+0x1e):
undefined reference to `mbedtls_cipher_free'
/opt/gcc-arm-none-eabi/bin/../lib/gcc/arm-none-eabi/13.2.1/../../../../arm-none-eabi/bin/ld:
/home/dev/app/source/iobox-app/../../thirdparty/mbedtls/build/library/libmbedtls.a(ssl_tls.c.obj):
in function `mbedtls_ssl_transform_init':
/home/dev/app/thirdparty/mbedtls/library/ssl_tls.c:1028:(.text.mbedtls_ssl_transform_init+0x18):
undefined reference to `mbedtls_cipher_init'
/opt/gcc-arm-none-eabi/bin/../lib/gcc/arm-none-eabi/13.2.1/../../../../arm-none-eabi/bin/ld:
/home/dev/app/thirdparty/mbedtls/library/ssl_tls.c:1029:(.text.mbedtls_ssl_transform_init+0x22):
undefined reference to `mbedtls_cipher_init'
/opt/gcc-arm-none-eabi/bin/../lib/gcc/arm-none-eabi/13.2.1/../../../../arm-none-eabi/bin/ld:
/home/dev/app/source/iobox-app/../../thirdparty/mbedtls/build/library/libmbedtls.a(ssl_tls.c.obj):
in function `mbedtls_ssl_get_mode_from_ciphersuite':
/home/dev/app/thirdparty/mbedtls/library/ssl_tls.c:2453:(.text.mbedtls_ssl_get_mode_from_ciphersuite+0x12):
undefined reference to `mbedtls_cipher_info_from_type'
/opt/gcc-arm-none-eabi/bin/../lib/gcc/arm-none-eabi/13.2.1/../../../../arm-none-eabi/bin/ld:
/home/dev/app/source/iobox-app/../../thirdparty/mbedtls/build/library/libmbedtls.a(ssl_tls.c.obj):
in function `mbedtls_ssl_parse_finished':
/home/dev/app/thirdparty/mbedtls/library/ssl_tls.c:8680:(.text.mbedtls_ssl_parse_finished+0xac):
undefined reference to `mbedtls_ct_memcmp'
/opt/gcc-arm-none-eabi/bin/../lib/gcc/arm-none-eabi/13.2.1/../../../../arm-none-eabi/bin/ld:
/home/dev/app/source/iobox-app/../../thirdparty/mbedtls/build/library/libmbedtls.a(ssl_tls.c.obj):
in function `ssl_tls12_populate_transform':
/home/dev/app/thirdparty/mbedtls/library/ssl_tls.c:8878:(.text.ssl_tls12_populate_transform+0xa6):
undefined reference to `mbedtls_cipher_info_from_type'
/opt/gcc-arm-none-eabi/bin/../lib/gcc/arm-none-eabi/13.2.1/../../../../arm-none-eabi/bin/ld:
/home/dev/app/thirdparty/mbedtls/library/ssl_tls.c:9136:(.text.ssl_tls12_populate_transform+0x454):
undefined reference to `mbedtls_cipher_setup'
/opt/gcc-arm-none-eabi/bin/../lib/gcc/arm-none-eabi/13.2.1/../../../../arm-none-eabi/bin/ld:
/home/dev/app/thirdparty/mbedtls/library/ssl_tls.c:9142:(.text.ssl_tls12_populate_transform+0x476):
undefined reference to `mbedtls_cipher_setup'
/opt/gcc-arm-none-eabi/bin/../lib/gcc/arm-none-eabi/13.2.1/../../../../arm-none-eabi/bin/ld:
/home/dev/app/thirdparty/mbedtls/library/ssl_tls.c:9148:(.text.ssl_tls12_populate_transform+0x4a8):
undefined reference to `mbedtls_cipher_setkey'
/opt/gcc-arm-none-eabi/bin/../lib/gcc/arm-none-eabi/13.2.1/../../../../arm-none-eabi/bin/ld:
/home/dev/app/thirdparty/mbedtls/library/ssl_tls.c:9155:(.text.ssl_tls12_populate_transform+0x4da):
undefined reference to `mbedtls_cipher_setkey'
/opt/gcc-arm-none-eabi/bin/../lib/gcc/arm-none-eabi/13.2.1/../../../../arm-none-eabi/bin/ld:
CMakeFiles/app.dir/home/dev/app/thirdparty/lwip/src/apps/altcp_tls/altcp_tls_mbedtls.c.obj:
in function `altcp_mbedtls_sndbuf':
/home/dev/app/thirdparty/lwip/src/apps/altcp_tls/altcp_tls_mbedtls.c:1192:(.text.altcp_mbedtls_sndbuf+0x7e):
undefined reference to `mbedtls_ssl_get_max_frag_len'
/opt/gcc-arm-none-eabi/bin/../lib/gcc/arm-none-eabi/13.2.1/../../../../arm-none-eabi/bin/ld:
/home/dev/app/source/iobox-app/../../thirdparty/mbedtls/build/library/libmbedtls.a(ssl_tls12_server.c.obj):
in function `ssl_parse_client_psk_identity':
/home/dev/app/thirdparty/mbedtls/library/ssl_tls12_server.c:3638:(.text.ssl_parse_client_psk_identity+0xb6):
undefined reference to `mbedtls_ct_memcmp'
The distinct list undefined references of the above:
undefined reference to `mbedtls_cipher_auth_encrypt_ext'
undefined reference to `mbedtls_cipher_auth_decrypt_ext'
undefined reference to `mbedtls_cipher_free'
undefined reference to `mbedtls_cipher_init'
undefined reference to `mbedtls_cipher_info_from_type'
undefined reference to `mbedtls_ct_memcmp'
undefined reference to `mbedtls_cipher_setup'
undefined reference to `mbedtls_cipher_setup'
undefined reference to `mbedtls_cipher_setkey'
undefined reference to `mbedtls_cipher_setkey'
undefined reference to `mbedtls_ssl_get_max_frag_len'
All except the last one are coming from Mbed TSL internally, so I *guess*
this means I am missing options? Or maybe I am still having too many?
The last one is called from the LWIP integration of Mbed TLS, and I could
"sweep this under the carpet" by disabling
"MBEDTLS_SSL_MAX_FRAGMENT_LENGTH". But I haven't looked further in what I
cause if I do not support "RFC 6066 max_fragment_length extension in SSL"
My Mbed TLS configuration:
I followed the suggestion of your documentation, and went for a minimal
example configuration. Pure on intuition, I went for
"config-ccm-psk-dtls1_2.h". Because the file name suggests it brings TSL
1.2 which is basically all I need. I think.
I did had to make the following changes in order to be able to compile it:
1. Comment out two defines in order to get rid of module requiring
"windows or unix"
//#define MBEDTLS_NET_C
//#define MBEDTLS_TIMING_C
2. Add a define, again to get rid of the compiler error "require windows or
unix"
#define MBEDTLS_NO_PLATFORM_ENTROPY
After applying these small changes to the include/mbedtls/mbedtls_config.h
I was able to cross compile (and link) Mbed TLS with arm-none-eabi
toolchain.
Once I adjusted the build scripts to lnk against the Mbed TLS static
libraries, I finally ended up with the earlier mentioned linker errors.
=============================
My questions:
=============================
1. Does my starting point configuration make sense?
As mentioned earlier, pure intuition made me try the
"config-ccm-psk-dtls1_2.h" configuration example, which after some
modifications compiled and produced 3 static libraries. but, this bit in
the example header worries me a bit:
* Distinguishing features:
* - Optimized for small code size, low bandwidth (on an unreliable
transport),
* and low RAM usage.
* - No asymmetric cryptography (no certificates, no Diffie-Hellman key
* exchange).
* - Fully modern and secure (provided the pre-shared keys are generated and
* stored securely).
* - Very low record overhead with CCM-8.
* - Includes several optional DTLS features typically used in IoT.
What does "no asymmetric cryptography" exactly mean? Isn't that the pure
basis of TLS altogether?
If I want to achieve HTTPS using TLS, is this a good starting point?
2. Undefined references: wrong configuration, or should I supply some of
the implementations?
As mentioned before, I have quite a few linking errors related to the
cipher module. I tried to find answers in the documentation, but came up
empty.
I assume (again...) that I should be able to get rid of these linking
errors by enabling more features in Mbed TLS. But I honestly get lost in
#define's. And maybe it's documented somewhere, but I couldn't find it.
3. Root CA provided by me?
I assume I *need* to provide at least one root CA for Mbed TLS to be able
to verify the public key provided by the server, at some point, right? I
would expect some callback I need to implement where such a root CA was
read (in my case, i would have to read if from flash). Am I
misunderstanding Mbed TLS on this aspect also? Or did I just miss the
obvious spot where to Mbed TLS requests a root CA?
4. More examples available for typical microcontroller projects
(FreeRTOS/LWIP)?
My experience so far is:
- Mbed TLS is well documented
- LWIP is no longer actively maintained, and lacks documentation in general
- Google finds a painful amount of LWIP/TLS integrations which are based on
really old implementations of both, which does more harm than good for me
- Chat GPT knows everything, even when it doesn't, which is a really great
recipe to get on the wrong track... It doesn't seem rather helpful on my
integration questions for Mbed TLS/LWIP. Disclaimer: could be that my lack
of knowledge is causing gpt to come up with wrong answers of course...
I understand that my email is (too?) long, and that the chance somebody
will actually find the time to help me out is limited.
I expect nothing,
I hope for everything :)
ANY help is more than welcome. Good references, links to official
documentation I missed, or in the best case: answers to my
questions/uncertainties.
Many thanks in advance.
Best regards, Bas
