Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make legacy declarations private: macro guard, cipher #132

Open
wants to merge 3 commits into
base: development
Choose a base branch
from
Open

Make legacy declarations private: macro guard, cipher #132

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
276a9e3
private_access.h: Improve documentation
gilles-peskine-arm Dec 23, 2024
c49eb7f
Introduce MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS
gilles-peskine-arm Dec 23, 2024
e3abfab
Make cipher functions private
gilles-peskine-arm Dec 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions drivers/builtin/include/mbedtls/cipher.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -367,6 +367,9 @@ typedef struct mbedtls_cipher_context_t {

} mbedtls_cipher_context_t;


#if defined(MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS)

/**
* \brief This function retrieves the list of ciphers supported
* by the generic cipher module.
Expand Down Expand Up @@ -1164,6 +1167,9 @@ int mbedtls_cipher_auth_decrypt_ext(mbedtls_cipher_context_t *ctx,
unsigned char *output, size_t output_len,
size_t *olen, size_t tag_len);
#endif /* MBEDTLS_CIPHER_MODE_AEAD || MBEDTLS_NIST_KW_C */

#endif /* MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS */
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be convenient to additionally annotate all function declarations between #if defined(MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS) and the corresponding #endif with MBEDTLS_DECLARE_PRIVATE_FUNCTION which can be defined to expand to something like __attribute__((__deprecated__)). This would allow detecting the uses of private functions through compiler warnings, and gradually eliminating them by eliminating warnings.

We can add these annotations mechanically, once we've manually added the preprocessor guards.


#ifdef __cplusplus
}
#endif
Expand Down
35 changes: 34 additions & 1 deletion drivers/builtin/include/mbedtls/private_access.h
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,10 @@
/**
* \file private_access.h
*
* \brief Macro wrapper for struct's members.
* \brief Optionally activate declarations of private identifiers
* in public headers.
*
* This header is reserved for internal use in TF-PSA-Crypto and Mbed TLS.
*/
/*
* Copyright The Mbed TLS Contributors
Expand All @@ -12,9 +15,39 @@
#define MBEDTLS_PRIVATE_ACCESS_H

#ifndef MBEDTLS_ALLOW_PRIVATE_ACCESS
/* Public use: do not declare private identifiers. */

/* Pseudo-hide an identifier (typically a struct or union member) by giving
* it the prefix `private_`.
*
* Typical usage:
* ```
* typedef struct {
* int MBEDTLS_PRIVATE(foo); // private member (not part of the public API,
* // but part of the ABI)
* int bar; // public member (covered by API stability guarantees)
* } mbedtls_some_type_t;
* ```
*/
#define MBEDTLS_PRIVATE(member) private_##member

#else
/* Private use: declare private identifiers. */

#define MBEDTLS_PRIVATE(member) member

/* Activate declarations guarded by this macro.
*
* Typical usage:
* ```
* typedef ... mbedtls_some_type_t; // built-in crypto type
* #if defined(MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS)
* int mbedtls_some_function(...); // built-in crypto function
* #endif // MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS
* ```
*/
#define MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS

#endif

#endif /* MBEDTLS_PRIVATE_ACCESS_H */