Deprecations
To ensure backwards-compatibility between versions of Mbed TLS, elements of the public interface may not be removed except during the release of a new major version. Instead, they may be ‘deprecated’, indicating to users that they will be removed in the future.
When a build is made with MBEDTLS_DEPRECATED_WARNING
defined, a compiler warning will be generated to warn a user that a function or constant will be removed at some point in the future, notifying users that they should change to a replacement function or constant at their own convenience. Note: this only works when using GCC-like compilers that recognize __attribute__((deprecated))
.
To find examples of past deprecations, look at the previous major version of Mbed TLS.
Deprecating functions
To deprecate a function, the following actions must be taken:
In the header file (e.g.
include/mbedtls/xyz.h
):Surround the function declaration with
#if !defined(MBEDTLS_DEPRECATED_REMOVED)
.Add a line to the docstring consisting of the keyword
\deprecated
followed by the reason for deprecation and (where applicable) the function it is superseded by.Add the
MBEDTLS_DEPRECATED
annotation to the function prototype (soint foo();
becomesint MBEDTLS_DEPRECATED foo();
).Make sure the header file includes
mbedtls/platform_util.h
(this contains the definition ofMBEDTLS_DEPRECATED
).
In the source file (e.g.
library/xyz.c
):Surround the function definition with
#if !defined(MBEDTLS_DEPRECATED_REMOVED)
.If the function is superseded, ensure there is no code duplication between the old function and the new one. Typically this means refactoring the old function to be a simple wrapper around the new function.
In a new file in ChangeLog.d (e.g.
ChangeLog.d/change-xyz-api.txt
)Add an entry under the heading
New deprecations
that describes the deprecation. See the ChangeLog readme for more information on the format of ChangeLog entries.
In the function’s unit tests (see the test guidelines for more information on unit tests):
Add
MBEDTLS_TEST_DEPRECATED
to thedepends_on:
line in the.function
file that tests the deprecated function.If there are test functions that can test either the deprecated function or the replacement, they may use the directive
#if defined(MBEDTLS_TEST_DEPRECATED)
to select the function to use.
Deprecating constants
Numeric and string constants can also be deprecated by wrapping them in the macros MBEDTLS_DEPRECATED_NUMERIC_CONSTANT()
and MBEDTLS_DEPRECATED_STRING_CONSTANT()
respectively. For example, the code:
const int X = 42;
would become:
const int X = MBEDTLS_DEPRECATED_NUMERIC_CONSTANT(42);
The file where the constant is defined must include mbedtls/platform_util.h
as it contains the definition of MBEDTLS_DEPRECATED_NUMERIC_CONSTANT
.
Any testcases (in .data
files) that use the deprecated constant must have MBEDTLS_TEST_DEPRECATED
added to their depends_on:
line.
Partial deprecation
From time to time it is necessary to deprecate one specific aspect of a function. For example, calling a function in a particular mode or with a particular parameter may be deprecated. In this case, simply add a line to the function’s doxygen description explaining the deprecation. For example:
/**
* \brief This function divides x by y
*
* \deprecated It is deprecated to call this function with y = 0.
* Future versions of this function will return an error
* when called with y = 0, rather than returning INT_MAX as
* is the current behaviour.
*
* ...
*/