Remove private pk functions from public documentation #205

New issue

Closed

opened 2025-03-14 13:36:47 -05:00 by gilles-peskine-arm · 3 comments

gilles-peskine-arm commented

2025-03-14 13:36:47 -05:00

(Migrated from github.com)

Depends: new PK mostly done, so that it's clear exactly what is going into the 1.0 release.

Do a pass over pk.h to check for remaining obsolete statements and inconsistencies. In particular, check for mentions of API elements that have become private or have been removed.

Get rid any remaining mention of “opaque” in pk.h: it should now only refer to PSA keys that are in a secure element, not to all keys that are in PSA.

Also double-check that mbedtls_pk_type_t is no longer mentioned in any public documentation.

Depends: new PK mostly done, so that it's clear exactly what is going into the 1.0 release. Do a pass over `pk.h` to check for remaining obsolete statements and inconsistencies. In particular, check for mentions of API elements that have become private or have been removed. Get rid any remaining mention of “opaque” in `pk.h`: it should now only refer to PSA keys that are in a secure element, not to all keys that are in PSA. Also double-check that `mbedtls_pk_type_t` is no longer mentioned in any public documentation.

bjwtaylor commented

2025-08-18 05:59:13 -05:00

(Migrated from github.com)

We still have references to mbedtls_pk_type_t in github.com/Mbed-TLS/TF-PSA-Crypto@4a7ae0c096/drivers/builtin/src/pk_wrap.h (L25) which are then referenced in pk.h. Do these need to be removed, or can they be kept?

We still have references to mbedtls_pk_type_t in https://github.com/Mbed-TLS/TF-PSA-Crypto/blob/4a7ae0c096fa81ed6b242c02547ae31642e008fc/drivers/builtin/src/pk_wrap.h#L25 which are then referenced in pk.h. Do these need to be removed, or can they be kept?

gilles-peskine-arm commented

2025-08-25 03:48:48 -05:00

(Migrated from github.com)

pk_wrap.h is internal to TF-PSA-Crypto. mbedtls_pk_type_t will be fully removed eventually, but that can be done as part of the post-1.0 cleanup.

`pk_wrap.h` is internal to TF-PSA-Crypto. `mbedtls_pk_type_t` will be fully removed eventually, but that can be done as part of the post-1.0 cleanup.

mpg commented

2025-09-01 03:01:55 -05:00

(Migrated from github.com)

To clarify, once #344 is completed, public doxygen documentation about PK is only what's left in include/mbedtls/pk.h (all other headers are private). This documentation must not reference things that are no longer public (ie no longer in this header).

Also, docs/psa-transition.md and docs/4.0-migration-guide/* are public documentation about PK. They should not reference things that are no longer in include/mbedtls/pk.h - except of course to say they have been removed. Edit: ah, but those are covered by a separate task: #209. So I'd say this task is just about making include/mbedtls/pk.h free of references to things that are no longe there.

To clarify, once #344 is completed, public doxygen documentation about PK is only what's left in `include/mbedtls/pk.h` (all other headers are private). This documentation must not reference things that are no longer public (ie no longer in this header). Also, `docs/psa-transition.md` and `docs/4.0-migration-guide/*` are public documentation about PK. They should not reference things that are no longer in `include/mbedtls/pk.h` - except of course to say they have been removed. Edit: ah, but those are covered by a separate task: #209. So I'd say this task is just about making `include/mbedtls/pk.h` free of references to things that are no longe there.

No milestone

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

gh-Mbed-TLS/TF-PSA-Crypto#205

No description provided.

Rows
Columns