Document (with examples) how to integrate a third-party driver with Mbed TLS

[aditya-deshpande-arm]

Description

There is not much documentation on how a driver or software accelerator can be integrated alongside Mbed TLS. The proposed PSA Driver Interface, which aims to auto-generate driver wrappers, has only been partially implemented. It would be useful to have a guide in the interim which shows how to integrate drivers for operations for whom auto code-gen has not been implemented.

p256-m has been used as an example driver to show how a third party driver can be used with Mbed TLS.

TODO before merge

• Build p256-m with Mbed TLS
• Write driver interface functions
• Write Documentation
• Needs preceding PR Add driver dispatch layer for raw key agreement, along with test call for transparent drivers. #6426 to be merged DONE
• Needs preceding PR check_names.py: Compare identifiers in excluded files against symbols parsed by nm #6938 to be merged DONE

Note: all_u16-check_files is expected to fail on PR-Head . This is because the version of check_files.py on this branch does not allow for box drawings characters. PR #6982 allows these characters and has been merged. all_u16-check_files should pass on PR-Merge.

Gatekeeper checklist

• changelog not required, documentation changes only (unless addition of a new config option warrants one?)
• backport not required
• testsnot required

[daverodgman]

Should this explicitly state copyright? @mpg

[mpg]

Now that you mention it, I think it should.

[daverodgman]

Please include a short readme in 3rdparty/p-256m/README.md, similar to the one for Everest, that explains where the code comes from, license, etc, and a brief explanation of what it's for.

[aditya-deshpande-arm]

Please include a short readme in 3rdparty/p-256m/README.md, similar to the one for Everest, that explains where the code comes from, license, etc, and a brief explanation of what it's for.

Done

[daverodgman]

Reminder: we need to check the process defined in https://confluence.arm.com/display/OSS/Including+third+party+open+source+in+an+Arm+OSS+project

Discussed with Aditya and agreed:

• licenses are compatible (both Apache 2)
• this does not change the scope of approval for Mbed TLS (it does not add new features, only new implementations of existing features)
• the changes to p256-m are minor configuration changes (adding a RNG)

As per the checklist

• all license files, notices and headers are retained - no, missing the README. Maybe cleaner to rename the license file to LICENSE as per the original.
• Add a note to the main project README - not done
• nice-to-have: put third party code in separate directory
• extra-nice-to-have: create a top-level SPDX document - out of scope for this PR

When these are all concluded, please email OSRB as an FYI, linking them to this PR, and give them the opportunity to respond (let's say 2 weeks) before we merge. I don't expect they will request any changes or have any concerns, but best to keep them informed.

[aditya-deshpande-arm]

Reminder: we need to check the process defined in https://confluence.arm.com/display/OSS/Including+third+party+open+source+in+an+Arm+OSS+project

Discussed with Aditya and agreed:

• licenses are compatible (both Apache 2)
• this does not change the scope of approval for Mbed TLS (it does not add new features, only new implementations of existing features)
• the changes to p256-m are minor configuration changes (adding a RNG)

As per the checklist

• all license files, notices and headers are retained - no, missing the README. Maybe cleaner to rename the license file to LICENSE as per the original.
• Add a note to the main project README - not done
• nice-to-have: put third party code in separate directory
• extra-nice-to-have: create a top-level SPDX document - out of scope for this PR

When these are all concluded, please email OSRB as an FYI, linking them to this PR, and give them the opportunity to respond (let's say 2 weeks) before we merge. I don't expect they will request any changes or have any concerns, but best to keep them informed.

Added the README from the p256-m repo in its original form. It should be noted however that it mentions scripts/files from the original repo that were not copied to mbedtls (should we edit these out?). I've also renamed the license file to LICENSE.

The License section of the mbedtls project README has been updated so that it mentions both everest and p256-m.

[daverodgman]

Added the README from the p256-m repo in its original form. It should be noted however that it mentions scripts/files from the original repo that were not copied to mbedtls (should we edit these out?). I've also renamed the license file to LICENSE.

I think the simplest thing is just to add a short note at the top of the README that explains this.

[aditya-deshpande-arm]

Had to make a few further changes to make the CI happy, but it's ready to go now.

[daverodgman]

LGTM

[mpg]

LGTM

[mpg]

• tests not required

Really? This PR contains a non-trivial amount of code in p256-m_driver_entrypoints.c and I can't see any reason why this code shouldn't be tested.

@daverodgman I think you and I failed to notice, as reviewers, that this PR lacks testing. Two things should have alerted us:

1. a non-trivial amount of C code is introduced, so we should have made sure it was covered (ideally even measured its coverage);
2. a new config option was added, so we should have made sure that all.sh tests at least one config when it's disabled (OK, default and full) and one config where it's enabled (none currently).

Not the end of the world, but let's be more careful in the future. Tests are being added in #8032 now.