Move public legacy headers to /include/mbedtls

[felixc-arm]

Moves public headers from /drivers/builtin/include/mbedtls to /include/mbedtls to make it clear that they are public.
Resolves #223, although there may be further work to move these headers somewhere else, e.g. /include/tf-psa-crypto.

List of files moved for reference:

asn1.h
asn1write.h
base64.h
constant_time.h
lms.h
memory_buffer_alloc.h
nist_kw.h
pem.h
pk.h
platform.h
platform_time.h
platform_util.h
psa_util.h
threading.h

PR checklist

• changelog not required because: no change in user-facing functionality
• framework PR provided: Adjust scripts to accommodate public header move mbedtls-framework#156
• mbedtls development PR provided: Adjust build scripts to accommodate public header move mbedtls#10122
• mbedtls 3.6 PR not required because: work for 4.0/1.0
• tests not required because: no functional changes

[gilles-peskine-arm]

There are probably build scripts that need to be updated. For example include/CMakeLists.txt has

    file(GLOB tf-psa-crypto_headers "tf-psa-crypto/*.h")
    file(GLOB mbedtls_crypto_headers "../drivers/builtin/include/mbedtls/*.h")

and presumably there needs to be a line for "mbedtls/*.h". I don't know whether it should be one of these variables or yet another one: I don't know what the difference is between those variables.

[felixc-arm]

The companion PR Mbed-TLS/mbedtls#10122 has now passed the CI

[valeriosetti]

The PR looks mostly OK to me. I only left 1 question

[gilles-peskine-arm]

The CI is unhappy here. Is the companion mbedtls pull request needed to make it happy?

[mpg]

Sounds like a plan. Indeed those doxygen errors are actual issues that we want to address (as opposed to just silence), so let's do it - but proceed step by step, starting with getting this PR merged without the doxygen change for now.

[felixc-arm]

Cool, I've created #281 to track this Doxygen work.

I've also reverted that commit so everything should be good to review again, although it makes sense to wait until after #212 and its mbedtls PR get merged so that I can rebase on top of that to avoid extra reviews/pings.

[felixc-arm]

This is all ready for review again (just a rebase) when you've got a moment @bjwtaylor @valeriosetti

n.b. The failure in OpenCI seems to be an intermittent one that is not related to this PR, and I'd replay it but I don't think I have the permissions or am not in a certain group or something as I can't see a replay button even though I'm logged in (but I can see a rerun button for the internal CI)

[gilles-peskine-arm]

The failure in https://mbedtls.trustedfirmware.org/blue/organizations/jenkins/mbed-tls-tf-psa-crypto-multibranch/detail/PR-247-head/9/pipeline/1211 doesn't look like a glitch:

/var/lib/build/core/psa_crypto.c:21:10: fatal error: 'psa_crypto_driver_wrappers.h' file not found
#include "psa_crypto_driver_wrappers.h"
         ^
/var/lib/build/core/psa_crypto.c:21:10: fatal error: 'psa_crypto_driver_wrappers.h' file not found
#include "psa_crypto_driver_wrappers.h"
         ^
1 error generated.
core/CMakeFiles/tfpsacrypto_static.dir/build.make:71: recipe for target 'core/CMakeFiles/tfpsacrypto_static.dir/psa_crypto.c.o' failed
make[2]: *** [core/CMakeFiles/tfpsacrypto_static.dir/psa_crypto.c.o] Error 1
CMakeFiles/Makefile2:329: recipe for target 'core/CMakeFiles/tfpsacrypto_static.dir/all' failed
make[1]: *** [core/CMakeFiles/tfpsacrypto_static.dir/all] Error 2
make[1]: *** Waiting for unfinished jobs....
[ 31%] Building C object core/CMakeFiles/tfpsacrypto.dir/psa_crypto_client.c.o
1 error generated.
core/CMakeFiles/tfpsacrypto.dir/build.make:71: recipe for target 'core/CMakeFiles/tfpsacrypto.dir/psa_crypto.c.o' failed
make[2]: *** [core/CMakeFiles/tfpsacrypto.dir/psa_crypto.c.o] Error 1
make[2]: *** Waiting for unfinished jobs....
CMakeFiles/Makefile2:290: recipe for target 'core/CMakeFiles/tfpsacrypto.dir/all' failed
make[1]: *** [core/CMakeFiles/tfpsacrypto.dir/all] Error 2
make: *** [all] Error 2
Makefile:138: recipe for target 'all' failed
^^^^test_tf_psa_crypto_shared: build/test: shared libraries: make -> 2^^^^

It is weird that the internal CI passed though. A non-deterministic failure when building could be a missing build dependency. On the CI, we run make -j2 (at least in builds initiated by make, I'm not completely sure this applies to CMake builds). With parallel builds, sometimes, missing build dependencies are only a problem if the build is executed in a particular order, and are not a problem with sequential builds.

This pull request moves files in a way that could affect dependencies — for example maybe somewhere dependencies are calculated in a way that doesn't take /include/mbedtls into account. Can you please check carefully whether that might be the case?

Experimentally, you may want to try doing build locally with various levels of parallelism and see if it breaks. This can be very sensitive to the level of parallelism, the number of CPUs, how fast the builds are and other factors. For example we used to have a missing dependency that would in practice never be a problem for make -j2 if there was an odd number of files to build, but caused problems frequently if there was an even number! (Or vice versa, I don't remember — but the parity of the number of files was what made make -j2 work or not in practice.)

[felixc-arm]

I'll have a look, but I do remember seeing this exact failure on another patch (found it!: https://mbedtls.trustedfirmware.org/blue/organizations/jenkins/mbed-tls-framework-multibranch/detail/PR-153-head/16/pipeline/2066 for Mbed-TLS/mbedtls-framework#153) that is unrelated, so I don't think it is this specific patch that is causing it at least.

[gilles-peskine-arm]

Ok, then this is probably a preexisting issue, which may be exacerbated by changes that we make. Can you please file an issue and reference all the places where you've seen it happen?

[felixc-arm]

Sure, opened #286 - and I'll rerun the OpenCI now I have permissions to hopefully ensure it's only an intermittent failure... 🙂

[felixc-arm]

The Windows CI seemed to have issues with rerunning after Mbed-TLS/mbedtls-test#203 was merged as it was trying to rerun Windows 2013 jobs whilst looking for 'v141' which I think is Visual Studio 2017 which wasn't installed.
So I've rebased it (again... 🙂) to hopefully re-trigger with the Windows 2017 jobs instead and get everything green.

[gilles-peskine-arm]

The Windows CI seemed to have issues with rerunning after Mbed-TLS/mbedtls-test#203

Ah, FYI this is a subtlety with the rerun/replay button on Jenkins. It replays the same Groovy script as the run that's getting replayed, but it gets its files from a checkout of the main branch of https://github.com/Mbed-TLS/mbedtls-test. If mbedtls-test has moved forward, the Groovy scripts and the rest of mbedtls-test (e.g. windows_testing.py) may be out of synch. To avoid this, run a fresh job instead of using rerun/replay. For example, here, use the “Build Now” button on https://mbedtls.trustedfirmware.org/job/mbed-tls-tf-psa-crypto-multibranch/job/PR-247-head/ rather than replaying a run.

This comes up rarely in normal usage because merges in mbedtls-test are rare, and replays are also rare, but it's something to keep in mind when testing changes in mbedtls-test — always start new jobs after updating your patch to mbedtls-test, because otherwise you won't be testing your latest patch.

[felixc-arm]

I see, good to know the 'build now' button will do a fresh job, cheers!