From 0289c19b8aefbaa5d5ba930ceab4d4489a05916d Mon Sep 17 00:00:00 2001 From: Tom Cosgrove Date: Fri, 10 Feb 2023 12:52:13 +0000 Subject: [PATCH 01/51] Don't use lstrlenW() on Windows The lstrlenW() function isn't available to UWP apps, and isn't necessary, since when given -1, WideCharToMultiByte() will process the terminating null character itself (and the length returned by the function includes this character). Resolves #2994 Signed-off-by: Tom Cosgrove --- library/x509_crt.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/library/x509_crt.c b/library/x509_crt.c index cb2740fba..e7fcaf462 100644 --- a/library/x509_crt.c +++ b/library/x509_crt.c @@ -1601,8 +1601,8 @@ int mbedtls_x509_crt_parse_path(mbedtls_x509_crt *chain, const char *path) } w_ret = WideCharToMultiByte(CP_ACP, 0, file_data.cFileName, - lstrlenW(file_data.cFileName), - p, (int) len - 1, + -1, + p, (int) len, NULL, NULL); if (w_ret == 0) { ret = MBEDTLS_ERR_X509_FILE_IO_ERROR; From cf39406196a2d4d38954c9d036987ad3213a7ae7 Mon Sep 17 00:00:00 2001 From: Andrzej Kurek Date: Wed, 15 Feb 2023 05:42:02 -0500 Subject: [PATCH 02/51] Use config.py as a module in depends.py Signed-off-by: Andrzej Kurek --- tests/scripts/depends.py | 94 ++++++++++++++++++++++++---------------- 1 file changed, 56 insertions(+), 38 deletions(-) diff --git a/tests/scripts/depends.py b/tests/scripts/depends.py index b8bcfd256..4369246f5 100755 --- a/tests/scripts/depends.py +++ b/tests/scripts/depends.py @@ -23,7 +23,7 @@ Test Mbed TLS with a subset of algorithms. This script can be divided into several steps: First, include/mbedtls/config.h or a different config file passed -in the arguments is parsed to extract any configuration options (collect_config_symbols). +in the arguments is parsed to extract any configuration options (using config.py). Then, test domains (groups of jobs, tests) are built based on predefined data collected in the DomainData class. Here, each domain has five major traits: @@ -60,6 +60,9 @@ import subprocess import sys import traceback +import scripts_path # pylint: disable=unused-import +import config + class Colors: # pylint: disable=too-few-public-methods """Minimalistic support for colored output. Each field of an object of this class is either None if colored output @@ -68,6 +71,7 @@ that outputting start switches the text color to the desired color and stop switches the text color back to the default.""" red = None green = None + cyan = None bold_red = None bold_green = None def __init__(self, options=None): @@ -83,6 +87,7 @@ stop switches the text color back to the default.""" normal = '\033[0m' self.red = ('\033[31m', normal) self.green = ('\033[32m', normal) + self.cyan = ('\033[36m', normal) self.bold_red = ('\033[1;31m', normal) self.bold_green = ('\033[1;32m', normal) NO_COLORS = Colors(None) @@ -118,34 +123,39 @@ Remove the backup file if it was saved earlier.""" else: shutil.copy(options.config_backup, options.config) -def run_config_py(options, args): - """Run scripts/config.py with the specified arguments.""" - cmd = ['scripts/config.py'] - if options.config != 'include/mbedtls/config.h': - cmd += ['--file', options.config] - cmd += args - log_command(cmd) - subprocess.check_call(cmd) +def option_exists(conf, option): + if option not in conf.settings: + return False + return True -def set_reference_config(options): +def set_config_option(conf, option, colors, value=None): + """Set configuration option, optionally specifying a value""" + if not option_exists(conf, option): + log_line('Symbol {} was not found in {}'.format(option, conf.filename), color=colors.red) + return False + log_command(['config.py', 'set', option]) + conf.set(option, value) + return True + +def unset_config_option(conf, option, colors): + """Unset configuration option if it exists""" + if not option_exists(conf, option): + log_line('Symbol {} was not found in {}'.format(option, conf.filename), color=colors.red) + return False + log_command(['config.py', 'unset', option]) + conf.unset(option) + return True + +def set_reference_config(conf, options, colors): """Change the library configuration file (config.h) to the reference state. The reference state is the one from which the tested configurations are derived.""" # Turn off options that are not relevant to the tests and slow them down. - run_config_py(options, ['full']) - run_config_py(options, ['unset', 'MBEDTLS_TEST_HOOKS']) + log_command(['config.py', 'full']) + conf.adapt(config.full_adapter) + unset_config_option(conf, 'MBEDTLS_TEST_HOOKS', colors) if options.unset_use_psa: - run_config_py(options, ['unset', 'MBEDTLS_USE_PSA_CRYPTO']) - -def collect_config_symbols(options): - """Read the list of settings from config.h. -Return them in a generator.""" - with open(options.config, encoding="utf-8") as config_file: - rx = re.compile(r'\s*(?://\s*)?#define\s+(\w+)\s*(?:$|/[/*])') - for line in config_file: - m = re.match(rx, line) - if m: - yield m.group(1) + unset_config_option(conf, 'MBEDTLS_USE_PSA_CRYPTO', colors) class Job: """A job builds the library in a specific configuration and runs some tests.""" @@ -173,19 +183,22 @@ If what is False, announce that the job has failed.''' elif what is False: log_line(self.name + ' FAILED', color=colors.red) else: - log_line('starting ' + self.name) + log_line('starting ' + self.name, color=colors.cyan) - def configure(self, options): + def configure(self, conf, options, colors): '''Set library configuration options as required for the job.''' - set_reference_config(options) + set_reference_config(conf, options, colors) for key, value in sorted(self.config_settings.items()): + ret = False if value is True: - args = ['set', key] + ret = set_config_option(conf, key, colors) elif value is False: - args = ['unset', key] + ret = unset_config_option(conf, key, colors) else: - args = ['set', key, value] - run_config_py(options, args) + ret = set_config_option(conf, key, colors, value) + if ret is False: + return False + return True def test(self, options): '''Run the job's build and test commands. @@ -400,11 +413,11 @@ class DomainData: return [symbol for symbol in self.all_config_symbols if re.match(regexp, symbol)] - def __init__(self, options): + def __init__(self, options, conf): """Gather data about the library and establish a list of domains to test.""" build_command = [options.make_command, 'CFLAGS=-Werror'] build_and_test = [build_command, [options.make_command, 'test']] - self.all_config_symbols = set(collect_config_symbols(options)) + self.all_config_symbols = set(conf.settings.keys()) # Find hash modules by name. hash_symbols = self.config_symbols_matching(r'MBEDTLS_(MD|RIPEMD|SHA)[0-9]+_C\Z') hash_symbols.append("MBEDTLS_SHA512_NO_SHA384") @@ -456,16 +469,19 @@ A name can either be the name of a domain or the name of one specific job.""" else: return [self.jobs[name]] -def run(options, job, colors=NO_COLORS): +def run(options, job, conf, colors=NO_COLORS): """Run the specified job (a Job instance).""" subprocess.check_call([options.make_command, 'clean']) job.announce(colors, None) - job.configure(options) + if not job.configure(conf, options, colors): + job.announce(colors, False) + return False + conf.write() success = job.test(options) job.announce(colors, success) return success -def run_tests(options, domain_data): +def run_tests(options, domain_data, conf): """Run the desired jobs. domain_data should be a DomainData instance that describes the available domains and jobs. @@ -481,7 +497,7 @@ Run the jobs listed in options.tasks.""" backup_config(options) try: for job in jobs: - success = run(options, job, colors=colors) + success = run(options, job, conf, colors=colors) if not success: if options.keep_going: failures.append(job.name) @@ -547,7 +563,9 @@ def main(): default=True) options = parser.parse_args() os.chdir(options.directory) - domain_data = DomainData(options) + conf = config.ConfigFile(options.config) + domain_data = DomainData(options, conf) + if options.tasks is True: options.tasks = sorted(domain_data.domains.keys()) if options.list: @@ -556,7 +574,7 @@ def main(): print(domain_name) sys.exit(0) else: - sys.exit(0 if run_tests(options, domain_data) else 1) + sys.exit(0 if run_tests(options, domain_data, conf) else 1) except Exception: # pylint: disable=broad-except traceback.print_exc() sys.exit(3) From 2e1aeb129d620baa632f2c1a9aaea869d9fd7497 Mon Sep 17 00:00:00 2001 From: Andrzej Kurek Date: Mon, 23 Jan 2023 07:19:22 -0500 Subject: [PATCH 03/51] depends.py: merge set/unset config option into one function Signed-off-by: Andrzej Kurek --- tests/scripts/depends.py | 38 ++++++++++++++++---------------------- 1 file changed, 16 insertions(+), 22 deletions(-) diff --git a/tests/scripts/depends.py b/tests/scripts/depends.py index 4369246f5..1ab6d70b4 100755 --- a/tests/scripts/depends.py +++ b/tests/scripts/depends.py @@ -59,7 +59,7 @@ import shutil import subprocess import sys import traceback - +# Add the Mbed TLS Python library directory to the module search path import scripts_path # pylint: disable=unused-import import config @@ -128,22 +128,22 @@ def option_exists(conf, option): return False return True -def set_config_option(conf, option, colors, value=None): - """Set configuration option, optionally specifying a value""" +def set_config_option_value(conf, option, colors, value): + """Set/unset a configuration option, optionally specifying a value""" if not option_exists(conf, option): log_line('Symbol {} was not found in {}'.format(option, conf.filename), color=colors.red) return False - log_command(['config.py', 'set', option]) - conf.set(option, value) - return True -def unset_config_option(conf, option, colors): - """Unset configuration option if it exists""" - if not option_exists(conf, option): - log_line('Symbol {} was not found in {}'.format(option, conf.filename), color=colors.red) - return False - log_command(['config.py', 'unset', option]) - conf.unset(option) + if value is False: + log_command(['config.py', 'unset', option]) + conf.unset(option) + else: + if value is True: + log_command(['config.py', 'set', option]) + conf.set(option) + else: + log_command(['config.py', 'set', option, value]) + conf.set(option, value) return True def set_reference_config(conf, options, colors): @@ -153,9 +153,9 @@ derived.""" # Turn off options that are not relevant to the tests and slow them down. log_command(['config.py', 'full']) conf.adapt(config.full_adapter) - unset_config_option(conf, 'MBEDTLS_TEST_HOOKS', colors) + set_config_option_value(conf, 'MBEDTLS_TEST_HOOKS', colors, False) if options.unset_use_psa: - unset_config_option(conf, 'MBEDTLS_USE_PSA_CRYPTO', colors) + set_config_option_value(conf, 'MBEDTLS_USE_PSA_CRYPTO', colors, False) class Job: """A job builds the library in a specific configuration and runs some tests.""" @@ -189,13 +189,7 @@ If what is False, announce that the job has failed.''' '''Set library configuration options as required for the job.''' set_reference_config(conf, options, colors) for key, value in sorted(self.config_settings.items()): - ret = False - if value is True: - ret = set_config_option(conf, key, colors) - elif value is False: - ret = unset_config_option(conf, key, colors) - else: - ret = set_config_option(conf, key, colors, value) + ret = set_config_option_value(conf, key, colors, value) if ret is False: return False return True From 2432dc212e14749a8d2b3abf5689765c4e89c725 Mon Sep 17 00:00:00 2001 From: Andrzej Kurek Date: Tue, 24 Jan 2023 07:40:42 -0500 Subject: [PATCH 04/51] depends.py: improve expected argument type Requested config option can be either boolean or a string. Signed-off-by: Andrzej Kurek --- tests/scripts/depends.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/tests/scripts/depends.py b/tests/scripts/depends.py index 1ab6d70b4..9c3c49a9a 100755 --- a/tests/scripts/depends.py +++ b/tests/scripts/depends.py @@ -59,6 +59,8 @@ import shutil import subprocess import sys import traceback +from typing import Union + # Add the Mbed TLS Python library directory to the module search path import scripts_path # pylint: disable=unused-import import config @@ -128,8 +130,10 @@ def option_exists(conf, option): return False return True -def set_config_option_value(conf, option, colors, value): - """Set/unset a configuration option, optionally specifying a value""" +def set_config_option_value(conf, option, colors, value: Union[bool, str]): + """Set/unset a configuration option, optionally specifying a value. +value can be either True/False (set/unset config option), or a string, +which will make a symbol defined with a certain value.""" if not option_exists(conf, option): log_line('Symbol {} was not found in {}'.format(option, conf.filename), color=colors.red) return False From 3ebe7d62609b58011cb3a011978bc677453b7bb5 Mon Sep 17 00:00:00 2001 From: Andrzej Kurek Date: Mon, 6 Feb 2023 10:48:43 +0100 Subject: [PATCH 05/51] Improve tests/scripts/depends.py code As suggested by gilles-peskine-arm. Co-authored-by: Gilles Peskine Signed-off-by: Andrzej Kurek --- tests/scripts/depends.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/tests/scripts/depends.py b/tests/scripts/depends.py index 9c3c49a9a..e604512d1 100755 --- a/tests/scripts/depends.py +++ b/tests/scripts/depends.py @@ -126,9 +126,7 @@ Remove the backup file if it was saved earlier.""" shutil.copy(options.config_backup, options.config) def option_exists(conf, option): - if option not in conf.settings: - return False - return True + return option in conf.settings def set_config_option_value(conf, option, colors, value: Union[bool, str]): """Set/unset a configuration option, optionally specifying a value. From 3e7666b95defe685dbf8fde999926ea52a501144 Mon Sep 17 00:00:00 2001 From: Andrzej Kurek Date: Mon, 6 Feb 2023 10:49:46 +0100 Subject: [PATCH 06/51] Improve tests/scripts/depends.py code As suggested by gilles-peskine-arm. Co-authored-by: Gilles Peskine Signed-off-by: Andrzej Kurek --- tests/scripts/depends.py | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/tests/scripts/depends.py b/tests/scripts/depends.py index e604512d1..182471376 100755 --- a/tests/scripts/depends.py +++ b/tests/scripts/depends.py @@ -139,13 +139,12 @@ which will make a symbol defined with a certain value.""" if value is False: log_command(['config.py', 'unset', option]) conf.unset(option) + elif value is True: + log_command(['config.py', 'set', option]) + conf.set(option) else: - if value is True: - log_command(['config.py', 'set', option]) - conf.set(option) - else: - log_command(['config.py', 'set', option, value]) - conf.set(option, value) + log_command(['config.py', 'set', option, value]) + conf.set(option, value) return True def set_reference_config(conf, options, colors): From b790c935e6d48039ec2d49731739fea1b64fef3d Mon Sep 17 00:00:00 2001 From: Andrzej Kurek Date: Wed, 15 Feb 2023 15:19:37 -0500 Subject: [PATCH 07/51] depends.py: remove symbols that are not present in 2.28 Signed-off-by: Andrzej Kurek --- tests/scripts/depends.py | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/tests/scripts/depends.py b/tests/scripts/depends.py index 182471376..f107dd5cf 100755 --- a/tests/scripts/depends.py +++ b/tests/scripts/depends.py @@ -259,11 +259,7 @@ REVERSE_DEPENDENCIES = { 'MBEDTLS_KEY_EXCHANGE_ECDH_RSA_ENABLED'], 'MBEDTLS_SHA1_C': SSL_PRE_1_2_DEPENDENCIES, 'MBEDTLS_SHA256_C': ['MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED', - 'MBEDTLS_ENTROPY_FORCE_SHA256', - 'MBEDTLS_SHA256_USE_A64_CRYPTO_IF_PRESENT', - 'MBEDTLS_SHA256_USE_A64_CRYPTO_ONLY'], - 'MBEDTLS_SHA512_C': ['MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT', - 'MBEDTLS_SHA512_USE_A64_CRYPTO_ONLY'], + 'MBEDTLS_ENTROPY_FORCE_SHA256'], 'MBEDTLS_X509_RSASSA_PSS_SUPPORT': [] } From b1c9cc3ae423d3e0a5fa82945d07ebd1252e9453 Mon Sep 17 00:00:00 2001 From: Pengyu Lv Date: Mon, 6 Feb 2023 14:29:02 +0800 Subject: [PATCH 08/51] code_style.py: Apply exclusions to the file list This commit rename `--files` options to `--subset` and it means to check a subset of the files known to git. Signed-off-by: Pengyu Lv --- scripts/code_style.py | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/scripts/code_style.py b/scripts/code_style.py index dd8305faf..4a5fb68c1 100755 --- a/scripts/code_style.py +++ b/scripts/code_style.py @@ -174,22 +174,19 @@ def main() -> int: parser.add_argument('-f', '--fix', action='store_true', help=('modify source files to fix the code style ' '(default: print diff, do not modify files)')) - # --files is almost useless: it only matters if there are no files - # ('code_style.py' without arguments checks all files known to Git, - # 'code_style.py --files' does nothing). In particular, - # 'code_style.py --fix --files ...' is intended as a stable ("porcelain") - # way to restyle a possibly empty set of files. - parser.add_argument('--files', action='store_true', - help='only check the specified files (default with non-option arguments)') + parser.add_argument('--subset', action='store_true', + help=('check a subset of the files known to git ' + '(default: empty FILE means full set)')) parser.add_argument('operands', nargs='*', metavar='FILE', - help='files to check (if none: check files that are known to git)') + help='files to check') args = parser.parse_args() - if args.files or args.operands: - src_files = args.operands - else: - src_files = get_src_files() + all_src_files = get_src_files() + src_files = args.operands if args.operands else all_src_files + if args.subset: + # We are to check a subset of the default list + src_files = [f for f in args.operands if f in all_src_files] if args.fix: # Fix mode From a4b9b7700a7e4b93ae35e9d2bd44801444cdd4eb Mon Sep 17 00:00:00 2001 From: Pengyu Lv Date: Mon, 6 Feb 2023 14:27:30 +0800 Subject: [PATCH 09/51] code_style.py: Add helpers to print warning and skipped files Signed-off-by: Pengyu Lv --- scripts/code_style.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/scripts/code_style.py b/scripts/code_style.py index 4a5fb68c1..61b1ab0e6 100755 --- a/scripts/code_style.py +++ b/scripts/code_style.py @@ -33,6 +33,17 @@ CHECK_GENERATED_FILES = "tests/scripts/check-generated-files.sh" def print_err(*args): print("Error: ", *args, file=sys.stderr) +def print_warn(*args): + print("Warn:", *args, file=sys.stderr) + +# Print the file names that will be skipped and the help message +def print_skip(files_to_skip): + print() + print(*files_to_skip, sep=", SKIP\n", end=", SKIP\n") + print_warn("The listed files will be skipped because\n" + "they are not included in the default list.") + print() + # Match FILENAME(s) in "check SCRIPT (FILENAME...)" CHECK_CALL_RE = re.compile(r"\n\s*check\s+[^\s#$&*?;|]+([^\n#$&*?;|]+)", re.ASCII) @@ -187,6 +198,9 @@ def main() -> int: if args.subset: # We are to check a subset of the default list src_files = [f for f in args.operands if f in all_src_files] + skip_src_files = [f for f in args.operands if f not in src_files] + if skip_src_files: + print_skip(skip_src_files) if args.fix: # Fix mode From 75e11d3703e85ba98f5abff2e795eaf5d1122529 Mon Sep 17 00:00:00 2001 From: Pengyu Lv Date: Fri, 10 Feb 2023 10:55:29 +0800 Subject: [PATCH 10/51] print skipped file names to stdout Signed-off-by: Pengyu Lv --- scripts/code_style.py | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/scripts/code_style.py b/scripts/code_style.py index 61b1ab0e6..85008bec1 100755 --- a/scripts/code_style.py +++ b/scripts/code_style.py @@ -33,15 +33,12 @@ CHECK_GENERATED_FILES = "tests/scripts/check-generated-files.sh" def print_err(*args): print("Error: ", *args, file=sys.stderr) -def print_warn(*args): - print("Warn:", *args, file=sys.stderr) - # Print the file names that will be skipped and the help message def print_skip(files_to_skip): print() print(*files_to_skip, sep=", SKIP\n", end=", SKIP\n") - print_warn("The listed files will be skipped because\n" - "they are not included in the default list.") + print("Warn: The listed files will be skipped because\n" + "they are not included in the default list.") print() # Match FILENAME(s) in "check SCRIPT (FILENAME...)" From 44b75a605b94add7aacb1cd5b56228b5a667d860 Mon Sep 17 00:00:00 2001 From: Pengyu Lv Date: Fri, 10 Feb 2023 11:06:36 +0800 Subject: [PATCH 11/51] adjust help message Signed-off-by: Pengyu Lv --- scripts/code_style.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/scripts/code_style.py b/scripts/code_style.py index 85008bec1..65c9cccfb 100755 --- a/scripts/code_style.py +++ b/scripts/code_style.py @@ -184,9 +184,10 @@ def main() -> int: '(default: print diff, do not modify files)')) parser.add_argument('--subset', action='store_true', help=('check a subset of the files known to git ' - '(default: empty FILE means full set)')) + '(default: check all files passed as arguments, ' + 'known to git or not)')) parser.add_argument('operands', nargs='*', metavar='FILE', - help='files to check') + help='files to check (if none: check files that are known to git)') args = parser.parse_args() From bae83d25ebb8550d10a7e3ea4b65789730e32616 Mon Sep 17 00:00:00 2001 From: Pengyu Lv Date: Tue, 14 Feb 2023 10:29:53 +0800 Subject: [PATCH 12/51] Improve readability Signed-off-by: Pengyu Lv --- scripts/code_style.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/scripts/code_style.py b/scripts/code_style.py index 65c9cccfb..eaf1f6b88 100755 --- a/scripts/code_style.py +++ b/scripts/code_style.py @@ -191,12 +191,12 @@ def main() -> int: args = parser.parse_args() - all_src_files = get_src_files() - src_files = args.operands if args.operands else all_src_files + covered = frozenset(get_src_files()) + src_files = args.operands if args.operands else covered if args.subset: # We are to check a subset of the default list - src_files = [f for f in args.operands if f in all_src_files] - skip_src_files = [f for f in args.operands if f not in src_files] + src_files = [f for f in args.operands if f in covered] + skip_src_files = [f for f in args.operands if f not in covered] if skip_src_files: print_skip(skip_src_files) From 4a37eef78f985cc5842a2c9619443a2ed40a2b62 Mon Sep 17 00:00:00 2001 From: Pengyu Lv Date: Wed, 15 Feb 2023 10:20:40 +0800 Subject: [PATCH 13/51] Only check files known to git Signed-off-by: Pengyu Lv --- scripts/code_style.py | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/scripts/code_style.py b/scripts/code_style.py index eaf1f6b88..e40a20cfc 100755 --- a/scripts/code_style.py +++ b/scripts/code_style.py @@ -37,8 +37,8 @@ def print_err(*args): def print_skip(files_to_skip): print() print(*files_to_skip, sep=", SKIP\n", end=", SKIP\n") - print("Warn: The listed files will be skipped because\n" - "they are not included in the default list.") + print("Warning: The listed files will be skipped because\n" + "they are not known to git.") print() # Match FILENAME(s) in "check SCRIPT (FILENAME...)" @@ -182,23 +182,27 @@ def main() -> int: parser.add_argument('-f', '--fix', action='store_true', help=('modify source files to fix the code style ' '(default: print diff, do not modify files)')) + # --subset is almost useless: it only matters if there are no files + # ('code_style.py' without arguments checks all files known to Git, + # 'code_style.py --subset' does nothing). In particular, + # 'code_style.py --fix --subset ...' is intended as a stable ("porcelain") + # way to restyle a possibly empty set of files. parser.add_argument('--subset', action='store_true', - help=('check a subset of the files known to git ' - '(default: check all files passed as arguments, ' - 'known to git or not)')) + help='only check the specified files (default with non-option arguments)') parser.add_argument('operands', nargs='*', metavar='FILE', - help='files to check (if none: check files that are known to git)') + help='files to check (files MUST be known to git, if none: check all)') args = parser.parse_args() covered = frozenset(get_src_files()) - src_files = args.operands if args.operands else covered - if args.subset: - # We are to check a subset of the default list + # We only check files that are known to git + if args.subset or args.operands: src_files = [f for f in args.operands if f in covered] skip_src_files = [f for f in args.operands if f not in covered] if skip_src_files: print_skip(skip_src_files) + else: + src_files = covered if args.fix: # Fix mode From e95df0bd700eef07aa0a4fec903633f80f4c8567 Mon Sep 17 00:00:00 2001 From: Pengyu Lv Date: Wed, 15 Feb 2023 16:58:09 +0800 Subject: [PATCH 14/51] Fix CI failure Signed-off-by: Pengyu Lv --- scripts/code_style.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/code_style.py b/scripts/code_style.py index e40a20cfc..c31fb2949 100755 --- a/scripts/code_style.py +++ b/scripts/code_style.py @@ -202,7 +202,7 @@ def main() -> int: if skip_src_files: print_skip(skip_src_files) else: - src_files = covered + src_files = list(covered) if args.fix: # Fix mode From cdaee54773cbba892afce2b64bbcd7acd13784ac Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Tue, 14 Feb 2023 14:34:15 +0000 Subject: [PATCH 15/51] Fix incorrect printing of OIDs The first 2 components of an OID are combined together into the same subidentifier via the formula: subidentifier = (component1 * 40) + component2 The current code extracts component1 and component2 using division and modulo as one would expect. However, there is a subtlety in the specification[1]: >This packing of the first two object identifier components recognizes >that only three values are allocated from the root node, and at most >39 subsequent values from nodes reached by X = 0 and X = 1. If the root node (component1) is 2, the subsequent node (component2) may be greater than 38. For example, the following are real OIDs: * 2.40.0.25, UPU standard S25 * 2.49.0.0.826.0, Met Office * 2.999, Allocated example OID This has 2 implications that the current parsing code does not take account of: 1. The second component may be > 39, so (subidentifier % 40) is not correct in all circumstances. 2. The first subidentifier (containing the first 2 components) may be more than one byte long. Currently we assume it is just 1 byte. Improve parsing code to deal with these cases correctly. [1] Rec. ITU-T X.690 (02/2021), 8.19.4 Signed-off-by: David Horstmann --- library/oid.c | 35 ++++++++++++++++++++++++++++++----- 1 file changed, 30 insertions(+), 5 deletions(-) diff --git a/library/oid.c b/library/oid.c index fcff15273..d8ba773a5 100644 --- a/library/oid.c +++ b/library/oid.c @@ -796,14 +796,39 @@ int mbedtls_oid_get_numeric_string(char *buf, size_t size, p = buf; n = size; - /* First byte contains first two dots */ - if (oid->len > 0) { - ret = mbedtls_snprintf(p, n, "%d.%d", oid->p[0] / 40, oid->p[0] % 40); - OID_SAFE_SNPRINTF; + /* First subidentifier contains first two OID components */ + i = 0; + value = 0; + while (i < oid->len && ((oid->p[i] & 0x80) != 0)) { + /* Prevent overflow in value. */ + if (((value << 7) >> 7) != value) { + return MBEDTLS_ERR_OID_BUF_TOO_SMALL; + } + + value += oid->p[i] & 0x7F; + value <<= 7; + i++; } + if (i >= oid->len) { + return MBEDTLS_ERR_OID_BUF_TOO_SMALL; + } + /* Last byte of first subidentifier */ + value += oid->p[i] & 0x7F; + i++; + + unsigned int component1 = value / 40; + if (component1 > 2) { + /* The first component can only be 0, 1 or 2. + * If oid->p[0] / 40 is greater than 2, the leftover belongs to + * the second component. */ + component1 = 2; + } + unsigned int component2 = value - (40 * component1); + ret = mbedtls_snprintf(p, n, "%u.%u", component1, component2); + OID_SAFE_SNPRINTF; value = 0; - for (i = 1; i < oid->len; i++) { + for (; i < oid->len; i++) { /* Prevent overflow in value. */ if (((value << 7) >> 7) != value) { return MBEDTLS_ERR_OID_BUF_TOO_SMALL; From c714416d1648656c7ccdabe0b598f0e6264a9e66 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Tue, 14 Feb 2023 17:29:16 +0000 Subject: [PATCH 16/51] Add tests for mbedtls_oid_get_numeric_string() Signed-off-by: David Horstmann --- tests/suites/test_suite_oid.data | 24 ++++++++++++++++++++++++ tests/suites/test_suite_oid.function | 21 +++++++++++++++++++++ 2 files changed, 45 insertions(+) diff --git a/tests/suites/test_suite_oid.data b/tests/suites/test_suite_oid.data index 326193520..83a39bb1e 100644 --- a/tests/suites/test_suite_oid.data +++ b/tests/suites/test_suite_oid.data @@ -89,3 +89,27 @@ oid_get_md_alg_id:"2b24030201":MBEDTLS_MD_RIPEMD160 OID hash id - invalid oid oid_get_md_alg_id:"2B864886f70d0204":-1 +OID get numeric string - hardware module name +oid_get_numeric_string:"2B06010505070804":0:"1.3.6.1.5.5.7.8.4" + +OID get numeric string - multi-byte subidentifier +oid_get_numeric_string:"29903C":0:"1.1.2108" + +OID get numeric string - second component greater than 39 +oid_get_numeric_string:"81010000863A00":0:"2.49.0.0.826.0" + +OID get numeric string - multi-byte first subidentifier +oid_get_numeric_string:"8837":0:"2.999" + +OID get numeric string - empty oid buffer +oid_get_numeric_string:"":MBEDTLS_ERR_OID_BUF_TOO_SMALL:"" + +OID get numeric string - no final / all bytes have top bit set +oid_get_numeric_string:"818181":MBEDTLS_ERR_OID_BUF_TOO_SMALL:"" + +# Encodes the number 0x0400000000 as a subidentifier which overflows 32-bits +OID get numeric string - 32-bit overflow +oid_get_numeric_string:"C080808000":MBEDTLS_ERR_OID_BUF_TOO_SMALL:"" + +OID get numeric string - 32-bit overflow, second subidentifier +oid_get_numeric_string:"2BC080808000":MBEDTLS_ERR_OID_BUF_TOO_SMALL:"" diff --git a/tests/suites/test_suite_oid.function b/tests/suites/test_suite_oid.function index fac5ed4d0..7759baf36 100644 --- a/tests/suites/test_suite_oid.function +++ b/tests/suites/test_suite_oid.function @@ -95,3 +95,24 @@ void oid_get_md_alg_id(data_t *oid, int exp_md_id) } } /* END_CASE */ + +/* BEGIN_CASE */ +void oid_get_numeric_string(data_t *oid, int error_ret, char *result_str) +{ + char buf[256]; + mbedtls_asn1_buf input_oid = { 0, 0, NULL }; + int ret; + + input_oid.tag = MBEDTLS_ASN1_OID; + input_oid.p = oid->x; + input_oid.len = oid->len; + + ret = mbedtls_oid_get_numeric_string(buf, sizeof(buf), &input_oid); + + if (error_ret == 0) { + TEST_ASSERT(strcmp(buf, result_str) == 0); + } else { + TEST_EQUAL(ret, error_ret); + } +} +/* END_CASE */ From beb90e30de05a11c6946e4fe53156c78a0252dba Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Wed, 15 Feb 2023 11:48:13 +0000 Subject: [PATCH 17/51] Disallow overlong encoding when parsing OIDs OID subidentifiers are encoded as follow. For every byte: * The top bit is 1 if there is another byte to come, 0 if this is the last byte. * The other 7 bits form 7 bits of the number. These groups of 7 are concatenated together in big-endian order. Overlong encodings are explicitly disallowed by the BER/DER/X690 specification. For example, the number 1 cannot be encoded as: 0x80 0x80 0x01 It must be encoded as: 0x01 Enforce this in Mbed TLS' OID DER-to-string parser. Signed-off-by: David Horstmann --- library/oid.c | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/library/oid.c b/library/oid.c index d8ba773a5..fb4caaddf 100644 --- a/library/oid.c +++ b/library/oid.c @@ -799,6 +799,11 @@ int mbedtls_oid_get_numeric_string(char *buf, size_t size, /* First subidentifier contains first two OID components */ i = 0; value = 0; + if ((oid->p[0]) == 0x80) { + /* Overlong encoding is not allowed */ + return MBEDTLS_ERR_OID_BUF_TOO_SMALL; + } + while (i < oid->len && ((oid->p[i] & 0x80) != 0)) { /* Prevent overflow in value. */ if (((value << 7) >> 7) != value) { @@ -833,6 +838,10 @@ int mbedtls_oid_get_numeric_string(char *buf, size_t size, if (((value << 7) >> 7) != value) { return MBEDTLS_ERR_OID_BUF_TOO_SMALL; } + if ((value == 0) && ((oid->p[i]) == 0x80)) { + /* Overlong encoding is not allowed */ + return MBEDTLS_ERR_OID_BUF_TOO_SMALL; + } value <<= 7; value += oid->p[i] & 0x7F; From 071dd3579cc7d639ec9356bcc014f3cc08556d19 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Wed, 15 Feb 2023 11:58:40 +0000 Subject: [PATCH 18/51] Add testcases for overlong encoding of OIDs Signed-off-by: David Horstmann --- tests/suites/test_suite_oid.data | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/tests/suites/test_suite_oid.data b/tests/suites/test_suite_oid.data index 83a39bb1e..f721b820c 100644 --- a/tests/suites/test_suite_oid.data +++ b/tests/suites/test_suite_oid.data @@ -113,3 +113,9 @@ oid_get_numeric_string:"C080808000":MBEDTLS_ERR_OID_BUF_TOO_SMALL:"" OID get numeric string - 32-bit overflow, second subidentifier oid_get_numeric_string:"2BC080808000":MBEDTLS_ERR_OID_BUF_TOO_SMALL:"" + +OID get numeric string - overlong encoding +oid_get_numeric_string:"8001":MBEDTLS_ERR_OID_BUF_TOO_SMALL:"" + +OID get numeric string - overlong encoding, second subidentifier +oid_get_numeric_string:"2B8001":MBEDTLS_ERR_OID_BUF_TOO_SMALL:"" From b91ba4b7bf8d8ebeeae9fbebf159b6e1e5c19a09 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Wed, 15 Feb 2023 13:07:49 +0000 Subject: [PATCH 19/51] Add ChangeLog for OID-to-string fixes Signed-off-by: David Horstmann --- ChangeLog.d/fix-oid-to-string-bugs.txt | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 ChangeLog.d/fix-oid-to-string-bugs.txt diff --git a/ChangeLog.d/fix-oid-to-string-bugs.txt b/ChangeLog.d/fix-oid-to-string-bugs.txt new file mode 100644 index 000000000..799f44474 --- /dev/null +++ b/ChangeLog.d/fix-oid-to-string-bugs.txt @@ -0,0 +1,6 @@ +Bugfix + * Fix bug in conversion from OID to string in + mbedtls_oid_get_numeric_string(). OIDs such as 2.40.0.25 are now printed + correctly. + * Reject OIDs with overlong-encoded subidentifiers when converting + OID-to-string. From 8f81d8a3053ad0ef874cc015df13fca6ae1e583e Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Wed, 15 Feb 2023 13:46:53 +0000 Subject: [PATCH 20/51] Make overflow checks more readable Signed-off-by: David Horstmann --- library/oid.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/library/oid.c b/library/oid.c index fb4caaddf..e36caf2a4 100644 --- a/library/oid.c +++ b/library/oid.c @@ -806,7 +806,7 @@ int mbedtls_oid_get_numeric_string(char *buf, size_t size, while (i < oid->len && ((oid->p[i] & 0x80) != 0)) { /* Prevent overflow in value. */ - if (((value << 7) >> 7) != value) { + if (value > (UINT_MAX >> 7)) { return MBEDTLS_ERR_OID_BUF_TOO_SMALL; } @@ -835,7 +835,7 @@ int mbedtls_oid_get_numeric_string(char *buf, size_t size, value = 0; for (; i < oid->len; i++) { /* Prevent overflow in value. */ - if (((value << 7) >> 7) != value) { + if (value > (UINT_MAX >> 7)) { return MBEDTLS_ERR_OID_BUF_TOO_SMALL; } if ((value == 0) && ((oid->p[i]) == 0x80)) { From d138181190153d3239f35cfdd418029f3a742b41 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Wed, 15 Feb 2023 15:44:24 +0000 Subject: [PATCH 21/51] Change += to |= for clearer semantics Signed-off-by: David Horstmann --- library/oid.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/library/oid.c b/library/oid.c index e36caf2a4..e720ceaaf 100644 --- a/library/oid.c +++ b/library/oid.c @@ -810,7 +810,7 @@ int mbedtls_oid_get_numeric_string(char *buf, size_t size, return MBEDTLS_ERR_OID_BUF_TOO_SMALL; } - value += oid->p[i] & 0x7F; + value |= oid->p[i] & 0x7F; value <<= 7; i++; } @@ -818,7 +818,7 @@ int mbedtls_oid_get_numeric_string(char *buf, size_t size, return MBEDTLS_ERR_OID_BUF_TOO_SMALL; } /* Last byte of first subidentifier */ - value += oid->p[i] & 0x7F; + value |= oid->p[i] & 0x7F; i++; unsigned int component1 = value / 40; @@ -844,7 +844,7 @@ int mbedtls_oid_get_numeric_string(char *buf, size_t size, } value <<= 7; - value += oid->p[i] & 0x7F; + value |= oid->p[i] & 0x7F; if (!(oid->p[i] & 0x80)) { /* Last byte */ From 0518d53ba75c7dfb89d120cb2266a05297037c36 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Mon, 20 Feb 2023 14:21:23 +0000 Subject: [PATCH 22/51] Change error codes to more appropriate codes The more precise error codes are borrowed from the ASN1 module. Signed-off-by: David Horstmann --- library/oid.c | 10 +++++----- tests/suites/test_suite_oid.data | 12 ++++++------ 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/library/oid.c b/library/oid.c index e720ceaaf..4ec752fb9 100644 --- a/library/oid.c +++ b/library/oid.c @@ -801,13 +801,13 @@ int mbedtls_oid_get_numeric_string(char *buf, size_t size, value = 0; if ((oid->p[0]) == 0x80) { /* Overlong encoding is not allowed */ - return MBEDTLS_ERR_OID_BUF_TOO_SMALL; + return MBEDTLS_ERR_ASN1_INVALID_DATA; } while (i < oid->len && ((oid->p[i] & 0x80) != 0)) { /* Prevent overflow in value. */ if (value > (UINT_MAX >> 7)) { - return MBEDTLS_ERR_OID_BUF_TOO_SMALL; + return MBEDTLS_ERR_ASN1_INVALID_DATA; } value |= oid->p[i] & 0x7F; @@ -815,7 +815,7 @@ int mbedtls_oid_get_numeric_string(char *buf, size_t size, i++; } if (i >= oid->len) { - return MBEDTLS_ERR_OID_BUF_TOO_SMALL; + return MBEDTLS_ERR_ASN1_OUT_OF_DATA; } /* Last byte of first subidentifier */ value |= oid->p[i] & 0x7F; @@ -836,11 +836,11 @@ int mbedtls_oid_get_numeric_string(char *buf, size_t size, for (; i < oid->len; i++) { /* Prevent overflow in value. */ if (value > (UINT_MAX >> 7)) { - return MBEDTLS_ERR_OID_BUF_TOO_SMALL; + return MBEDTLS_ERR_ASN1_INVALID_DATA; } if ((value == 0) && ((oid->p[i]) == 0x80)) { /* Overlong encoding is not allowed */ - return MBEDTLS_ERR_OID_BUF_TOO_SMALL; + return MBEDTLS_ERR_ASN1_INVALID_DATA; } value <<= 7; diff --git a/tests/suites/test_suite_oid.data b/tests/suites/test_suite_oid.data index f721b820c..38d8b7e1c 100644 --- a/tests/suites/test_suite_oid.data +++ b/tests/suites/test_suite_oid.data @@ -102,20 +102,20 @@ OID get numeric string - multi-byte first subidentifier oid_get_numeric_string:"8837":0:"2.999" OID get numeric string - empty oid buffer -oid_get_numeric_string:"":MBEDTLS_ERR_OID_BUF_TOO_SMALL:"" +oid_get_numeric_string:"":MBEDTLS_ERR_ASN1_OUT_OF_DATA:"" OID get numeric string - no final / all bytes have top bit set -oid_get_numeric_string:"818181":MBEDTLS_ERR_OID_BUF_TOO_SMALL:"" +oid_get_numeric_string:"818181":MBEDTLS_ERR_ASN1_OUT_OF_DATA:"" # Encodes the number 0x0400000000 as a subidentifier which overflows 32-bits OID get numeric string - 32-bit overflow -oid_get_numeric_string:"C080808000":MBEDTLS_ERR_OID_BUF_TOO_SMALL:"" +oid_get_numeric_string:"C080808000":MBEDTLS_ERR_ASN1_INVALID_DATA:"" OID get numeric string - 32-bit overflow, second subidentifier -oid_get_numeric_string:"2BC080808000":MBEDTLS_ERR_OID_BUF_TOO_SMALL:"" +oid_get_numeric_string:"2BC080808000":MBEDTLS_ERR_ASN1_INVALID_DATA:"" OID get numeric string - overlong encoding -oid_get_numeric_string:"8001":MBEDTLS_ERR_OID_BUF_TOO_SMALL:"" +oid_get_numeric_string:"8001":MBEDTLS_ERR_ASN1_INVALID_DATA:"" OID get numeric string - overlong encoding, second subidentifier -oid_get_numeric_string:"2B8001":MBEDTLS_ERR_OID_BUF_TOO_SMALL:"" +oid_get_numeric_string:"2B8001":MBEDTLS_ERR_ASN1_INVALID_DATA:"" From e8ef6adde0cb3257a4377910778b07c74b37250a Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Mon, 20 Feb 2023 14:57:47 +0000 Subject: [PATCH 23/51] Correct error code in test_suite_x509parse.data Signed-off-by: David Horstmann --- tests/suites/test_suite_x509parse.data | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/suites/test_suite_x509parse.data b/tests/suites/test_suite_x509parse.data index 071bdd41d..685106bab 100644 --- a/tests/suites/test_suite_x509parse.data +++ b/tests/suites/test_suite_x509parse.data @@ -2578,7 +2578,7 @@ X509 OID numstring #4 (larger number) x509_oid_numstr:"2a864886f70d":"1.2.840.113549":15:14 X509 OID numstring #5 (arithmetic overflow) -x509_oid_numstr:"2a8648f9f8f7f6f5f4f3f2f1f001":"":100:MBEDTLS_ERR_OID_BUF_TOO_SMALL +x509_oid_numstr:"2a8648f9f8f7f6f5f4f3f2f1f001":"":100:MBEDTLS_ERR_ASN1_INVALID_DATA X509 CRT keyUsage #1 (no extension, expected KU) depends_on:MBEDTLS_RSA_C:MBEDTLS_SHA1_C From 02a76a507b2d1e3f0b331e5d1b91a58182f210c5 Mon Sep 17 00:00:00 2001 From: Pengyu Lv Date: Mon, 20 Feb 2023 18:05:21 +0800 Subject: [PATCH 24/51] compat.sh: skip static ECDH cases if unsupported in openssl This commit add support to detect if openssl used for testing supports static ECDH key exchange. Skip the ciphersutes if openssl doesn't support them. Signed-off-by: Pengyu Lv --- tests/compat.sh | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/tests/compat.sh b/tests/compat.sh index f96c4e4c6..6d09b4fc9 100755 --- a/tests/compat.sh +++ b/tests/compat.sh @@ -861,6 +861,16 @@ add_mbedtls_ciphersuites() esac } +# o_check_ciphersuite CIPHER_SUITE_NAME +o_check_ciphersuite() +{ + if [ "${O_SUPPORT_ECDH}" = "NO" ]; then + case "$1" in + *ECDH-*) SKIP_NEXT="YES" + esac + fi +} + setup_arguments() { O_MODE="" @@ -947,6 +957,11 @@ setup_arguments() ;; esac + case $($OPENSSL ciphers ALL) in + *ECDH-ECDSA*|*ECDH-RSA*) O_SUPPORT_ECDH="YES";; + *) O_SUPPORT_ECDH="NO";; + esac + if [ "X$VERIFY" = "XYES" ]; then M_SERVER_ARGS="$M_SERVER_ARGS ca_file=data_files/test-ca_cat12.crt auth_mode=required" @@ -1373,6 +1388,7 @@ for MODE in $MODES; do if [ "X" != "X$M_CIPHERS" ]; then start_server "OpenSSL" for i in $M_CIPHERS; do + o_check_ciphersuite "$i" run_client mbedTLS $i done stop_server @@ -1381,6 +1397,7 @@ for MODE in $MODES; do if [ "X" != "X$O_CIPHERS" ]; then start_server "mbedTLS" for i in $O_CIPHERS; do + o_check_ciphersuite "$i" run_client OpenSSL $i done stop_server From 95167893f694e94f797a8a7bbf78b3c68256eca3 Mon Sep 17 00:00:00 2001 From: Pengyu Lv Date: Thu, 23 Feb 2023 16:40:26 +0800 Subject: [PATCH 25/51] Remove explicit ECDH exclusion for Travis CI Signed-off-by: Pengyu Lv --- .travis.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.travis.yml b/.travis.yml index cdf74c717..eb01a44ab 100644 --- a/.travis.yml +++ b/.travis.yml @@ -55,8 +55,8 @@ jobs: # Exclude a few test cases that are failing mysteriously. # https://github.com/Mbed-TLS/mbedtls/issues/6660 - tests/ssl-opt.sh -e 'Fallback SCSV:\ .*list' - # Modern OpenSSL does not support fixed ECDH, null or ancient ciphers. - - tests/compat.sh -p OpenSSL -e 'NULL\|ECDH-\|DES\|RC4' + # Modern OpenSSL does not support null or ancient ciphers. + - tests/compat.sh -p OpenSSL -e 'NULL\|DES\|RC4' - tests/scripts/travis-log-failure.sh # GnuTLS supports CAMELLIA but compat.sh doesn't properly enable it. # Modern GnuTLS does not support DES. From fef3ad0a14d8bb0fc1471b9f7fde23434f1a0684 Mon Sep 17 00:00:00 2001 From: Pengyu Lv Date: Thu, 23 Feb 2023 16:41:35 +0800 Subject: [PATCH 26/51] Update incorrect comment Signed-off-by: Pengyu Lv --- tests/compat.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/compat.sh b/tests/compat.sh index 6d09b4fc9..e520c3186 100755 --- a/tests/compat.sh +++ b/tests/compat.sh @@ -1175,7 +1175,7 @@ run_client() { if [ $EXIT -eq 0 ]; then RESULT=0 else - # If the cipher isn't supported... + # If ti is NULL cipher ... if grep 'Cipher is (NONE)' $CLI_OUT >/dev/null; then RESULT=1 else From ab1fb39d7a108aecbbf9294f84d54bb6abd23af8 Mon Sep 17 00:00:00 2001 From: Pengyu Lv Date: Thu, 23 Feb 2023 18:27:33 +0800 Subject: [PATCH 27/51] Fix typo Signed-off-by: Pengyu Lv --- tests/compat.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/compat.sh b/tests/compat.sh index e520c3186..e7f9d4981 100755 --- a/tests/compat.sh +++ b/tests/compat.sh @@ -1175,7 +1175,7 @@ run_client() { if [ $EXIT -eq 0 ]; then RESULT=0 else - # If ti is NULL cipher ... + # If it is NULL cipher ... if grep 'Cipher is (NONE)' $CLI_OUT >/dev/null; then RESULT=1 else From 2fb14e93f3996f6eb9ccfc94988c1794f53641b3 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 14 Feb 2023 19:15:40 +0100 Subject: [PATCH 28/51] Define a workaround for empty \retval description Since Clang 15, `clang -Wdocumentation` warns about an empty description in a Doxygen `\retval` command: ``` include/psa/crypto.h:91:23: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation] * \retval #PSA_SUCCESS ~~~~~~~~~~~~~~~~~~~^ ``` Ideally `\retval` directives should have a description that describes the precise meaning of the return value, but we commonly use an empty description when the return value is a status code and the status code's description is sufficient documentation. As a workaround, define a Doxygen command `\emptydescription` that we can use to make the description source code non-empty, without changing the appearance. Using the command will be done in a subsequent commit. Signed-off-by: Gilles Peskine --- doxygen/mbedtls.doxyfile | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile index 7c4f31c85..1ad5866a4 100644 --- a/doxygen/mbedtls.doxyfile +++ b/doxygen/mbedtls.doxyfile @@ -25,3 +25,15 @@ HAVE_DOT = YES DOT_GRAPH_MAX_NODES = 200 MAX_DOT_GRAPH_DEPTH = 1000 DOT_TRANSPARENT = YES + +# Doxygen accepts empty descriptions for commands such as \retval, +# but clang -Wdocumentation doesn't (since Clang 15, for \retval). +# https://github.com/Mbed-TLS/mbedtls/issues/6960 +# https://github.com/llvm/llvm-project/issues/60315 +# As a workaround, when documenting the status codes that a function can +# return, if you don't have anything to say beyond the status code's +# description, you can write something like +# \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription +# This does not change the documentation generated by Doxygen, but +# it pacifies clang -Wdocumentation. +ALIASES += emptydescription="" From ec1eff386ce36a0efd4d00322f46bda203f02371 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 14 Feb 2023 19:21:09 +0100 Subject: [PATCH 29/51] Make \retval commands non-empty Pacify Clang >=15 which complained: ``` include/psa/crypto.h:91:23: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation] * \retval #PSA_SUCCESS ~~~~~~~~~~~~~~~~~~~^ ``` This commit performs the following systematic replacement: ``` perl -i -0777 -p -e 's/([\\@])(retval +\S+)\n(?! *\*? *([^\n \\*\/]|\\[cp]\b))/$1$2 ${1}emptydescription\n/g' $(git ls-files '*.[hc]' '*.function' '*.jinja') ``` i.e. add an `\emptydescription` argument to `\retval` commands (or `@retval`, which we don't normally used) that are followed by a single word, unless the next line looks like it contains text which would be the description. Signed-off-by: Gilles Peskine --- include/psa/crypto.h | 776 +++++++++++++-------------- include/psa/crypto_compat.h | 14 +- include/psa/crypto_extra.h | 24 +- include/psa/crypto_se_driver.h | 46 +- library/psa_crypto.c | 12 +- library/psa_crypto_aead.h | 8 +- library/psa_crypto_cipher.h | 46 +- library/psa_crypto_core.h | 70 +-- library/psa_crypto_ecp.h | 36 +- library/psa_crypto_hash.h | 26 +- library/psa_crypto_mac.h | 28 +- library/psa_crypto_rsa.h | 36 +- library/psa_crypto_slot_management.h | 18 +- library/psa_crypto_storage.c | 28 +- library/psa_crypto_storage.h | 52 +- 15 files changed, 610 insertions(+), 610 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index a6875ac3f..3c1c109a9 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -88,16 +88,16 @@ extern "C" { * initialization may have security implications, for example due to improper * seeding of the random number generator. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_INSUFFICIENT_STORAGE - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_DATA_INVALID - * \retval #PSA_ERROR_DATA_CORRUPT + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_DATA_INVALID \emptydescription + * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription */ psa_status_t psa_crypto_init(void); @@ -374,14 +374,14 @@ static size_t psa_get_key_bits(const psa_key_attributes_t *attributes); * On failure, equivalent to a * freshly-initialized structure. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_INVALID_HANDLE - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_DATA_CORRUPT - * \retval #PSA_ERROR_DATA_INVALID + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription + * \retval #PSA_ERROR_DATA_INVALID \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -492,7 +492,7 @@ psa_status_t psa_purge_key(mbedtls_svc_key_id_t key); * identifier defined in \p attributes. * \c 0 on failure. * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription * \retval #PSA_ERROR_INVALID_HANDLE * \p source_key is invalid. * \retval #PSA_ERROR_ALREADY_EXISTS @@ -508,14 +508,14 @@ psa_status_t psa_purge_key(mbedtls_svc_key_id_t key); * The source key does not have the #PSA_KEY_USAGE_COPY usage flag, or * the source key is not exportable and its lifetime does not * allow copying it to the target's lifetime. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_INSUFFICIENT_STORAGE - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_DATA_INVALID - * \retval #PSA_ERROR_DATA_CORRUPT - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_DATA_INVALID \emptydescription + * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -637,14 +637,14 @@ psa_status_t psa_destroy_key(mbedtls_svc_key_id_t key); * the key data is not correctly formatted, or * the size in \p attributes is nonzero and does not match the size * of the key data. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_INSUFFICIENT_STORAGE - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_DATA_CORRUPT - * \retval #PSA_ERROR_DATA_INVALID - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription + * \retval #PSA_ERROR_DATA_INVALID \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -724,22 +724,22 @@ psa_status_t psa_import_key(const psa_key_attributes_t *attributes, * \param[out] data_length On success, the number of bytes * that make up the key data. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_INVALID_HANDLE + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription * \retval #PSA_ERROR_NOT_PERMITTED * The key does not have the #PSA_KEY_USAGE_EXPORT flag. - * \retval #PSA_ERROR_NOT_SUPPORTED + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p data buffer is too small. You can determine a * sufficient buffer size by calling * #PSA_EXPORT_KEY_OUTPUT_SIZE(\c type, \c bits) * where \c type is the key type * and \c bits is the key size in bits. - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -799,22 +799,22 @@ psa_status_t psa_export_key(mbedtls_svc_key_id_t key, * \param[out] data_length On success, the number of bytes * that make up the key data. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_INVALID_HANDLE + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription * \retval #PSA_ERROR_INVALID_ARGUMENT * The key is neither a public key nor a key pair. - * \retval #PSA_ERROR_NOT_SUPPORTED + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p data buffer is too small. You can determine a * sufficient buffer size by calling * #PSA_EXPORT_KEY_OUTPUT_SIZE(#PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(\c type), \c bits) * where \c type is the key type * and \c bits is the key size in bits. - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -852,13 +852,13 @@ psa_status_t psa_export_public_key(mbedtls_svc_key_id_t key, * Success. * \retval #PSA_ERROR_NOT_SUPPORTED * \p alg is not supported or is not a hash algorithm. - * \retval #PSA_ERROR_INVALID_ARGUMENT + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription * \retval #PSA_ERROR_BUFFER_TOO_SMALL * \p hash_size is too small - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -890,10 +890,10 @@ psa_status_t psa_hash_compute(psa_algorithm_t alg, * \p alg is not supported or is not a hash algorithm. * \retval #PSA_ERROR_INVALID_ARGUMENT * \p input_length or \p hash_length do not match the hash size for \p alg - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -989,10 +989,10 @@ static psa_hash_operation_t psa_hash_operation_init(void); * \p alg is not a supported hash algorithm. * \retval #PSA_ERROR_INVALID_ARGUMENT * \p alg is not a hash algorithm. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be inactive), or * the library has not been previously initialized by psa_crypto_init(). @@ -1015,10 +1015,10 @@ psa_status_t psa_hash_setup(psa_hash_operation_t *operation, * * \retval #PSA_SUCCESS * Success. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be active), or * the library has not been previously initialized by psa_crypto_init(). @@ -1061,10 +1061,10 @@ psa_status_t psa_hash_update(psa_hash_operation_t *operation, * The size of the \p hash buffer is too small. You can determine a * sufficient buffer size by calling #PSA_HASH_LENGTH(\c alg) * where \c alg is the hash algorithm that is calculated. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be active), or * the library has not been previously initialized by psa_crypto_init(). @@ -1102,10 +1102,10 @@ psa_status_t psa_hash_finish(psa_hash_operation_t *operation, * \retval #PSA_ERROR_INVALID_SIGNATURE * The hash of the message was calculated successfully, but it * differs from the expected hash. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be active), or * the library has not been previously initialized by psa_crypto_init(). @@ -1132,10 +1132,10 @@ psa_status_t psa_hash_verify(psa_hash_operation_t *operation, * * \param[in,out] operation Initialized hash operation. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -1158,11 +1158,11 @@ psa_status_t psa_hash_abort(psa_hash_operation_t *operation); * \param[in,out] target_operation The operation object to set up. * It must be initialized but not active. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription * \retval #PSA_ERROR_BAD_STATE * The \p source_operation state is not valid (it must be active), or * the \p target_operation state is not valid (it must be inactive), or @@ -1202,18 +1202,18 @@ psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation, * * \retval #PSA_SUCCESS * Success. - * \retval #PSA_ERROR_INVALID_HANDLE - * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription + * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription * \retval #PSA_ERROR_INVALID_ARGUMENT * \p key is not compatible with \p alg. * \retval #PSA_ERROR_NOT_SUPPORTED * \p alg is not supported or is not a MAC algorithm. * \retval #PSA_ERROR_BUFFER_TOO_SMALL * \p mac_size is too small - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_STORAGE_FAILURE * The key could not be retrieved from storage. * \retval #PSA_ERROR_BAD_STATE @@ -1245,16 +1245,16 @@ psa_status_t psa_mac_compute(mbedtls_svc_key_id_t key, * \retval #PSA_ERROR_INVALID_SIGNATURE * The MAC of the message was calculated successfully, but it * differs from the expected value. - * \retval #PSA_ERROR_INVALID_HANDLE - * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription + * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription * \retval #PSA_ERROR_INVALID_ARGUMENT * \p key is not compatible with \p alg. * \retval #PSA_ERROR_NOT_SUPPORTED * \p alg is not supported or is not a MAC algorithm. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_STORAGE_FAILURE * The key could not be retrieved from storage. * \retval #PSA_ERROR_BAD_STATE @@ -1355,16 +1355,16 @@ static psa_mac_operation_t psa_mac_operation_init(void); * * \retval #PSA_SUCCESS * Success. - * \retval #PSA_ERROR_INVALID_HANDLE - * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription + * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription * \retval #PSA_ERROR_INVALID_ARGUMENT * \p key is not compatible with \p alg. * \retval #PSA_ERROR_NOT_SUPPORTED * \p alg is not supported or is not a MAC algorithm. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_STORAGE_FAILURE * The key could not be retrieved from storage. * \retval #PSA_ERROR_BAD_STATE @@ -1417,16 +1417,16 @@ psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation, * * \retval #PSA_SUCCESS * Success. - * \retval #PSA_ERROR_INVALID_HANDLE - * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription + * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription * \retval #PSA_ERROR_INVALID_ARGUMENT * \c key is not compatible with \c alg. * \retval #PSA_ERROR_NOT_SUPPORTED * \c alg is not supported or is not a MAC algorithm. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_STORAGE_FAILURE * The key could not be retrieved from storage. * \retval #PSA_ERROR_BAD_STATE @@ -1454,11 +1454,11 @@ psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation, * * \retval #PSA_SUCCESS * Success. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be active), or * the library has not been previously initialized by psa_crypto_init(). @@ -1502,11 +1502,11 @@ psa_status_t psa_mac_update(psa_mac_operation_t *operation, * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p mac buffer is too small. You can determine a * sufficient buffer size by calling PSA_MAC_LENGTH(). - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be an active mac sign * operation), or the library has not been previously initialized @@ -1545,11 +1545,11 @@ psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation, * \retval #PSA_ERROR_INVALID_SIGNATURE * The MAC of the message was calculated successfully, but it * differs from the expected MAC. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be an active mac verify * operation), or the library has not been previously initialized @@ -1577,10 +1577,10 @@ psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation, * * \param[in,out] operation Initialized MAC operation. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -1616,18 +1616,18 @@ psa_status_t psa_mac_abort(psa_mac_operation_t *operation); * * \retval #PSA_SUCCESS * Success. - * \retval #PSA_ERROR_INVALID_HANDLE - * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription + * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription * \retval #PSA_ERROR_INVALID_ARGUMENT * \p key is not compatible with \p alg. * \retval #PSA_ERROR_NOT_SUPPORTED * \p alg is not supported or is not a cipher algorithm. - * \retval #PSA_ERROR_BUFFER_TOO_SMALL - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_BUFFER_TOO_SMALL \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -1663,18 +1663,18 @@ psa_status_t psa_cipher_encrypt(mbedtls_svc_key_id_t key, * * \retval #PSA_SUCCESS * Success. - * \retval #PSA_ERROR_INVALID_HANDLE - * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription + * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription * \retval #PSA_ERROR_INVALID_ARGUMENT * \p key is not compatible with \p alg. * \retval #PSA_ERROR_NOT_SUPPORTED * \p alg is not supported or is not a cipher algorithm. - * \retval #PSA_ERROR_BUFFER_TOO_SMALL - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_BUFFER_TOO_SMALL \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -1776,17 +1776,17 @@ static psa_cipher_operation_t psa_cipher_operation_init(void); * * \retval #PSA_SUCCESS * Success. - * \retval #PSA_ERROR_INVALID_HANDLE - * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription + * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription * \retval #PSA_ERROR_INVALID_ARGUMENT * \p key is not compatible with \p alg. * \retval #PSA_ERROR_NOT_SUPPORTED * \p alg is not supported or is not a cipher algorithm. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be inactive), or * the library has not been previously initialized by psa_crypto_init(). @@ -1839,17 +1839,17 @@ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation, * * \retval #PSA_SUCCESS * Success. - * \retval #PSA_ERROR_INVALID_HANDLE - * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription + * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription * \retval #PSA_ERROR_INVALID_ARGUMENT * \p key is not compatible with \p alg. * \retval #PSA_ERROR_NOT_SUPPORTED * \p alg is not supported or is not a cipher algorithm. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be inactive), or * the library has not been previously initialized by psa_crypto_init(). @@ -1882,11 +1882,11 @@ psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation, * Success. * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p iv buffer is too small. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be active, with no IV set), * or the library has not been previously initialized @@ -1923,11 +1923,11 @@ psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation, * \retval #PSA_ERROR_INVALID_ARGUMENT * The size of \p iv is not acceptable for the chosen algorithm, * or the chosen algorithm does not use an IV. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be an active cipher * encrypt operation, with no IV set), or the library has not been @@ -1964,11 +1964,11 @@ psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation, * Success. * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p output buffer is too small. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be active, with an IV set * if required for the algorithm), or the library has not been @@ -2016,11 +2016,11 @@ psa_status_t psa_cipher_update(psa_cipher_operation_t *operation, * padding, and the ciphertext does not contain valid padding. * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p output buffer is too small. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be active, with an IV set * if required for the algorithm), or the library has not been @@ -2049,10 +2049,10 @@ psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation, * * \param[in,out] operation Initialized cipher operation. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -2105,23 +2105,23 @@ psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation); * * \retval #PSA_SUCCESS * Success. - * \retval #PSA_ERROR_INVALID_HANDLE - * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription + * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription * \retval #PSA_ERROR_INVALID_ARGUMENT * \p key is not compatible with \p alg. * \retval #PSA_ERROR_NOT_SUPPORTED * \p alg is not supported or is not an AEAD algorithm. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription * \retval #PSA_ERROR_BUFFER_TOO_SMALL * \p ciphertext_size is too small. * #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\c key_type, \p alg, * \p plaintext_length) or * #PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(\p plaintext_length) can be used to * determine the required buffer size. - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -2176,25 +2176,25 @@ psa_status_t psa_aead_encrypt(mbedtls_svc_key_id_t key, * * \retval #PSA_SUCCESS * Success. - * \retval #PSA_ERROR_INVALID_HANDLE + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription * \retval #PSA_ERROR_INVALID_SIGNATURE * The ciphertext is not authentic. - * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription * \retval #PSA_ERROR_INVALID_ARGUMENT * \p key is not compatible with \p alg. * \retval #PSA_ERROR_NOT_SUPPORTED * \p alg is not supported or is not an AEAD algorithm. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription * \retval #PSA_ERROR_BUFFER_TOO_SMALL * \p plaintext_size is too small. * #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\c key_type, \p alg, * \p ciphertext_length) or * #PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE(\p ciphertext_length) can be used * to determine the required buffer size. - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -2309,16 +2309,16 @@ static psa_aead_operation_t psa_aead_operation_init(void); * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be inactive), or * the library has not been previously initialized by psa_crypto_init(). - * \retval #PSA_ERROR_INVALID_HANDLE - * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription + * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription * \retval #PSA_ERROR_INVALID_ARGUMENT * \p key is not compatible with \p alg. * \retval #PSA_ERROR_NOT_SUPPORTED * \p alg is not supported or is not an AEAD algorithm. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_STORAGE_FAILURE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -2373,17 +2373,17 @@ psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation, * * \retval #PSA_SUCCESS * Success. - * \retval #PSA_ERROR_INVALID_HANDLE - * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription + * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription * \retval #PSA_ERROR_INVALID_ARGUMENT * \p key is not compatible with \p alg. * \retval #PSA_ERROR_NOT_SUPPORTED * \p alg is not supported or is not an AEAD algorithm. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be inactive), or the * library has not been previously initialized by psa_crypto_init(). @@ -2417,11 +2417,11 @@ psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation, * Success. * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p nonce buffer is too small. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be an active aead encrypt * operation, with no nonce set), or the library has not been @@ -2457,11 +2457,11 @@ psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation, * Success. * \retval #PSA_ERROR_INVALID_ARGUMENT * The size of \p nonce is not acceptable for the chosen algorithm. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be active, with no nonce * set), or the library has not been previously initialized @@ -2502,10 +2502,10 @@ psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation, * \retval #PSA_ERROR_INVALID_ARGUMENT * At least one of the lengths is not acceptable for the chosen * algorithm. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be active, and * psa_aead_update_ad() and psa_aead_update() must not have been @@ -2549,11 +2549,11 @@ psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation, * \retval #PSA_ERROR_INVALID_ARGUMENT * The total input length overflows the additional data length that * was previously specified with psa_aead_set_lengths(). - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be active, have a nonce * set, have lengths set if required by the algorithm, and @@ -2634,11 +2634,11 @@ psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation, * specified with psa_aead_set_lengths(), or * the total input length overflows the plaintext length that * was previously specified with psa_aead_set_lengths(). - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be active, have a nonce * set, and have lengths set if required by the algorithm), or the @@ -2720,11 +2720,11 @@ psa_status_t psa_aead_update(psa_aead_operation_t *operation, * the total length of input to psa_aead_update() so far is * less than the plaintext length that was previously * specified with psa_aead_set_lengths(). - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be an active encryption * operation with a nonce set), or the library has not been previously @@ -2803,11 +2803,11 @@ psa_status_t psa_aead_finish(psa_aead_operation_t *operation, * the total length of input to psa_aead_update() so far is * less than the plaintext length that was previously * specified with psa_aead_set_lengths(). - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be an active decryption * operation with a nonce set), or the library has not been previously @@ -2838,10 +2838,10 @@ psa_status_t psa_aead_verify(psa_aead_operation_t *operation, * * \param[in,out] operation Initialized AEAD operation. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -2887,8 +2887,8 @@ psa_status_t psa_aead_abort(psa_aead_operation_t *operation); * \param[out] signature_length On success, the number of bytes that make up * the returned signature value. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_INVALID_HANDLE + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription * \retval #PSA_ERROR_NOT_PERMITTED * The key does not have the #PSA_KEY_USAGE_SIGN_MESSAGE flag, * or it does not permit the requested algorithm. @@ -2898,16 +2898,16 @@ psa_status_t psa_aead_abort(psa_aead_operation_t *operation); * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) * where \c key_type and \c key_bits are the type and bit-size * respectively of \p key. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INVALID_ARGUMENT - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_DATA_CORRUPT - * \retval #PSA_ERROR_DATA_INVALID - * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription + * \retval #PSA_ERROR_DATA_INVALID \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -2943,23 +2943,23 @@ psa_status_t psa_sign_message(mbedtls_svc_key_id_t key, * \param[out] signature Buffer containing the signature to verify. * \param[in] signature_length Size of the \p signature buffer in bytes. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_INVALID_HANDLE + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription * \retval #PSA_ERROR_NOT_PERMITTED * The key does not have the #PSA_KEY_USAGE_SIGN_MESSAGE flag, * or it does not permit the requested algorithm. * \retval #PSA_ERROR_INVALID_SIGNATURE * The calculation was performed successfully, but the passed signature * is not a valid signature. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INVALID_ARGUMENT - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_DATA_CORRUPT - * \retval #PSA_ERROR_DATA_INVALID + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription + * \retval #PSA_ERROR_DATA_INVALID \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -2996,23 +2996,23 @@ psa_status_t psa_verify_message(mbedtls_svc_key_id_t key, * \param[out] signature_length On success, the number of bytes * that make up the returned signature value. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_INVALID_HANDLE - * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription + * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p signature buffer is too small. You can * determine a sufficient buffer size by calling * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) * where \c key_type and \c key_bits are the type and bit-size * respectively of \p key. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INVALID_ARGUMENT - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -3052,18 +3052,18 @@ psa_status_t psa_sign_hash(mbedtls_svc_key_id_t key, * * \retval #PSA_SUCCESS * The signature is valid. - * \retval #PSA_ERROR_INVALID_HANDLE - * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription + * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription * \retval #PSA_ERROR_INVALID_SIGNATURE * The calculation was performed successfully, but the passed * signature is not a valid signature. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INVALID_ARGUMENT - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -3105,23 +3105,23 @@ psa_status_t psa_verify_hash(mbedtls_svc_key_id_t key, * \param[out] output_length On success, the number of bytes * that make up the returned output. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_INVALID_HANDLE - * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription + * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p output buffer is too small. You can * determine a sufficient buffer size by calling * #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) * where \c key_type and \c key_bits are the type and bit-size * respectively of \p key. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INVALID_ARGUMENT - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -3165,24 +3165,24 @@ psa_status_t psa_asymmetric_encrypt(mbedtls_svc_key_id_t key, * \param[out] output_length On success, the number of bytes * that make up the returned output. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_INVALID_HANDLE - * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription + * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p output buffer is too small. You can * determine a sufficient buffer size by calling * #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) * where \c key_type and \c key_bits are the type and bit-size * respectively of \p key. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INVALID_ARGUMENT - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY - * \retval #PSA_ERROR_INVALID_PADDING + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription + * \retval #PSA_ERROR_INVALID_PADDING \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -3298,11 +3298,11 @@ static psa_key_derivation_operation_t psa_key_derivation_operation_init(void); * \c alg is not a key derivation algorithm. * \retval #PSA_ERROR_NOT_SUPPORTED * \c alg is not supported or is not a key derivation algorithm. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be inactive), or * the library has not been previously initialized by psa_crypto_init(). @@ -3322,10 +3322,10 @@ psa_status_t psa_key_derivation_setup( * \param[in] operation The operation to query. * \param[out] capacity On success, the capacity of the operation. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be active), or * the library has not been previously initialized by psa_crypto_init(). @@ -3346,14 +3346,14 @@ psa_status_t psa_key_derivation_get_capacity( * It must be less or equal to the operation's * current capacity. * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription * \retval #PSA_ERROR_INVALID_ARGUMENT * \p capacity is larger than the operation's current capacity. * In this case, the operation object remains valid and its capacity * remains unchanged. - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be active), or the * library has not been previously initialized by psa_crypto_init(). @@ -3402,11 +3402,11 @@ psa_status_t psa_key_derivation_set_capacity( * \retval #PSA_ERROR_INVALID_ARGUMENT * \c step is not compatible with the operation's algorithm, or * \c step does not allow direct inputs. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid for this input \p step, or * the library has not been previously initialized by psa_crypto_init(). @@ -3447,17 +3447,17 @@ psa_status_t psa_key_derivation_input_bytes( * * \retval #PSA_SUCCESS * Success. - * \retval #PSA_ERROR_INVALID_HANDLE - * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription + * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription * \retval #PSA_ERROR_INVALID_ARGUMENT * \c step is not compatible with the operation's algorithm, or * \c step does not allow key inputs of the given type * or does not allow key inputs at all. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid for this input \p step, or * the library has not been previously initialized by psa_crypto_init(). @@ -3512,8 +3512,8 @@ psa_status_t psa_key_derivation_input_key( * * \retval #PSA_SUCCESS * Success. - * \retval #PSA_ERROR_INVALID_HANDLE - * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription + * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription * \retval #PSA_ERROR_INVALID_ARGUMENT * \c private_key is not compatible with \c alg, * or \p peer_key is not valid for \c alg or not compatible with @@ -3521,11 +3521,11 @@ psa_status_t psa_key_derivation_input_key( * from a key agreement. * \retval #PSA_ERROR_NOT_SUPPORTED * \c alg is not supported or is not a key derivation algorithm. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid for this key agreement \p step, * or the library has not been previously initialized by psa_crypto_init(). @@ -3556,7 +3556,7 @@ psa_status_t psa_key_derivation_key_agreement( * \param[out] output Buffer where the output will be written. * \param output_length Number of bytes to output. * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription * \retval #PSA_ERROR_INSUFFICIENT_DATA * The operation's capacity was less than * \p output_length bytes. Note that in this case, @@ -3564,11 +3564,11 @@ psa_status_t psa_key_derivation_key_agreement( * The operation's capacity is set to 0, thus * subsequent calls to this function will not * succeed, even with a smaller output buffer. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be active and completed * all required input steps), or the library has not been previously @@ -3705,14 +3705,14 @@ psa_status_t psa_key_derivation_output_bytes( * \retval #PSA_ERROR_NOT_PERMITTED * The #PSA_KEY_DERIVATION_INPUT_SECRET input was not provided through * a key. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_INSUFFICIENT_STORAGE - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_DATA_INVALID - * \retval #PSA_ERROR_DATA_CORRUPT - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_DATA_INVALID \emptydescription + * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be active and completed * all required input steps), or the library has not been previously @@ -3739,10 +3739,10 @@ psa_status_t psa_key_derivation_output_key( * * \param[in,out] operation The operation to abort. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -3780,8 +3780,8 @@ psa_status_t psa_key_derivation_abort( * * \retval #PSA_SUCCESS * Success. - * \retval #PSA_ERROR_INVALID_HANDLE - * \retval #PSA_ERROR_NOT_PERMITTED + * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription + * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription * \retval #PSA_ERROR_INVALID_ARGUMENT * \p alg is not a key agreement algorithm, or * \p private_key is not compatible with \p alg, @@ -3791,11 +3791,11 @@ psa_status_t psa_key_derivation_abort( * \p output_size is too small * \retval #PSA_ERROR_NOT_SUPPORTED * \p alg is not a supported key agreement algorithm. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -3827,13 +3827,13 @@ psa_status_t psa_raw_key_agreement(psa_algorithm_t alg, * \param[out] output Output buffer for the generated data. * \param output_size Number of bytes to generate and output. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -3870,17 +3870,17 @@ psa_status_t psa_generate_random(uint8_t *output, * \retval #PSA_ERROR_ALREADY_EXISTS * This is an attempt to create a persistent key, and there is * already a persistent key with the given identifier. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INVALID_ARGUMENT - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_INSUFFICIENT_STORAGE - * \retval #PSA_ERROR_DATA_INVALID - * \retval #PSA_ERROR_DATA_CORRUPT - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription + * \retval #PSA_ERROR_DATA_INVALID \emptydescription + * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize diff --git a/include/psa/crypto_compat.h b/include/psa/crypto_compat.h index 7ae6cbbf7..5cb225bd5 100644 --- a/include/psa/crypto_compat.h +++ b/include/psa/crypto_compat.h @@ -470,11 +470,11 @@ MBEDTLS_PSA_DEPRECATED static inline psa_status_t psa_asymmetric_verify(psa_key_ * permission to access it. Note that this specification does not * define any way to create such a key, but it may be possible * through implementation-specific means. - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_DATA_INVALID - * \retval #PSA_ERROR_DATA_CORRUPT + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_DATA_INVALID \emptydescription + * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -514,8 +514,8 @@ psa_status_t psa_open_key(mbedtls_svc_key_id_t key, * \p handle was a valid handle or \c 0. It is now closed. * \retval #PSA_ERROR_INVALID_HANDLE * \p handle is not a valid handle nor \c 0. - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h index b62acdbb8..fa3e383f0 100644 --- a/include/psa/crypto_extra.h +++ b/include/psa/crypto_extra.h @@ -187,12 +187,12 @@ static inline void psa_clear_key_slot_number( * or the specified slot number is not valid. * \retval #PSA_ERROR_NOT_PERMITTED * The caller is not authorized to register the specified key slot. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_INSUFFICIENT_STORAGE - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_DATA_INVALID - * \retval #PSA_ERROR_DATA_CORRUPT - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_DATA_INVALID \emptydescription + * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize @@ -487,10 +487,10 @@ psa_status_t mbedtls_psa_inject_entropy(const uint8_t *seed, * according to \p type as described above. * \param data_length Size of the \p data buffer in bytes. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_INVALID_ARGUMENT - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription */ psa_status_t psa_set_key_domain_parameters(psa_key_attributes_t *attributes, psa_key_type_t type, @@ -517,8 +517,8 @@ psa_status_t psa_set_key_domain_parameters(psa_key_attributes_t *attributes, * \param[out] data_length On success, the number of bytes * that make up the key domain parameters data. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_BUFFER_TOO_SMALL + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_BUFFER_TOO_SMALL \emptydescription */ psa_status_t psa_get_key_domain_parameters( const psa_key_attributes_t *attributes, diff --git a/include/psa/crypto_se_driver.h b/include/psa/crypto_se_driver.h index bffebdd51..e2acb714e 100644 --- a/include/psa/crypto_se_driver.h +++ b/include/psa/crypto_se_driver.h @@ -384,8 +384,8 @@ typedef struct { * \param[in] direction Indicates whether the operation is an encrypt * or decrypt * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_NOT_SUPPORTED + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription */ typedef psa_status_t (*psa_drv_se_cipher_setup_t)(psa_drv_se_context_t *drv_context, void *op_context, @@ -406,7 +406,7 @@ typedef psa_status_t (*psa_drv_se_cipher_setup_t)(psa_drv_se_context_t *drv_cont * \param[in] p_iv A buffer containing the initialization vector * \param[in] iv_length The size (in bytes) of the `p_iv` buffer * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription */ typedef psa_status_t (*psa_drv_se_cipher_set_iv_t)(void *op_context, const uint8_t *p_iv, @@ -428,7 +428,7 @@ typedef psa_status_t (*psa_drv_se_cipher_set_iv_t)(void *op_context, * \param[out] p_output_length After completion, will contain the number * of bytes placed in the `p_output` buffer * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription */ typedef psa_status_t (*psa_drv_se_cipher_update_t)(void *op_context, const uint8_t *p_input, @@ -449,7 +449,7 @@ typedef psa_status_t (*psa_drv_se_cipher_update_t)(void *op_context, * \param[out] p_output_length After completion, will contain the number of * bytes placed in the `p_output` buffer * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription */ typedef psa_status_t (*psa_drv_se_cipher_finish_t)(void *op_context, uint8_t *p_output, @@ -484,8 +484,8 @@ typedef psa_status_t (*psa_drv_se_cipher_abort_t)(void *op_context); * \param[in] output_size The allocated size in bytes of the `p_output` * buffer * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_NOT_SUPPORTED + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription */ typedef psa_status_t (*psa_drv_se_cipher_ecb_t)(psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, @@ -553,7 +553,7 @@ typedef struct { * \param[out] p_signature_length On success, the number of bytes * that make up the returned signature value * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription */ typedef psa_status_t (*psa_drv_se_asymmetric_sign_t)(psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, @@ -617,7 +617,7 @@ typedef psa_status_t (*psa_drv_se_asymmetric_verify_t)(psa_drv_se_context_t *drv * \param[out] p_output_length On success, the number of bytes that make up * the returned output * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription */ typedef psa_status_t (*psa_drv_se_asymmetric_encrypt_t)(psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, @@ -657,7 +657,7 @@ typedef psa_status_t (*psa_drv_se_asymmetric_encrypt_t)(psa_drv_se_context_t *dr * \param[out] p_output_length On success, the number of bytes * that make up the returned output * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription */ typedef psa_status_t (*psa_drv_se_asymmetric_decrypt_t)(psa_drv_se_context_t *drv_context, psa_key_slot_number_t key_slot, @@ -903,8 +903,8 @@ typedef enum { * Success. * The core will record \c *key_slot as the key slot where the key * is stored and will update the persistent data in storage. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INSUFFICIENT_STORAGE + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription */ typedef psa_status_t (*psa_drv_se_allocate_key_t)( psa_drv_se_context_t *drv_context, @@ -1042,13 +1042,13 @@ typedef psa_status_t (*psa_drv_se_destroy_key_t)( * \param[out] p_data_length On success, the number of bytes * that make up the key data. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_DOES_NOT_EXIST - * \retval #PSA_ERROR_NOT_PERMITTED - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_DOES_NOT_EXIST \emptydescription + * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription */ typedef psa_status_t (*psa_drv_se_export_key_t)(psa_drv_se_context_t *drv_context, psa_key_slot_number_t key, @@ -1195,7 +1195,7 @@ typedef struct { * \param[in] source_key The key to be used as the source material for * the key derivation * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription */ typedef psa_status_t (*psa_drv_se_key_derivation_setup_t)(psa_drv_se_context_t *drv_context, void *op_context, @@ -1215,7 +1215,7 @@ typedef psa_status_t (*psa_drv_se_key_derivation_setup_t)(psa_drv_se_context_t * * \param[in] p_collateral A buffer containing the collateral data * \param[in] collateral_size The size in bytes of the collateral * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription */ typedef psa_status_t (*psa_drv_se_key_derivation_collateral_t)(void *op_context, uint32_t collateral_id, @@ -1230,7 +1230,7 @@ typedef psa_status_t (*psa_drv_se_key_derivation_collateral_t)(void *op_context, * \param[in] dest_key The slot where the generated key material * should be placed * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription */ typedef psa_status_t (*psa_drv_se_key_derivation_derive_t)(void *op_context, psa_key_slot_number_t dest_key); @@ -1244,7 +1244,7 @@ typedef psa_status_t (*psa_drv_se_key_derivation_derive_t)(void *op_context, * \param[out] p_output_length Upon success, contains the number of bytes of * key material placed in `p_output` * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription */ typedef psa_status_t (*psa_drv_se_key_derivation_export_t)(void *op_context, uint8_t *p_output, diff --git a/library/psa_crypto.c b/library/psa_crypto.c index 9976d72fe..d8a994045 100644 --- a/library/psa_crypto.c +++ b/library/psa_crypto.c @@ -1755,12 +1755,12 @@ static psa_status_t psa_start_key_creation( * * \retval #PSA_SUCCESS * The key was successfully created. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_INSUFFICIENT_STORAGE - * \retval #PSA_ERROR_ALREADY_EXISTS - * \retval #PSA_ERROR_DATA_INVALID - * \retval #PSA_ERROR_DATA_CORRUPT - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription + * \retval #PSA_ERROR_ALREADY_EXISTS \emptydescription + * \retval #PSA_ERROR_DATA_INVALID \emptydescription + * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription * * \return If this function fails, the key slot is an invalid state. * You must call psa_fail_key_creation() to wipe and free the slot. diff --git a/library/psa_crypto_aead.h b/library/psa_crypto_aead.h index 320f835e4..8586c7bfa 100644 --- a/library/psa_crypto_aead.h +++ b/library/psa_crypto_aead.h @@ -71,10 +71,10 @@ * \retval #PSA_SUCCESS Success. * \retval #PSA_ERROR_NOT_SUPPORTED * \p alg is not supported. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription * \retval #PSA_ERROR_BUFFER_TOO_SMALL * ciphertext_size is too small. - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription */ psa_status_t mbedtls_psa_aead_encrypt( const psa_key_attributes_t *attributes, @@ -134,10 +134,10 @@ psa_status_t mbedtls_psa_aead_encrypt( * The cipher is not authentic. * \retval #PSA_ERROR_NOT_SUPPORTED * \p alg is not supported. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription * \retval #PSA_ERROR_BUFFER_TOO_SMALL * plaintext_size is too small. - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription */ psa_status_t mbedtls_psa_aead_decrypt( const psa_key_attributes_t *attributes, diff --git a/library/psa_crypto_cipher.h b/library/psa_crypto_cipher.h index 6cc6bf614..bf43ff08a 100644 --- a/library/psa_crypto_cipher.h +++ b/library/psa_crypto_cipher.h @@ -59,10 +59,10 @@ const mbedtls_cipher_info_t *mbedtls_cipher_info_from_psa( * (\c PSA_ALG_XXX value such that * #PSA_ALG_IS_CIPHER(\p alg) is true). * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription */ psa_status_t mbedtls_psa_cipher_encrypt_setup( mbedtls_psa_cipher_operation_t *operation, @@ -89,10 +89,10 @@ psa_status_t mbedtls_psa_cipher_encrypt_setup( * (\c PSA_ALG_XXX value such that * #PSA_ALG_IS_CIPHER(\p alg) is true). * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription */ psa_status_t mbedtls_psa_cipher_decrypt_setup( mbedtls_psa_cipher_operation_t *operation, @@ -116,11 +116,11 @@ psa_status_t mbedtls_psa_cipher_decrypt_setup( * the core to be less or equal to * PSA_CIPHER_IV_MAX_SIZE. * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription * \retval #PSA_ERROR_INVALID_ARGUMENT * The size of \p iv is not acceptable for the chosen algorithm, * or the chosen algorithm does not use an IV. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription */ psa_status_t mbedtls_psa_cipher_set_iv( mbedtls_psa_cipher_operation_t *operation, @@ -142,10 +142,10 @@ psa_status_t mbedtls_psa_cipher_set_iv( * \param[out] output_length On success, the number of bytes * that make up the returned output. * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p output buffer is too small. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription */ psa_status_t mbedtls_psa_cipher_update( mbedtls_psa_cipher_operation_t *operation, @@ -165,7 +165,7 @@ psa_status_t mbedtls_psa_cipher_update( * \param[out] output_length On success, the number of bytes * that make up the returned output. * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription * \retval #PSA_ERROR_INVALID_ARGUMENT * The total input size passed to this operation is not valid for * this particular algorithm. For example, the algorithm is a based @@ -176,7 +176,7 @@ psa_status_t mbedtls_psa_cipher_update( * padding, and the ciphertext does not contain valid padding. * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p output buffer is too small. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription */ psa_status_t mbedtls_psa_cipher_finish( mbedtls_psa_cipher_operation_t *operation, @@ -195,7 +195,7 @@ psa_status_t mbedtls_psa_cipher_finish( * * \param[in,out] operation Initialized cipher operation. * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription */ psa_status_t mbedtls_psa_cipher_abort(mbedtls_psa_cipher_operation_t *operation); @@ -224,10 +224,10 @@ psa_status_t mbedtls_psa_cipher_abort(mbedtls_psa_cipher_operation_t *operation) * the returned output. Initialized to zero * by the core. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p output buffer is too small. * \retval #PSA_ERROR_INVALID_ARGUMENT @@ -275,10 +275,10 @@ psa_status_t mbedtls_psa_cipher_encrypt(const psa_key_attributes_t *attributes, * the returned output. Initialized to zero * by the core. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p output buffer is too small. * \retval #PSA_ERROR_INVALID_ARGUMENT diff --git a/library/psa_crypto_core.h b/library/psa_crypto_core.h index 672fb5dbc..688ea3885 100644 --- a/library/psa_crypto_core.h +++ b/library/psa_crypto_core.h @@ -195,7 +195,7 @@ static inline psa_key_slot_number_t psa_key_slot_get_slot_number( * \retval #PSA_SUCCESS * Success. This includes the case of a key slot that was * already fully wiped. - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription */ psa_status_t psa_wipe_key_slot(psa_key_slot_t *slot); @@ -271,9 +271,9 @@ psa_status_t mbedtls_to_psa_error(int ret); * \retval #PSA_SUCCESS The key was imported successfully. * \retval #PSA_ERROR_INVALID_ARGUMENT * The key data is not correctly formatted. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription */ psa_status_t psa_import_key_into_slot( const psa_key_attributes_t *attributes, @@ -296,12 +296,12 @@ psa_status_t psa_import_key_into_slot( * \p data * * \retval #PSA_SUCCESS The key was exported successfully. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription */ psa_status_t psa_export_key_internal( const psa_key_attributes_t *attributes, @@ -324,12 +324,12 @@ psa_status_t psa_export_key_internal( * \p data * * \retval #PSA_SUCCESS The public key was exported successfully. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription */ psa_status_t psa_export_public_key_internal( const psa_key_attributes_t *attributes, @@ -350,7 +350,7 @@ psa_status_t psa_export_public_key_internal( * * \retval #PSA_SUCCESS * The key was generated successfully. - * \retval #PSA_ERROR_INVALID_ARGUMENT + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription * \retval #PSA_ERROR_NOT_SUPPORTED * Key size in bits or type not supported. * \retval #PSA_ERROR_BUFFER_TOO_SMALL @@ -385,18 +385,18 @@ psa_status_t psa_generate_key_internal(const psa_key_attributes_t *attributes, * \param[out] signature_length On success, the number of bytes * that make up the returned signature value. * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p signature buffer is too small. You can * determine a sufficient buffer size by calling * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) * where \c key_type and \c key_bits are the type and bit-size * respectively of the key. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INVALID_ARGUMENT - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription */ psa_status_t psa_sign_message_builtin( const psa_key_attributes_t *attributes, @@ -431,9 +431,9 @@ psa_status_t psa_sign_message_builtin( * \retval #PSA_ERROR_INVALID_SIGNATURE * The calculation was performed successfully, but the passed * signature is not a valid signature. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INVALID_ARGUMENT - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription */ psa_status_t psa_verify_message_builtin( const psa_key_attributes_t *attributes, @@ -461,18 +461,18 @@ psa_status_t psa_verify_message_builtin( * \param[out] signature_length On success, the number of bytes * that make up the returned signature value. * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p signature buffer is too small. You can * determine a sufficient buffer size by calling * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) * where \c key_type and \c key_bits are the type and bit-size * respectively of the key. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INVALID_ARGUMENT - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription */ psa_status_t psa_sign_hash_builtin( const psa_key_attributes_t *attributes, @@ -505,9 +505,9 @@ psa_status_t psa_sign_hash_builtin( * \retval #PSA_ERROR_INVALID_SIGNATURE * The calculation was performed successfully, but the passed * signature is not a valid signature. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INVALID_ARGUMENT - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription */ psa_status_t psa_verify_hash_builtin( const psa_key_attributes_t *attributes, diff --git a/library/psa_crypto_ecp.h b/library/psa_crypto_ecp.h index b6dc2473a..7541c7749 100644 --- a/library/psa_crypto_ecp.h +++ b/library/psa_crypto_ecp.h @@ -70,9 +70,9 @@ psa_status_t mbedtls_psa_ecp_load_representation(psa_key_type_t type, * \retval #PSA_SUCCESS The ECP key was imported successfully. * \retval #PSA_ERROR_INVALID_ARGUMENT * The key data is not correctly formatted. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription */ psa_status_t mbedtls_psa_ecp_import_key( const psa_key_attributes_t *attributes, @@ -111,12 +111,12 @@ psa_status_t mbedtls_psa_ecp_export_key(psa_key_type_t type, * \p data * * \retval #PSA_SUCCESS The ECP public key was exported successfully. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription */ psa_status_t mbedtls_psa_ecp_export_public_key( const psa_key_attributes_t *attributes, @@ -166,17 +166,17 @@ psa_status_t mbedtls_psa_ecp_generate_key( * \param[out] signature_length On success, the number of bytes * that make up the returned signature value. * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p signature buffer is too small. You can * determine a sufficient buffer size by calling * #PSA_SIGN_OUTPUT_SIZE(\c PSA_KEY_TYPE_ECC_KEY_PAIR, \c key_bits, * \p alg) where \c key_bits is the bit-size of the ECC key. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INVALID_ARGUMENT - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription */ psa_status_t mbedtls_psa_ecdsa_sign_hash( const psa_key_attributes_t *attributes, @@ -209,9 +209,9 @@ psa_status_t mbedtls_psa_ecdsa_sign_hash( * \retval #PSA_ERROR_INVALID_SIGNATURE * The calculation was performed successfully, but the passed * signature is not a valid signature. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INVALID_ARGUMENT - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription */ psa_status_t mbedtls_psa_ecdsa_verify_hash( const psa_key_attributes_t *attributes, diff --git a/library/psa_crypto_hash.h b/library/psa_crypto_hash.h index ab07231ed..1c1b45198 100644 --- a/library/psa_crypto_hash.h +++ b/library/psa_crypto_hash.h @@ -57,8 +57,8 @@ const mbedtls_md_info_t *mbedtls_md_info_from_psa(psa_algorithm_t alg); * \p alg is not supported * \retval #PSA_ERROR_BUFFER_TOO_SMALL * \p hash_size is too small - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription */ psa_status_t mbedtls_psa_hash_compute( psa_algorithm_t alg, @@ -97,8 +97,8 @@ psa_status_t mbedtls_psa_hash_compute( * \p alg is not supported * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be inactive). - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription */ psa_status_t mbedtls_psa_hash_setup( mbedtls_psa_hash_operation_t *operation, @@ -124,13 +124,13 @@ psa_status_t mbedtls_psa_hash_setup( * \param[in,out] target_operation The operation object to set up. * It must be initialized but not active. * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription * \retval #PSA_ERROR_BAD_STATE * The \p source_operation state is not valid (it must be active). * \retval #PSA_ERROR_BAD_STATE * The \p target_operation state is not valid (it must be inactive). - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription */ psa_status_t mbedtls_psa_hash_clone( const mbedtls_psa_hash_operation_t *source_operation, @@ -156,8 +156,8 @@ psa_status_t mbedtls_psa_hash_clone( * Success. * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be active). - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription */ psa_status_t mbedtls_psa_hash_update( mbedtls_psa_hash_operation_t *operation, @@ -195,8 +195,8 @@ psa_status_t mbedtls_psa_hash_update( * The size of the \p hash buffer is too small. You can determine a * sufficient buffer size by calling #PSA_HASH_LENGTH(\c alg) * where \c alg is the hash algorithm that is calculated. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription */ psa_status_t mbedtls_psa_hash_finish( mbedtls_psa_hash_operation_t *operation, @@ -225,8 +225,8 @@ psa_status_t mbedtls_psa_hash_finish( * * \param[in,out] operation Initialized hash operation. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription */ psa_status_t mbedtls_psa_hash_abort( mbedtls_psa_hash_operation_t *operation); diff --git a/library/psa_crypto_mac.h b/library/psa_crypto_mac.h index 21c4de636..4f8024a9e 100644 --- a/library/psa_crypto_mac.h +++ b/library/psa_crypto_mac.h @@ -52,8 +52,8 @@ * \p alg is not supported. * \retval #PSA_ERROR_BUFFER_TOO_SMALL * \p mac_size is too small - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription */ psa_status_t mbedtls_psa_mac_compute( const psa_key_attributes_t *attributes, @@ -89,8 +89,8 @@ psa_status_t mbedtls_psa_mac_compute( * Success. * \retval #PSA_ERROR_NOT_SUPPORTED * \p alg is not supported. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be inactive). */ @@ -124,8 +124,8 @@ psa_status_t mbedtls_psa_mac_sign_setup( * Success. * \retval #PSA_ERROR_NOT_SUPPORTED * \p alg is not supported. - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be inactive). */ @@ -158,8 +158,8 @@ psa_status_t mbedtls_psa_mac_verify_setup( * Success. * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be active). - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription */ psa_status_t mbedtls_psa_mac_update( mbedtls_psa_mac_operation_t *operation, @@ -200,8 +200,8 @@ psa_status_t mbedtls_psa_mac_update( * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p mac buffer is too small. A sufficient buffer size * can be determined by calling PSA_MAC_LENGTH(). - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription */ psa_status_t mbedtls_psa_mac_sign_finish( mbedtls_psa_mac_operation_t *operation, @@ -241,8 +241,8 @@ psa_status_t mbedtls_psa_mac_sign_finish( * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be an active mac verify * operation). - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription */ psa_status_t mbedtls_psa_mac_verify_finish( mbedtls_psa_mac_operation_t *operation, @@ -267,8 +267,8 @@ psa_status_t mbedtls_psa_mac_verify_finish( * * \param[in,out] operation Initialized MAC operation. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription */ psa_status_t mbedtls_psa_mac_abort( mbedtls_psa_mac_operation_t *operation); diff --git a/library/psa_crypto_rsa.h b/library/psa_crypto_rsa.h index cee2f524c..82ea4746d 100644 --- a/library/psa_crypto_rsa.h +++ b/library/psa_crypto_rsa.h @@ -61,9 +61,9 @@ psa_status_t mbedtls_psa_rsa_load_representation(psa_key_type_t type, * \retval #PSA_SUCCESS The RSA key was imported successfully. * \retval #PSA_ERROR_INVALID_ARGUMENT * The key data is not correctly formatted. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_CORRUPTION_DETECTED + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription */ psa_status_t mbedtls_psa_rsa_import_key( const psa_key_attributes_t *attributes, @@ -102,12 +102,12 @@ psa_status_t mbedtls_psa_rsa_export_key(psa_key_type_t type, * \p data. * * \retval #PSA_SUCCESS The RSA public key was exported successfully. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_HARDWARE_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription */ psa_status_t mbedtls_psa_rsa_export_public_key( const psa_key_attributes_t *attributes, @@ -158,17 +158,17 @@ psa_status_t mbedtls_psa_rsa_generate_key( * \param[out] signature_length On success, the number of bytes * that make up the returned signature value. * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p signature buffer is too small. You can * determine a sufficient buffer size by calling * #PSA_SIGN_OUTPUT_SIZE(\c PSA_KEY_TYPE_RSA_KEY_PAIR, \c key_bits, * \p alg) where \c key_bits is the bit-size of the RSA key. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INVALID_ARGUMENT - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription */ psa_status_t mbedtls_psa_rsa_sign_hash( const psa_key_attributes_t *attributes, @@ -202,9 +202,9 @@ psa_status_t mbedtls_psa_rsa_sign_hash( * \retval #PSA_ERROR_INVALID_SIGNATURE * The calculation was performed successfully, but the passed * signature is not a valid signature. - * \retval #PSA_ERROR_NOT_SUPPORTED - * \retval #PSA_ERROR_INVALID_ARGUMENT - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription */ psa_status_t mbedtls_psa_rsa_verify_hash( const psa_key_attributes_t *attributes, diff --git a/library/psa_crypto_slot_management.h b/library/psa_crypto_slot_management.h index ff8ccdeae..c8366abeb 100644 --- a/library/psa_crypto_slot_management.h +++ b/library/psa_crypto_slot_management.h @@ -88,9 +88,9 @@ static inline int psa_key_id_is_volatile(psa_key_id_t key_id) * due to a lack of empty key slot, or available memory. * \retval #PSA_ERROR_DOES_NOT_EXIST * There is no key with key identifier \p key. - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_DATA_CORRUPT + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription */ psa_status_t psa_get_and_lock_key_slot(mbedtls_svc_key_id_t key, psa_key_slot_t **p_slot); @@ -118,9 +118,9 @@ void psa_wipe_all_key_slots(void); * associated to the returned slot. * \param[out] p_slot On success, a pointer to the slot. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_BAD_STATE + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_BAD_STATE \emptydescription */ psa_status_t psa_get_empty_key_slot(psa_key_id_t *volatile_key_id, psa_key_slot_t **p_slot); @@ -195,8 +195,8 @@ static inline int psa_key_lifetime_is_external(psa_key_lifetime_t lifetime) * storage, returns a pointer to the driver table * associated with the key's storage location. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_INVALID_ARGUMENT + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription */ psa_status_t psa_validate_key_location(psa_key_lifetime_t lifetime, psa_se_drv_table_entry_t **p_drv); @@ -205,7 +205,7 @@ psa_status_t psa_validate_key_location(psa_key_lifetime_t lifetime, * * \param[in] lifetime The key lifetime attribute. * - * \retval #PSA_SUCCESS + * \retval #PSA_SUCCESS \emptydescription * \retval #PSA_ERROR_NOT_SUPPORTED The key is persistent but persistent keys * are not supported. */ diff --git a/library/psa_crypto_storage.c b/library/psa_crypto_storage.c index 037a32611..688940b5f 100644 --- a/library/psa_crypto_storage.c +++ b/library/psa_crypto_storage.c @@ -77,11 +77,11 @@ static psa_storage_uid_t psa_its_identifier_of_slot(mbedtls_svc_key_id_t key) * \param[out] data Buffer where the data is to be written. * \param data_size Size of the \c data buffer in bytes. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_DATA_INVALID - * \retval #PSA_ERROR_DATA_CORRUPT - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_DOES_NOT_EXIST + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_DATA_INVALID \emptydescription + * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_DOES_NOT_EXIST \emptydescription */ static psa_status_t psa_crypto_storage_load( const mbedtls_svc_key_id_t key, uint8_t *data, size_t data_size) @@ -129,11 +129,11 @@ int psa_is_key_present_in_storage(const mbedtls_svc_key_id_t key) * \param data_length The number of bytes * that make up the data. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_INSUFFICIENT_STORAGE - * \retval #PSA_ERROR_ALREADY_EXISTS - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_DATA_INVALID + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription + * \retval #PSA_ERROR_ALREADY_EXISTS \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_DATA_INVALID \emptydescription */ static psa_status_t psa_crypto_storage_store(const mbedtls_svc_key_id_t key, const uint8_t *data, @@ -203,10 +203,10 @@ psa_status_t psa_destroy_persistent_key(const mbedtls_svc_key_id_t key) * is to be obtained. * \param[out] data_length The number of bytes that make up the data. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_DOES_NOT_EXIST - * \retval #PSA_ERROR_DATA_CORRUPT + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_DOES_NOT_EXIST \emptydescription + * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription */ static psa_status_t psa_crypto_storage_get_data_length( const mbedtls_svc_key_id_t key, diff --git a/library/psa_crypto_storage.h b/library/psa_crypto_storage.h index 8e108c568..04768f8a4 100644 --- a/library/psa_crypto_storage.h +++ b/library/psa_crypto_storage.h @@ -96,14 +96,14 @@ int psa_is_key_present_in_storage(const mbedtls_svc_key_id_t key); * \param[in] data Buffer containing the key data. * \param data_length The number of bytes that make up the key data. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_INVALID_ARGUMENT - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_INSUFFICIENT_STORAGE - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_ALREADY_EXISTS - * \retval #PSA_ERROR_DATA_INVALID - * \retval #PSA_ERROR_DATA_CORRUPT + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_ALREADY_EXISTS \emptydescription + * \retval #PSA_ERROR_DATA_INVALID \emptydescription + * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription */ psa_status_t psa_save_persistent_key(const psa_core_key_attributes_t *attr, const uint8_t *data, @@ -129,11 +129,11 @@ psa_status_t psa_save_persistent_key(const psa_core_key_attributes_t *attr, * \param[out] data Pointer to an allocated key data buffer on return. * \param[out] data_length The number of bytes that make up the key data. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_DATA_INVALID - * \retval #PSA_ERROR_DATA_CORRUPT - * \retval #PSA_ERROR_DOES_NOT_EXIST + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_DATA_INVALID \emptydescription + * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription + * \retval #PSA_ERROR_DOES_NOT_EXIST \emptydescription */ psa_status_t psa_load_persistent_key(psa_core_key_attributes_t *attr, uint8_t **data, @@ -148,7 +148,7 @@ psa_status_t psa_load_persistent_key(psa_core_key_attributes_t *attr, * \retval #PSA_SUCCESS * The key was successfully removed, * or the key did not exist. - * \retval #PSA_ERROR_DATA_INVALID + * \retval #PSA_ERROR_DATA_INVALID \emptydescription */ psa_status_t psa_destroy_persistent_key(const mbedtls_svc_key_id_t key); @@ -190,9 +190,9 @@ void psa_format_key_data_for_storage(const uint8_t *data, * \param[out] attr On success, the attribute structure is filled * with the loaded key metadata. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_INSUFFICIENT_MEMORY - * \retval #PSA_ERROR_DATA_INVALID + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_DATA_INVALID \emptydescription */ psa_status_t psa_parse_key_data_from_storage(const uint8_t *storage_data, size_t storage_data_length, @@ -322,10 +322,10 @@ static inline void psa_crypto_prepare_transaction( * You may call this function multiple times during a transaction to * atomically update the transaction state. * - * \retval #PSA_SUCCESS - * \retval #PSA_ERROR_DATA_CORRUPT - * \retval #PSA_ERROR_INSUFFICIENT_STORAGE - * \retval #PSA_ERROR_STORAGE_FAILURE + * \retval #PSA_SUCCESS \emptydescription + * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription */ psa_status_t psa_crypto_save_transaction(void); @@ -339,9 +339,9 @@ psa_status_t psa_crypto_save_transaction(void); * #psa_crypto_transaction. * \retval #PSA_ERROR_DOES_NOT_EXIST * There is no ongoing transaction. - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_DATA_INVALID - * \retval #PSA_ERROR_DATA_CORRUPT + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_DATA_INVALID \emptydescription + * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription */ psa_status_t psa_crypto_load_transaction(void); @@ -380,8 +380,8 @@ psa_status_t psa_crypto_stop_transaction(void); * * \retval #PSA_SUCCESS * Success - * \retval #PSA_ERROR_STORAGE_FAILURE - * \retval #PSA_ERROR_INSUFFICIENT_STORAGE + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription * \retval #PSA_ERROR_NOT_PERMITTED * The entropy seed file already exists. */ From 44fe5ea532aa552614586861105572cfc166b726 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 14 Feb 2023 19:26:56 +0100 Subject: [PATCH 30/51] Changelog entry for pacifying clang -Wdocumentation about \retval Fixes #6960 Signed-off-by: Gilles Peskine --- ChangeLog.d/empty-retval-description.txt | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 ChangeLog.d/empty-retval-description.txt diff --git a/ChangeLog.d/empty-retval-description.txt b/ChangeLog.d/empty-retval-description.txt new file mode 100644 index 000000000..491adf55d --- /dev/null +++ b/ChangeLog.d/empty-retval-description.txt @@ -0,0 +1,3 @@ +Bugfix + * Silence warnings from clang -Wdocumentation about empty \retval + descriptions, which started appearing with Clang 15. Fixes #6960. From 4b86f531b7068e63f1755c4f1f09f6df39844ae1 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 21 Feb 2023 10:21:12 +0100 Subject: [PATCH 31/51] Improve documentation of documentation workaround Signed-off-by: Gilles Peskine --- doxygen/mbedtls.doxyfile | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile index 1ad5866a4..8804401a0 100644 --- a/doxygen/mbedtls.doxyfile +++ b/doxygen/mbedtls.doxyfile @@ -30,10 +30,13 @@ DOT_TRANSPARENT = YES # but clang -Wdocumentation doesn't (since Clang 15, for \retval). # https://github.com/Mbed-TLS/mbedtls/issues/6960 # https://github.com/llvm/llvm-project/issues/60315 -# As a workaround, when documenting the status codes that a function can -# return, if you don't have anything to say beyond the status code's -# description, you can write something like -# \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription +# We often use \retval declarations with just a constant name to +# document which error codes a function can return. If the documentation +# of the error code is enough to explain the error, then an empty +# description on the \retval statement is ok. However, the source code +# of the description needs to be made non-empty to pacify Clang. +# In such cases, you can write something like +# \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription # This does not change the documentation generated by Doxygen, but # it pacifies clang -Wdocumentation. ALIASES += emptydescription="" From 8377f3dec0dd992c04c9e103dc6794611958d875 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 23 Feb 2023 13:03:30 +0100 Subject: [PATCH 32/51] Further documentation improvements Signed-off-by: Gilles Peskine --- doxygen/mbedtls.doxyfile | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile index 8804401a0..6a590b3cc 100644 --- a/doxygen/mbedtls.doxyfile +++ b/doxygen/mbedtls.doxyfile @@ -26,17 +26,17 @@ DOT_GRAPH_MAX_NODES = 200 MAX_DOT_GRAPH_DEPTH = 1000 DOT_TRANSPARENT = YES -# Doxygen accepts empty descriptions for commands such as \retval, -# but clang -Wdocumentation doesn't (since Clang 15, for \retval). +# We mostly \retval declarations to document which error codes a function +# can return. The reader can follow the hyperlink to the definition of the +# constant to get the generic documentation of that error code. If we don't +# have anything to say about the specific error code for the specific +# function, we can leave the description part of the \retval command blank. +# This is perfectly valid as far as Doxygen is concerned. However, with +# Clang >=15, the -Wdocumentation option emits a warning for empty +# descriptions. # https://github.com/Mbed-TLS/mbedtls/issues/6960 # https://github.com/llvm/llvm-project/issues/60315 -# We often use \retval declarations with just a constant name to -# document which error codes a function can return. If the documentation -# of the error code is enough to explain the error, then an empty -# description on the \retval statement is ok. However, the source code -# of the description needs to be made non-empty to pacify Clang. -# In such cases, you can write something like +# As a workaround, you can write something like # \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription -# This does not change the documentation generated by Doxygen, but -# it pacifies clang -Wdocumentation. +# This avoids writing redundant text and keeps Clang happy. ALIASES += emptydescription="" From 809c3d50037f83d29d70370e8487b5eebd510311 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 23 Feb 2023 13:37:54 +0100 Subject: [PATCH 33/51] Words. Use them! Signed-off-by: Gilles Peskine --- doxygen/mbedtls.doxyfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile index 6a590b3cc..1f1a9cd24 100644 --- a/doxygen/mbedtls.doxyfile +++ b/doxygen/mbedtls.doxyfile @@ -26,7 +26,7 @@ DOT_GRAPH_MAX_NODES = 200 MAX_DOT_GRAPH_DEPTH = 1000 DOT_TRANSPARENT = YES -# We mostly \retval declarations to document which error codes a function +# We mostly use \retval declarations to document which error codes a function # can return. The reader can follow the hyperlink to the definition of the # constant to get the generic documentation of that error code. If we don't # have anything to say about the specific error code for the specific From d784833a1b83d26ea7bd3cc32d58e27d10d8f6cc Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 24 Feb 2023 12:08:01 +0100 Subject: [PATCH 34/51] Silence a warning from Clang >=15 about an unused local variable The assembly code uses t only on some architectures. Fixes #7166. Signed-off-by: Gilles Peskine --- ChangeLog.d/clang-15-bignum-warning.txt | 3 +++ library/bignum.c | 3 +-- 2 files changed, 4 insertions(+), 2 deletions(-) create mode 100644 ChangeLog.d/clang-15-bignum-warning.txt diff --git a/ChangeLog.d/clang-15-bignum-warning.txt b/ChangeLog.d/clang-15-bignum-warning.txt new file mode 100644 index 000000000..d3308b4c9 --- /dev/null +++ b/ChangeLog.d/clang-15-bignum-warning.txt @@ -0,0 +1,3 @@ +Bugfix + * Silence a warning about an unused local variable in bignum.c on + some architectures. Fixes #7166. diff --git a/library/bignum.c b/library/bignum.c index d915ade63..5dca3a917 100644 --- a/library/bignum.c +++ b/library/bignum.c @@ -1427,6 +1427,7 @@ void mpi_mul_hlp(size_t i, mbedtls_mpi_uint b) { mbedtls_mpi_uint c = 0, t = 0; + (void) t; /* Unused in some architectures */ #if defined(MULADDC_HUIT) for (; i >= 8; i -= 8) { @@ -1472,8 +1473,6 @@ void mpi_mul_hlp(size_t i, } #endif /* MULADDC_HUIT */ - t++; - while (c != 0) { *d += c; c = (*d < c); d++; } From 6e9385b83244cb4b814d9abeed5a990e1344aa99 Mon Sep 17 00:00:00 2001 From: Andrzej Kurek Date: Fri, 24 Feb 2023 07:44:57 -0500 Subject: [PATCH 35/51] Reduce the default MBEDTLS_ECP_WINDOW_SIZE value to 2 As tested in https://github.com/Mbed-TLS/mbedtls/issues/6790, after introducing side-channel counter-measures to bignum, the performance of RSA decryption in correlation to the MBEDTLS_ECP_WINDOW_SIZE has changed. The default value of 2 has been chosen as it provides best or close-to-best results for tests on Cortex-M4 and Intel i7. Signed-off-by: Andrzej Kurek --- ChangeLog.d/mpi-window-perf | 7 +++++++ include/mbedtls/bignum.h | 4 ++-- include/mbedtls/config.h | 2 +- 3 files changed, 10 insertions(+), 3 deletions(-) create mode 100644 ChangeLog.d/mpi-window-perf diff --git a/ChangeLog.d/mpi-window-perf b/ChangeLog.d/mpi-window-perf new file mode 100644 index 000000000..0f75d6af1 --- /dev/null +++ b/ChangeLog.d/mpi-window-perf @@ -0,0 +1,7 @@ +Changes + * Changed the default MBEDTLS_ECP_WINDOW_SIZE from 6 to 2. + As tested in issue 6790, the correlation between this define and + RSA decryption performance has changed lately due to security fixes. + To fix the performance degradation when using default values the + window was reduced from 6 to 2, a value that gives the best or close + to best results when tested on Cortex-M4 and Intel i7. diff --git a/include/mbedtls/bignum.h b/include/mbedtls/bignum.h index d706a2c4c..788ea21a8 100644 --- a/include/mbedtls/bignum.h +++ b/include/mbedtls/bignum.h @@ -66,7 +66,7 @@ #if !defined(MBEDTLS_MPI_WINDOW_SIZE) /* - * Maximum window size used for modular exponentiation. Default: 6 + * Maximum window size used for modular exponentiation. Default: 2 * Minimum value: 1. Maximum value: 6. * * Result is an array of ( 2 ** MBEDTLS_MPI_WINDOW_SIZE ) MPIs used @@ -74,7 +74,7 @@ * * Reduction in size, reduces speed. */ -#define MBEDTLS_MPI_WINDOW_SIZE 6 /**< Maximum window size used. */ +#define MBEDTLS_MPI_WINDOW_SIZE 2 /**< Maximum window size used. */ #endif /* !MBEDTLS_MPI_WINDOW_SIZE */ #if !defined(MBEDTLS_MPI_MAX_SIZE) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index 5dcbdd1dd..1e4d95e0c 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -3749,7 +3749,7 @@ * comment in the specific module. */ /* MPI / BIGNUM options */ -//#define MBEDTLS_MPI_WINDOW_SIZE 6 /**< Maximum window size used. */ +//#define MBEDTLS_MPI_WINDOW_SIZE 2 /**< Maximum window size used. */ //#define MBEDTLS_MPI_MAX_SIZE 1024 /**< Maximum number of bytes for usable MPIs. */ /* CTR_DRBG options */ From 272cc19ab5dcf8a7dc1fc80323e1f4348512c544 Mon Sep 17 00:00:00 2001 From: Ashley Duncan Date: Fri, 11 Feb 2022 09:57:18 +1300 Subject: [PATCH 36/51] Fixed undefined behavior in ssl_read if buf parameter is NULL. Signed-off-by: Ashley Duncan --- library/ssl_msg.c | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/library/ssl_msg.c b/library/ssl_msg.c index a38e76440..8d35c9c00 100644 --- a/library/ssl_msg.c +++ b/library/ssl_msg.c @@ -5429,8 +5429,10 @@ int mbedtls_ssl_read(mbedtls_ssl_context *ssl, unsigned char *buf, size_t len) n = (len < ssl->in_msglen) ? len : ssl->in_msglen; - memcpy(buf, ssl->in_offt, n); - ssl->in_msglen -= n; + if (buf) { + memcpy(buf, ssl->in_offt, n); + ssl->in_msglen -= n; + } /* Zeroising the plaintext buffer to erase unused application data from the memory. */ From cf01d78e7ef546b934b0727da3ea372efe3ce94b Mon Sep 17 00:00:00 2001 From: ashesman Date: Thu, 17 Feb 2022 11:08:27 +1300 Subject: [PATCH 37/51] Update library/ssl_msg.c Co-authored-by: Gilles Peskine Signed-off-by: Dave Rodgman --- library/ssl_msg.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/ssl_msg.c b/library/ssl_msg.c index 8d35c9c00..db0299eda 100644 --- a/library/ssl_msg.c +++ b/library/ssl_msg.c @@ -5429,7 +5429,7 @@ int mbedtls_ssl_read(mbedtls_ssl_context *ssl, unsigned char *buf, size_t len) n = (len < ssl->in_msglen) ? len : ssl->in_msglen; - if (buf) { + if (len != 0) { memcpy(buf, ssl->in_offt, n); ssl->in_msglen -= n; } From 13938b84e95c5508f497ebfcc831901b3a355d00 Mon Sep 17 00:00:00 2001 From: Ashley Duncan Date: Thu, 17 Feb 2022 11:10:33 +1300 Subject: [PATCH 38/51] Added changelog entry. Signed-off-by: Ashley Duncan --- ChangeLog.d/mbedtls_ssl_read_undefined_behavior.txt | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 ChangeLog.d/mbedtls_ssl_read_undefined_behavior.txt diff --git a/ChangeLog.d/mbedtls_ssl_read_undefined_behavior.txt b/ChangeLog.d/mbedtls_ssl_read_undefined_behavior.txt new file mode 100644 index 000000000..392a91b72 --- /dev/null +++ b/ChangeLog.d/mbedtls_ssl_read_undefined_behavior.txt @@ -0,0 +1,2 @@ +Bugfix + * Fixed undefined behavior in mbedtls_ssl_read if len argument is 0 From 1215557e91e551031d89cb89e235ec3483ac7a91 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Fri, 24 Feb 2023 15:41:34 +0000 Subject: [PATCH 39/51] Add corresponding fix for mbedtls_ssl_write Signed-off-by: Dave Rodgman --- library/ssl_msg.c | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/library/ssl_msg.c b/library/ssl_msg.c index db0299eda..8a2ab7b9b 100644 --- a/library/ssl_msg.c +++ b/library/ssl_msg.c @@ -5508,7 +5508,9 @@ static int ssl_write_real(mbedtls_ssl_context *ssl, */ ssl->out_msglen = len; ssl->out_msgtype = MBEDTLS_SSL_MSG_APPLICATION_DATA; - memcpy(ssl->out_msg, buf, len); + if (len > 0) { + memcpy(ssl->out_msg, buf, len); + } if ((ret = mbedtls_ssl_write_record(ssl, SSL_FORCE_FLUSH)) != 0) { MBEDTLS_SSL_DEBUG_RET(1, "mbedtls_ssl_write_record", ret); From fb07c37cb101798d004191372aa1ccd573feed1b Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Fri, 24 Feb 2023 15:43:43 +0000 Subject: [PATCH 40/51] Improve changelog Signed-off-by: Dave Rodgman --- ChangeLog.d/mbedtls_ssl_read_undefined_behavior.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/ChangeLog.d/mbedtls_ssl_read_undefined_behavior.txt b/ChangeLog.d/mbedtls_ssl_read_undefined_behavior.txt index 392a91b72..1f2c563be 100644 --- a/ChangeLog.d/mbedtls_ssl_read_undefined_behavior.txt +++ b/ChangeLog.d/mbedtls_ssl_read_undefined_behavior.txt @@ -1,2 +1,3 @@ Bugfix - * Fixed undefined behavior in mbedtls_ssl_read if len argument is 0 + * Fix undefined behavior in mbedtls_ssl_read() and mbedtls_ssl_write() if + len argument is 0 and buffer is NULL. From cd09d68eb1de3493c74ba72d5d69d6ab9a8bd9c4 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Fri, 24 Feb 2023 15:41:55 +0000 Subject: [PATCH 41/51] Add tests Signed-off-by: Dave Rodgman --- tests/suites/test_suite_ssl.function | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/tests/suites/test_suite_ssl.function b/tests/suites/test_suite_ssl.function index 1dec18d38..39825ed96 100644 --- a/tests/suites/test_suite_ssl.function +++ b/tests/suites/test_suite_ssl.function @@ -1052,6 +1052,12 @@ int mbedtls_ssl_write_fragment(mbedtls_ssl_context *ssl, unsigned char *buf, int buf_len, int *written, const int expected_fragments) { + /* Verify that calling mbedtls_ssl_write with a NULL buffer and zero length is + * a valid no-op for TLS connections. */ + if (ssl->conf->transport != MBEDTLS_SSL_TRANSPORT_DATAGRAM) { + TEST_ASSERT(mbedtls_ssl_write(ssl, NULL, 0) == 0); + } + int ret = mbedtls_ssl_write(ssl, buf + *written, buf_len - *written); if (ret > 0) { *written += ret; @@ -1090,6 +1096,12 @@ int mbedtls_ssl_read_fragment(mbedtls_ssl_context *ssl, unsigned char *buf, int buf_len, int *read, int *fragments, const int expected_fragments) { + /* Verify that calling mbedtls_ssl_write with a NULL buffer and zero length is + * a valid no-op for TLS connections. */ + if (ssl->conf->transport != MBEDTLS_SSL_TRANSPORT_DATAGRAM) { + TEST_ASSERT(mbedtls_ssl_read(ssl, NULL, 0) == 0); + } + int ret = mbedtls_ssl_read(ssl, buf + *read, buf_len - *read); if (ret > 0) { (*fragments)++; From 8a23f49ebc79c98082926ca2d17f96e62f3f5b12 Mon Sep 17 00:00:00 2001 From: oberon-sk Date: Mon, 13 Feb 2023 13:42:02 +0100 Subject: [PATCH 42/51] asymmetric_encrypt: check output length only if return code is PSA_SUCCESS. Signed-off-by: Stephan Koch Signed-off-by: Dave Rodgman --- tests/suites/test_suite_psa_crypto.function | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/tests/suites/test_suite_psa_crypto.function b/tests/suites/test_suite_psa_crypto.function index 214096c09..a96bcf7c2 100644 --- a/tests/suites/test_suite_psa_crypto.function +++ b/tests/suites/test_suite_psa_crypto.function @@ -4173,7 +4173,9 @@ void asymmetric_encrypt(int key_type_arg, output, output_size, &output_length); TEST_EQUAL(actual_status, expected_status); - TEST_EQUAL(output_length, expected_output_length); + if (actual_status == PSA_SUCCESS) { + TEST_EQUAL(output_length, expected_output_length); + } /* If the label is empty, the test framework puts a non-null pointer * in label->x. Test that a null pointer works as well. */ @@ -4188,7 +4190,9 @@ void asymmetric_encrypt(int key_type_arg, output, output_size, &output_length); TEST_EQUAL(actual_status, expected_status); - TEST_EQUAL(output_length, expected_output_length); + if (actual_status == PSA_SUCCESS) { + TEST_EQUAL(output_length, expected_output_length); + } } exit: From 6ed143635d0a91c79c21ec1d762e7e7d6aae20f5 Mon Sep 17 00:00:00 2001 From: Stephan Koch Date: Wed, 22 Feb 2023 13:39:21 +0100 Subject: [PATCH 43/51] Feedback from Arm: guarantee that output_length <= output_size even on error, to reduce the risk that a missing error check escalates into a buffer overflow in the application code Signed-off-by: Stephan Koch Signed-off-by: Dave Rodgman --- tests/suites/test_suite_psa_crypto.function | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/tests/suites/test_suite_psa_crypto.function b/tests/suites/test_suite_psa_crypto.function index a96bcf7c2..5bd7b36e5 100644 --- a/tests/suites/test_suite_psa_crypto.function +++ b/tests/suites/test_suite_psa_crypto.function @@ -4175,6 +4175,8 @@ void asymmetric_encrypt(int key_type_arg, TEST_EQUAL(actual_status, expected_status); if (actual_status == PSA_SUCCESS) { TEST_EQUAL(output_length, expected_output_length); + } else { + TEST_LE_U(output_length, output_size); } /* If the label is empty, the test framework puts a non-null pointer @@ -4192,6 +4194,8 @@ void asymmetric_encrypt(int key_type_arg, TEST_EQUAL(actual_status, expected_status); if (actual_status == PSA_SUCCESS) { TEST_EQUAL(output_length, expected_output_length); + } else { + TEST_LE_U(output_length, output_size); } } From 6cda3d3b5b0212390afe25f3b0dce8ae17b7804f Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Thu, 2 Mar 2023 13:39:04 +0000 Subject: [PATCH 44/51] Enable -Werror for armclang Signed-off-by: Dave Rodgman --- tests/scripts/all.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/scripts/all.sh b/tests/scripts/all.sh index 1490bd057..2da9fe20f 100755 --- a/tests/scripts/all.sh +++ b/tests/scripts/all.sh @@ -376,7 +376,7 @@ armc6_build_test() msg "build: ARM Compiler 6 ($FLAGS)" ARM_TOOL_VARIANT="ult" CC="$ARMC6_CC" AR="$ARMC6_AR" CFLAGS="$FLAGS" \ - WARNING_CFLAGS='-xc -std=c99' make lib + WARNING_CFLAGS='-Werror -xc -std=c99' make lib msg "size: ARM Compiler 6 ($FLAGS)" "$ARMC6_FROMELF" -z library/*.o From a19ce12e4700615ebdd5f2a7ad1dcc31d744370f Mon Sep 17 00:00:00 2001 From: Pengyu Lv Date: Fri, 24 Feb 2023 15:38:52 +0800 Subject: [PATCH 45/51] all.sh: Skip build_mingw correctly If i686-w64-mingw32-gcc is not installed, then build_mingw should be unsupported. Signed-off-by: Pengyu Lv --- tests/scripts/all.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/scripts/all.sh b/tests/scripts/all.sh index 2da9fe20f..22018ebe4 100755 --- a/tests/scripts/all.sh +++ b/tests/scripts/all.sh @@ -3211,8 +3211,8 @@ component_build_mingw () { make WINDOWS_BUILD=1 clean } support_build_mingw() { - case $(i686-w64-mingw32-gcc -dumpversion) in - [0-5]*) false;; + case $(i686-w64-mingw32-gcc -dumpversion 2>/dev/null) in + [0-5]*|"") false;; *) true;; esac } From d216c0411d80552d599530596e3d8dc7481c250b Mon Sep 17 00:00:00 2001 From: Pengyu Lv Date: Fri, 3 Mar 2023 18:23:35 +0800 Subject: [PATCH 46/51] all.sh: add support function for build_armcc With this change, "--list-components" will not list "build_armcc" on the system which is not installed with Arm Compilers. Signed-off-by: Pengyu Lv --- tests/scripts/all.sh | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/tests/scripts/all.sh b/tests/scripts/all.sh index 22018ebe4..87defc0ce 100755 --- a/tests/scripts/all.sh +++ b/tests/scripts/all.sh @@ -3181,6 +3181,11 @@ component_build_armcc () { # ARM Compiler 6 - Target ARMv8-A - AArch64 armc6_build_test "--target=aarch64-arm-none-eabi -march=armv8.2-a" } +support_build_armcc () { + armc5_cc="$ARMC5_BIN_DIR/armcc" + armc6_cc="$ARMC6_BIN_DIR/armclang" + (check_tools "$armc5_cc" "$armc6_cc" > /dev/null 2>&1) +} component_build_ssl_hw_record_accel() { msg "build: default config with MBEDTLS_SSL_HW_RECORD_ACCEL enabled" From 601e8394168d6ee4173e4ab4c7503bd07ce445dc Mon Sep 17 00:00:00 2001 From: Tom Cosgrove Date: Tue, 7 Mar 2023 11:43:12 +0000 Subject: [PATCH 47/51] Fix typos Signed-off-by: Tom Cosgrove --- include/mbedtls/config.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index 1e4d95e0c..acdb7acb3 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -871,7 +871,7 @@ * - Changes the behaviour of TLS 1.2 clients (not servers) when using the * ECDHE-ECDSA key exchange (not other key exchanges) to make all ECC * computations restartable: - * - ECDH operations from the key exchange, only for Short Weierstass + * - ECDH operations from the key exchange, only for Short Weierstrass * curves; * - verification of the server's key exchange signature; * - verification of the server's certificate chain; From 07ae208f12523d4fcd720a679609a02da7d86abc Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 7 Mar 2023 20:22:51 +0100 Subject: [PATCH 48/51] Document the need to call psa_crypto_init() with USE_PSA_CRYPTO When MBEDTLS_USE_PSA_CRYPTO is enabled, the application must call psa_crypto_init() before directly or indirectly calling cipher or PK code that will use PSA under the hood. Document this explicitly for some functions. To avoid clutter, this commit only documents the need to call psa_crypto_init() in common, non-obvious cases: using a PK object that was not constructed using PSA, X.509 processing, or setting up an SSL context. Functions that are normally only called after such a function (for example, using a cipher or PK context constructed from a PSA key), or where the need for PSA is obvious because they take a key ID as argument, do not need more explicit documentaion. Signed-off-by: Gilles Peskine --- include/mbedtls/pk.h | 5 +++++ include/mbedtls/ssl.h | 8 ++++++++ include/mbedtls/x509_crl.h | 12 ++++++++++++ include/mbedtls/x509_crt.h | 20 ++++++++++++++++++++ include/mbedtls/x509_csr.h | 8 ++++++++ 5 files changed, 53 insertions(+) diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h index a226e7173..ec8355136 100644 --- a/include/mbedtls/pk.h +++ b/include/mbedtls/pk.h @@ -402,6 +402,11 @@ int mbedtls_pk_can_do(const mbedtls_pk_context *ctx, mbedtls_pk_type_t type); * Use \c mbedtls_pk_verify_ext( MBEDTLS_PK_RSASSA_PSS, ... ) * to verify RSASSA_PSS signatures. * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function, + * if the key might be an ECC (ECDSA) key. + * * \note If hash_len is 0, then the length associated with md_alg * is used instead, or an error returned if it is invalid. * diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index 7836ecec6..26e4ec400 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -1544,6 +1544,10 @@ void mbedtls_ssl_init(mbedtls_ssl_context *ssl); * Calling mbedtls_ssl_setup again is not supported, even * if no session is active. * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param ssl SSL context * \param conf SSL configuration to use * @@ -3980,6 +3984,10 @@ int mbedtls_ssl_get_session(const mbedtls_ssl_context *ssl, mbedtls_ssl_session * in which case the datagram of the underlying transport that is * currently being processed might or might not contain further * DTLS records. + * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. */ int mbedtls_ssl_handshake(mbedtls_ssl_context *ssl); diff --git a/include/mbedtls/x509_crl.h b/include/mbedtls/x509_crl.h index 895eca0d6..140502140 100644 --- a/include/mbedtls/x509_crl.h +++ b/include/mbedtls/x509_crl.h @@ -95,6 +95,10 @@ mbedtls_x509_crl; /** * \brief Parse a DER-encoded CRL and append it to the chained list * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param chain points to the start of the chain * \param buf buffer holding the CRL data in DER format * \param buflen size of the buffer @@ -109,6 +113,10 @@ int mbedtls_x509_crl_parse_der(mbedtls_x509_crl *chain, * * \note Multiple CRLs are accepted only if using PEM format * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param chain points to the start of the chain * \param buf buffer holding the CRL data in PEM or DER format * \param buflen size of the buffer @@ -124,6 +132,10 @@ int mbedtls_x509_crl_parse(mbedtls_x509_crl *chain, const unsigned char *buf, si * * \note Multiple CRLs are accepted only if using PEM format * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param chain points to the start of the chain * \param path filename to read the CRLs from (in PEM or DER encoding) * diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h index 235e00c06..466611f79 100644 --- a/include/mbedtls/x509_crt.h +++ b/include/mbedtls/x509_crt.h @@ -283,6 +283,10 @@ extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_suiteb; * \brief Parse a single DER formatted certificate and add it * to the end of the provided chained list. * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param chain The pointer to the start of the CRT chain to attach to. * When parsing the first CRT in a chain, this should point * to an instance of ::mbedtls_x509_crt initialized through @@ -344,6 +348,10 @@ typedef int (*mbedtls_x509_crt_ext_cb_t)(void *p_ctx, * \brief Parse a single DER formatted certificate and add it * to the end of the provided chained list. * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param chain The pointer to the start of the CRT chain to attach to. * When parsing the first CRT in a chain, this should point * to an instance of ::mbedtls_x509_crt initialized through @@ -394,6 +402,10 @@ int mbedtls_x509_crt_parse_der_with_ext_cb(mbedtls_x509_crt *chain, * temporary ownership of the CRT buffer until the CRT * is destroyed. * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param chain The pointer to the start of the CRT chain to attach to. * When parsing the first CRT in a chain, this should point * to an instance of ::mbedtls_x509_crt initialized through @@ -434,6 +446,10 @@ int mbedtls_x509_crt_parse_der_nocopy(mbedtls_x509_crt *chain, * long as the certificates are enclosed in the PEM specific * '-----{BEGIN/END} CERTIFICATE-----' delimiters. * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param chain The chain to which to add the parsed certificates. * \param buf The buffer holding the certificate data in PEM or DER format. * For certificates in PEM encoding, this may be a concatenation @@ -458,6 +474,10 @@ int mbedtls_x509_crt_parse(mbedtls_x509_crt *chain, const unsigned char *buf, si * of failed certificates it encountered. If none complete * correctly, the first error is returned. * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param chain points to the start of the chain * \param path filename to read the certificates from * diff --git a/include/mbedtls/x509_csr.h b/include/mbedtls/x509_csr.h index fa7ef04a2..5975584da 100644 --- a/include/mbedtls/x509_csr.h +++ b/include/mbedtls/x509_csr.h @@ -82,6 +82,10 @@ mbedtls_x509write_csr; * * \note CSR attributes (if any) are currently silently ignored. * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param csr CSR context to fill * \param buf buffer holding the CRL data * \param buflen size of the buffer @@ -96,6 +100,10 @@ int mbedtls_x509_csr_parse_der(mbedtls_x509_csr *csr, * * \note See notes for \c mbedtls_x509_csr_parse_der() * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param csr CSR context to fill * \param buf buffer holding the CRL data * \param buflen size of the buffer From fc09b75023f407ba4d02da6778cd935f86dd34ff Mon Sep 17 00:00:00 2001 From: Tom Cosgrove Date: Wed, 8 Mar 2023 15:58:47 +0000 Subject: [PATCH 49/51] Update ChangeLog to make "fix" explicit Signed-off-by: Tom Cosgrove --- ChangeLog | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/ChangeLog b/ChangeLog index 3673f5da5..23be7dd02 100644 --- a/ChangeLog +++ b/ChangeLog @@ -6,11 +6,11 @@ Security * Fix potential heap buffer overread and overwrite in DTLS if MBEDTLS_SSL_DTLS_CONNECTION_ID is enabled and MBEDTLS_SSL_CID_IN_LEN_MAX > 2 * MBEDTLS_SSL_CID_OUT_LEN_MAX. - * An adversary with access to precise enough information about memory - accesses (typically, an untrusted operating system attacking a secure - enclave) could recover an RSA private key after observing the victim - performing a single private-key operation if the window size used for the - exponentiation was 3 or smaller. Found and reported by Zili KOU, + * Fix an issue where an adversary with access to precise enough information + about memory accesses (typically, an untrusted operating system attacking + a secure enclave) could recover an RSA private key after observing the + victim performing a single private-key operation if the window size used + for the exponentiation was 3 or smaller. Found and reported by Zili KOU, Wenjian HE, Sharad Sinha, and Wei ZHANG. See "Cache Side-channel Attacks and Defenses of the Sliding Window Algorithm in TEEs" - Design, Automation and Test in Europe 2023. @@ -337,16 +337,17 @@ Security * It was possible to configure MBEDTLS_ECP_MAX_BITS to a value that is too small, leading to buffer overflows in ECC operations. Fail the build in such a case. - * An adversary with access to precise enough information about memory - accesses (typically, an untrusted operating system attacking a secure - enclave) could recover an RSA private key after observing the victim - performing a single private-key operation. Found and reported by + * Fix an issue where an adversary with access to precise enough information + about memory accesses (typically, an untrusted operating system attacking + a secure enclave) could recover an RSA private key after observing the + victim performing a single private-key operation. Found and reported by Zili KOU, Wenjian HE, Sharad Sinha, and Wei ZHANG. - * An adversary with access to precise enough timing information (typically, a - co-located process) could recover a Curve25519 or Curve448 static ECDH key - after inputting a chosen public key and observing the victim performing the - corresponding private-key operation. Found and reported by Leila Batina, - Lukas Chmielewski, Björn Haase, Niels Samwel and Peter Schwabe. + * Fix an issue where an adversary with access to precise enough timing + information (typically, a co-located process) could recover a Curve25519 + or Curve448 static ECDH key after inputting a chosen public key and + observing the victim performing the corresponding private-key operation. + Found and reported by Leila Batina, Lukas Chmielewski, Björn Haase, Niels + Samwel and Peter Schwabe. Bugfix * Add printf function attributes to mbedtls_debug_print_msg to ensure we From 29216d21e75558b4218aec5793446b1fad226ed7 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Thu, 9 Mar 2023 09:52:13 +0000 Subject: [PATCH 50/51] Move docs/getting_started.md to docs repo Delete docs/getting_started.md as it has been moved to the dedicated documentation repo. Signed-off-by: David Horstmann --- docs/getting_started.md | 962 ---------------------------------------- 1 file changed, 962 deletions(-) delete mode 100644 docs/getting_started.md diff --git a/docs/getting_started.md b/docs/getting_started.md deleted file mode 100644 index 507afa163..000000000 --- a/docs/getting_started.md +++ /dev/null @@ -1,962 +0,0 @@ -## Getting started with Mbed TLS - -### What is Mbed TLS? - -Mbed TLS is an open source cryptographic library that supports a wide range of -cryptographic operations, including: -* Key management -* Hashing -* Symmetric cryptography -* Asymmetric cryptography -* Message authentication (MAC) -* Key generation and derivation -* Authenticated encryption with associated data (AEAD) - -Mbed TLS provides a reference implementation of the cryptography interface of -the Arm Platform Security Architecture (PSA). It is written in portable C. - -Mbed TLS is distributed under the Apache License, version 2.0. - -#### Platform Security Architecture (PSA) - -Arm's Platform Security Architecture (PSA) is a holistic set of threat models, -security analyses, hardware and firmware architecture specifications, and an -open source firmware reference implementation. PSA provides a recipe, based on -industry best practice, that enables you to design security into both hardware -and firmware consistently. Part of the API provided by PSA is the cryptography -interface, which provides access to a set of primitives. - -### Using Mbed TLS - -* [Getting the Mbed TLS library](#getting-the-mbed-tls-library) -* [Building the Mbed TLS library](#building-the-mbed-tls-library) -* [Using the PSA Crypto API](#using-the-psa-crypto-api) -* [Importing a key](#importing-a-key) -* [Signing a message using RSA](#signing-a-message-using-RSA) -* [Encrypting or decrypting using symmetric ciphers](#encrypting-or-decrypting-using-symmetric-ciphers) -* [Hashing a message](#hashing-a-message) -* [Deriving a new key from an existing key](#deriving-a-new-key-from-an-existing-key) -* [Generating a random value](#generating-a-random-value) -* [Authenticating and encrypting or decrypting a message](#authenticating-and-encrypting-or-decrypting-a-message) -* [Generating and exporting keys](#generating-and-exporting-keys) -* [More about the PSA Crypto API](#more-about-the-psa-crypto-api) - -### Getting the Mbed TLS library - -Mbed TLS releases are available in the [public GitHub repository](https://github.com/Mbed-TLS/mbedtls). - -### Building the Mbed TLS library - -**Prerequisites to building the library with the provided makefiles:** -* GNU Make. -* A C toolchain (compiler, linker, archiver) that supports C99. -* Python 3.6 to generate the test code. -* Perl to run the tests. - -If you have a C compiler such as GCC or Clang, just run `make` in the top-level -directory to build the library, a set of unit tests and some sample programs. - -To select a different compiler, set the `CC` variable to the name or path of the -compiler and linker (default: `cc`) and set `AR` to a compatible archiver -(default: `ar`); for example: -``` -make CC=arm-linux-gnueabi-gcc AR=arm-linux-gnueabi-ar -``` -The provided makefiles pass options to the compiler that assume a GCC-like -command line syntax. To use a different compiler, you may need to pass different -values for `CFLAGS`, `WARNINGS_CFLAGS` and `LDFLAGS`. - -To run the unit tests on the host machine, run `make test` from the top-level -directory. If you are cross-compiling, copy the test executable from the `tests` -directory to the target machine. - -### Using the PSA Crypto API - -If using PSA Crypto, you must initialize the library by calling -`psa_crypto_init()` before any other PSA API. - -### Importing a key - -To use a key for cryptography operations in PSA, you need to first -import it. The import operation returns the identifier of the key for use -with other function calls. - -**Prerequisites to importing keys:** -* Initialize the library with a successful call to `psa_crypto_init()`. - -This example shows how to import a key: -```C -void import_a_key(const uint8_t *key, size_t key_len) -{ - psa_status_t status; - psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT; - psa_key_id_t key_id; - - printf("Import an AES key...\t"); - fflush(stdout); - - /* Initialize PSA Crypto */ - status = psa_crypto_init(); - if (status != PSA_SUCCESS) { - printf("Failed to initialize PSA Crypto\n"); - return; - } - - /* Set key attributes */ - psa_set_key_usage_flags(&attributes, 0); - psa_set_key_algorithm(&attributes, 0); - psa_set_key_type(&attributes, PSA_KEY_TYPE_AES); - psa_set_key_bits(&attributes, 128); - - /* Import the key */ - status = psa_import_key(&attributes, key, key_len, &key_id); - if (status != PSA_SUCCESS) { - printf("Failed to import key\n"); - return; - } - printf("Imported a key\n"); - - /* Free the attributes */ - psa_reset_key_attributes(&attributes); - - /* Destroy the key */ - psa_destroy_key(key_id); - - mbedtls_psa_crypto_free(); -} -``` - -### Signing a message using RSA - -The PSA Crypto API supports encrypting, decrypting, signing and verifying -messages using public key signature algorithms, such as RSA or ECDSA. - -**Prerequisites to performing asymmetric signature operations:** -* Initialize the library with a successful call to `psa_crypto_init()`. -* Have a valid key with appropriate attributes set: - * Usage flag `PSA_KEY_USAGE_SIGN_HASH` to allow signing. - * Usage flag `PSA_KEY_USAGE_VERIFY_HASH` to allow signature verification. - * Algorithm set to the desired signature algorithm. - -This example shows how to sign a hash that has already been calculated: -```C -void sign_a_message_using_rsa(const uint8_t *key, size_t key_len) -{ - psa_status_t status; - psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT; - uint8_t hash[32] = {0x50, 0xd8, 0x58, 0xe0, 0x98, 0x5e, 0xcc, 0x7f, - 0x60, 0x41, 0x8a, 0xaf, 0x0c, 0xc5, 0xab, 0x58, - 0x7f, 0x42, 0xc2, 0x57, 0x0a, 0x88, 0x40, 0x95, - 0xa9, 0xe8, 0xcc, 0xac, 0xd0, 0xf6, 0x54, 0x5c}; - uint8_t signature[PSA_SIGNATURE_MAX_SIZE] = {0}; - size_t signature_length; - psa_key_id_t key_id; - - printf("Sign a message...\t"); - fflush(stdout); - - /* Initialize PSA Crypto */ - status = psa_crypto_init(); - if (status != PSA_SUCCESS) { - printf("Failed to initialize PSA Crypto\n"); - return; - } - - /* Set key attributes */ - psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_SIGN_HASH); - psa_set_key_algorithm(&attributes, PSA_ALG_RSA_PKCS1V15_SIGN_RAW); - psa_set_key_type(&attributes, PSA_KEY_TYPE_RSA_KEY_PAIR); - psa_set_key_bits(&attributes, 1024); - - /* Import the key */ - status = psa_import_key(&attributes, key, key_len, &key_id); - if (status != PSA_SUCCESS) { - printf("Failed to import key\n"); - return; - } - - /* Sign message using the key */ - status = psa_sign_hash(key_id, PSA_ALG_RSA_PKCS1V15_SIGN_RAW, - hash, sizeof(hash), - signature, sizeof(signature), - &signature_length); - if (status != PSA_SUCCESS) { - printf("Failed to sign\n"); - return; - } - - printf("Signed a message\n"); - - /* Free the attributes */ - psa_reset_key_attributes(&attributes); - - /* Destroy the key */ - psa_destroy_key(key_id); - - mbedtls_psa_crypto_free(); -} -``` - -### Using symmetric ciphers - -The PSA Crypto API supports encrypting and decrypting messages using various -symmetric cipher algorithms (both block and stream ciphers). - -**Prerequisites to working with the symmetric cipher API:** -* Initialize the library with a successful call to `psa_crypto_init()`. -* Have a symmetric key. This key's usage flags must include - `PSA_KEY_USAGE_ENCRYPT` to allow encryption or `PSA_KEY_USAGE_DECRYPT` to - allow decryption. - -**To encrypt a message with a symmetric cipher:** -1. Allocate an operation (`psa_cipher_operation_t`) structure to pass to the - cipher functions. -1. Initialize the operation structure to zero or to `PSA_CIPHER_OPERATION_INIT`. -1. Call `psa_cipher_encrypt_setup()` to specify the algorithm and the key to be - used. -1. Call either `psa_cipher_generate_iv()` or `psa_cipher_set_iv()` to generate - or set the initialization vector (IV). We recommend calling - `psa_cipher_generate_iv()`, unless you require a specific IV value. -1. Call `psa_cipher_update()` with the message to encrypt. You may call this - function multiple times, passing successive fragments of the message on - successive calls. -1. Call `psa_cipher_finish()` to end the operation and output the encrypted - message. - -This example shows how to encrypt data using an AES (Advanced Encryption -Standard) key in CBC (Cipher Block Chaining) mode with no padding (assuming all -prerequisites have been fulfilled): -```c -void encrypt_with_symmetric_ciphers(const uint8_t *key, size_t key_len) -{ - enum { - block_size = PSA_BLOCK_CIPHER_BLOCK_LENGTH(PSA_KEY_TYPE_AES), - }; - psa_status_t status; - psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT; - psa_algorithm_t alg = PSA_ALG_CBC_NO_PADDING; - uint8_t plaintext[block_size] = SOME_PLAINTEXT; - uint8_t iv[block_size]; - size_t iv_len; - uint8_t output[block_size]; - size_t output_len; - psa_key_id_t key_id; - psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT; - - printf("Encrypt with cipher...\t"); - fflush(stdout); - - /* Initialize PSA Crypto */ - status = psa_crypto_init(); - if (status != PSA_SUCCESS) - { - printf("Failed to initialize PSA Crypto\n"); - return; - } - - /* Import a key */ - psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_ENCRYPT); - psa_set_key_algorithm(&attributes, alg); - psa_set_key_type(&attributes, PSA_KEY_TYPE_AES); - psa_set_key_bits(&attributes, 128); - status = psa_import_key(&attributes, key, key_len, &key_id); - if (status != PSA_SUCCESS) { - printf("Failed to import a key\n"); - return; - } - psa_reset_key_attributes(&attributes); - - /* Encrypt the plaintext */ - status = psa_cipher_encrypt_setup(&operation, key_id, alg); - if (status != PSA_SUCCESS) { - printf("Failed to begin cipher operation\n"); - return; - } - status = psa_cipher_generate_iv(&operation, iv, sizeof(iv), &iv_len); - if (status != PSA_SUCCESS) { - printf("Failed to generate IV\n"); - return; - } - status = psa_cipher_update(&operation, plaintext, sizeof(plaintext), - output, sizeof(output), &output_len); - if (status != PSA_SUCCESS) { - printf("Failed to update cipher operation\n"); - return; - } - status = psa_cipher_finish(&operation, output + output_len, - sizeof(output) - output_len, &output_len); - if (status != PSA_SUCCESS) { - printf("Failed to finish cipher operation\n"); - return; - } - printf("Encrypted plaintext\n"); - - /* Clean up cipher operation context */ - psa_cipher_abort(&operation); - - /* Destroy the key */ - psa_destroy_key(key_id); - - mbedtls_psa_crypto_free(); -} -``` - -**To decrypt a message with a symmetric cipher:** -1. Allocate an operation (`psa_cipher_operation_t`) structure to pass to the - cipher functions. -1. Initialize the operation structure to zero or to `PSA_CIPHER_OPERATION_INIT`. -1. Call `psa_cipher_decrypt_setup()` to specify the algorithm and the key to be - used. -1. Call `psa_cipher_set_iv()` with the IV for the decryption. -1. Call `psa_cipher_update()` with the message to encrypt. You may call this - function multiple times, passing successive fragments of the message on - successive calls. -1. Call `psa_cipher_finish()` to end the operation and output the decrypted - message. - -This example shows how to decrypt encrypted data using an AES key in CBC mode -with no padding (assuming all prerequisites have been fulfilled): -```c -void decrypt_with_symmetric_ciphers(const uint8_t *key, size_t key_len) -{ - enum { - block_size = PSA_BLOCK_CIPHER_BLOCK_LENGTH(PSA_KEY_TYPE_AES), - }; - psa_status_t status; - psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT; - psa_algorithm_t alg = PSA_ALG_CBC_NO_PADDING; - psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT; - uint8_t ciphertext[block_size] = SOME_CIPHERTEXT; - uint8_t iv[block_size] = ENCRYPTED_WITH_IV; - uint8_t output[block_size]; - size_t output_len; - psa_key_id_t key_id; - - printf("Decrypt with cipher...\t"); - fflush(stdout); - - /* Initialize PSA Crypto */ - status = psa_crypto_init(); - if (status != PSA_SUCCESS) - { - printf("Failed to initialize PSA Crypto\n"); - return; - } - - /* Import a key */ - psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_DECRYPT); - psa_set_key_algorithm(&attributes, alg); - psa_set_key_type(&attributes, PSA_KEY_TYPE_AES); - psa_set_key_bits(&attributes, 128); - status = psa_import_key(&attributes, key, key_len, &key_id); - if (status != PSA_SUCCESS) { - printf("Failed to import a key\n"); - return; - } - psa_reset_key_attributes(&attributes); - - /* Decrypt the ciphertext */ - status = psa_cipher_decrypt_setup(&operation, key_id, alg); - if (status != PSA_SUCCESS) { - printf("Failed to begin cipher operation\n"); - return; - } - status = psa_cipher_set_iv(&operation, iv, sizeof(iv)); - if (status != PSA_SUCCESS) { - printf("Failed to set IV\n"); - return; - } - status = psa_cipher_update(&operation, ciphertext, sizeof(ciphertext), - output, sizeof(output), &output_len); - if (status != PSA_SUCCESS) { - printf("Failed to update cipher operation\n"); - return; - } - status = psa_cipher_finish(&operation, output + output_len, - sizeof(output) - output_len, &output_len); - if (status != PSA_SUCCESS) { - printf("Failed to finish cipher operation\n"); - return; - } - printf("Decrypted ciphertext\n"); - - /* Clean up cipher operation context */ - psa_cipher_abort(&operation); - - /* Destroy the key */ - psa_destroy_key(key_id); - - mbedtls_psa_crypto_free(); -} -``` - -#### Handling cipher operation contexts - -After you've initialized the operation structure with a successful call to -`psa_cipher_encrypt_setup()` or `psa_cipher_decrypt_setup()`, you can terminate -the operation at any time by calling `psa_cipher_abort()`. - -The call to `psa_cipher_abort()` frees any resources associated with the -operation, except for the operation structure itself. - -The PSA Crypto API implicitly calls `psa_cipher_abort()` when: -* A call to `psa_cipher_generate_iv()`, `psa_cipher_set_iv()` or - `psa_cipher_update()` fails (returning any status other than `PSA_SUCCESS`). -* A call to `psa_cipher_finish()` succeeds or fails. - -After an implicit or explicit call to `psa_cipher_abort()`, the operation -structure is invalidated; in other words, you cannot reuse the operation -structure for the same operation. You can, however, reuse the operation -structure for a different operation by calling either -`psa_cipher_encrypt_setup()` or `psa_cipher_decrypt_setup()` again. - -You must call `psa_cipher_abort()` at some point for any operation that is -initialized successfully (by a successful call to `psa_cipher_encrypt_setup()` -or `psa_cipher_decrypt_setup()`). - -Making multiple sequential calls to `psa_cipher_abort()` on an operation that -is terminated (either implicitly or explicitly) is safe and has no effect. - -### Hashing a message - -The PSA Crypto API lets you compute and verify hashes using various hashing -algorithms. - -**Prerequisites to working with the hash APIs:** -* Initialize the library with a successful call to `psa_crypto_init()`. - -**To calculate a hash:** -1. Allocate an operation structure (`psa_hash_operation_t`) to pass to the hash - functions. -1. Initialize the operation structure to zero or to `PSA_HASH_OPERATION_INIT`. -1. Call `psa_hash_setup()` to specify the hash algorithm. -1. Call `psa_hash_update()` with the message to encrypt. You may call this - function multiple times, passing successive fragments of the message on - successive calls. -1. Call `psa_hash_finish()` to calculate the hash, or `psa_hash_verify()` to - compare the computed hash with an expected hash value. - -This example shows how to calculate the SHA-256 hash of a message: -```c - psa_status_t status; - psa_algorithm_t alg = PSA_ALG_SHA_256; - psa_hash_operation_t operation = PSA_HASH_OPERATION_INIT; - unsigned char input[] = { 'a', 'b', 'c' }; - unsigned char actual_hash[PSA_HASH_MAX_SIZE]; - size_t actual_hash_len; - - printf("Hash a message...\t"); - fflush(stdout); - - /* Initialize PSA Crypto */ - status = psa_crypto_init(); - if (status != PSA_SUCCESS) { - printf("Failed to initialize PSA Crypto\n"); - return; - } - - /* Compute hash of message */ - status = psa_hash_setup(&operation, alg); - if (status != PSA_SUCCESS) { - printf("Failed to begin hash operation\n"); - return; - } - status = psa_hash_update(&operation, input, sizeof(input)); - if (status != PSA_SUCCESS) { - printf("Failed to update hash operation\n"); - return; - } - status = psa_hash_finish(&operation, actual_hash, sizeof(actual_hash), - &actual_hash_len); - if (status != PSA_SUCCESS) { - printf("Failed to finish hash operation\n"); - return; - } - - printf("Hashed a message\n"); - - /* Clean up hash operation context */ - psa_hash_abort(&operation); - - mbedtls_psa_crypto_free(); -``` - -This example shows how to verify the SHA-256 hash of a message: -```c - psa_status_t status; - psa_algorithm_t alg = PSA_ALG_SHA_256; - psa_hash_operation_t operation = PSA_HASH_OPERATION_INIT; - unsigned char input[] = { 'a', 'b', 'c' }; - unsigned char expected_hash[] = { - 0xba, 0x78, 0x16, 0xbf, 0x8f, 0x01, 0xcf, 0xea, 0x41, 0x41, 0x40, 0xde, - 0x5d, 0xae, 0x22, 0x23, 0xb0, 0x03, 0x61, 0xa3, 0x96, 0x17, 0x7a, 0x9c, - 0xb4, 0x10, 0xff, 0x61, 0xf2, 0x00, 0x15, 0xad - }; - size_t expected_hash_len = PSA_HASH_LENGTH(alg); - - printf("Verify a hash...\t"); - fflush(stdout); - - /* Initialize PSA Crypto */ - status = psa_crypto_init(); - if (status != PSA_SUCCESS) { - printf("Failed to initialize PSA Crypto\n"); - return; - } - - /* Verify message hash */ - status = psa_hash_setup(&operation, alg); - if (status != PSA_SUCCESS) { - printf("Failed to begin hash operation\n"); - return; - } - status = psa_hash_update(&operation, input, sizeof(input)); - if (status != PSA_SUCCESS) { - printf("Failed to update hash operation\n"); - return; - } - status = psa_hash_verify(&operation, expected_hash, expected_hash_len); - if (status != PSA_SUCCESS) { - printf("Failed to verify hash\n"); - return; - } - - printf("Verified a hash\n"); - - /* Clean up hash operation context */ - psa_hash_abort(&operation); - - mbedtls_psa_crypto_free(); -``` - -The API provides the macro `PSA_HASH_LENGTH`, which returns the expected hash -length (in bytes) for the specified algorithm. - -#### Handling hash operation contexts - -After a successful call to `psa_hash_setup()`, you can terminate the operation -at any time by calling `psa_hash_abort()`. The call to `psa_hash_abort()` frees -any resources associated with the operation, except for the operation structure -itself. - -The PSA Crypto API implicitly calls `psa_hash_abort()` when: -1. A call to `psa_hash_update()` fails (returning any status other than - `PSA_SUCCESS`). -1. A call to `psa_hash_finish()` succeeds or fails. -1. A call to `psa_hash_verify()` succeeds or fails. - -After an implicit or explicit call to `psa_hash_abort()`, the operation -structure is invalidated; in other words, you cannot reuse the operation -structure for the same operation. You can, however, reuse the operation -structure for a different operation by calling `psa_hash_setup()` again. - -You must call `psa_hash_abort()` at some point for any operation that is -initialized successfully (by a successful call to `psa_hash_setup()`) . - -Making multiple sequential calls to `psa_hash_abort()` on an operation that has -already been terminated (either implicitly or explicitly) is safe and has no -effect. - -### Generating a random value - -The PSA Crypto API can generate random data. - -**Prerequisites to generating random data:** -* Initialize the library with a successful call to `psa_crypto_init()`. - -**Note:** To generate a random key, use `psa_generate_key()` -instead of `psa_generate_random()`. - -This example shows how to generate ten bytes of random data by calling -`psa_generate_random()`: -```C - psa_status_t status; - uint8_t random[10] = { 0 }; - - printf("Generate random...\t"); - fflush(stdout); - - /* Initialize PSA Crypto */ - status = psa_crypto_init(); - if (status != PSA_SUCCESS) { - printf("Failed to initialize PSA Crypto\n"); - return; - } - - status = psa_generate_random(random, sizeof(random)); - if (status != PSA_SUCCESS) { - printf("Failed to generate a random value\n"); - return; - } - - printf("Generated random data\n"); - - /* Clean up */ - mbedtls_psa_crypto_free(); -``` - -### Deriving a new key from an existing key - -The PSA Crypto API provides a key derivation API that lets you derive new keys -from existing ones. The key derivation API has functions to take inputs, -including other keys and data, and functions to generate outputs, such as -new keys or other data. - -You must first initialize and set up a key derivation context, -provided with a key and, optionally, other data. Then, use the key derivation -context to either read derived data to a buffer or send derived data directly -to a key slot. - -See the documentation for the particular algorithm (such as HKDF or the -TLS 1.2 PRF) for information about which inputs to pass when, and when you can -obtain which outputs. - -**Prerequisites to working with the key derivation APIs:** -* Initialize the library with a successful call to `psa_crypto_init()`. -* Use a key with the appropriate attributes set: - * Usage flags set for key derivation (`PSA_KEY_USAGE_DERIVE`) - * Key type set to `PSA_KEY_TYPE_DERIVE`. - * Algorithm set to a key derivation algorithm - (for example, `PSA_ALG_HKDF(PSA_ALG_SHA_256)`). - -**To derive a new AES-CTR 128-bit encryption key into a given key slot using HKDF -with a given key, salt and info:** - -1. Set up the key derivation context using the `psa_key_derivation_setup()` -function, specifying the derivation algorithm `PSA_ALG_HKDF(PSA_ALG_SHA_256)`. -1. Provide an optional salt with `psa_key_derivation_input_bytes()`. -1. Provide info with `psa_key_derivation_input_bytes()`. -1. Provide a secret with `psa_key_derivation_input_key()`, referencing a key - that can be used for key derivation. -1. Set the key attributes desired for the new derived key. We'll set - the `PSA_KEY_USAGE_ENCRYPT` usage flag and the `PSA_ALG_CTR` algorithm for - this example. -1. Derive the key by calling `psa_key_derivation_output_key()`. -1. Clean up the key derivation context. - -At this point, the derived key slot holds a new 128-bit AES-CTR encryption key -derived from the key, salt and info provided: -```C - psa_status_t status; - psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT; - static const unsigned char key[] = { - 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, - 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, - 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, - 0x0b }; - static const unsigned char salt[] = { - 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, - 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c }; - static const unsigned char info[] = { - 0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, - 0xf7, 0xf8, 0xf9 }; - psa_algorithm_t alg = PSA_ALG_HKDF(PSA_ALG_SHA_256); - psa_key_derivation_operation_t operation = - PSA_KEY_DERIVATION_OPERATION_INIT; - size_t derived_bits = 128; - size_t capacity = PSA_BITS_TO_BYTES(derived_bits); - psa_key_id_t base_key; - psa_key_id_t derived_key; - - printf("Derive a key (HKDF)...\t"); - fflush(stdout); - - /* Initialize PSA Crypto */ - status = psa_crypto_init(); - if (status != PSA_SUCCESS) { - printf("Failed to initialize PSA Crypto\n"); - return; - } - - /* Import a key for use in key derivation. If such a key has already been - * generated or imported, you can skip this part. */ - psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_DERIVE); - psa_set_key_algorithm(&attributes, alg); - psa_set_key_type(&attributes, PSA_KEY_TYPE_DERIVE); - status = psa_import_key(&attributes, key, sizeof(key), &base_key); - if (status != PSA_SUCCESS) { - printf("Failed to import a key\n"); - return; - } - psa_reset_key_attributes(&attributes); - - /* Derive a key */ - status = psa_key_derivation_setup(&operation, alg); - if (status != PSA_SUCCESS) { - printf("Failed to begin key derivation\n"); - return; - } - status = psa_key_derivation_set_capacity(&operation, capacity); - if (status != PSA_SUCCESS) { - printf("Failed to set capacity\n"); - return; - } - status = psa_key_derivation_input_bytes(&operation, - PSA_KEY_DERIVATION_INPUT_SALT, - salt, sizeof(salt)); - if (status != PSA_SUCCESS) { - printf("Failed to input salt (extract)\n"); - return; - } - status = psa_key_derivation_input_key(&operation, - PSA_KEY_DERIVATION_INPUT_SECRET, - base_key); - if (status != PSA_SUCCESS) { - printf("Failed to input key (extract)\n"); - return; - } - status = psa_key_derivation_input_bytes(&operation, - PSA_KEY_DERIVATION_INPUT_INFO, - info, sizeof(info)); - if (status != PSA_SUCCESS) { - printf("Failed to input info (expand)\n"); - return; - } - psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_ENCRYPT); - psa_set_key_algorithm(&attributes, PSA_ALG_CTR); - psa_set_key_type(&attributes, PSA_KEY_TYPE_AES); - psa_set_key_bits(&attributes, 128); - status = psa_key_derivation_output_key(&attributes, &operation, - &derived_key); - if (status != PSA_SUCCESS) { - printf("Failed to derive key\n"); - return; - } - psa_reset_key_attributes(&attributes); - - printf("Derived key\n"); - - /* Clean up key derivation operation */ - psa_key_derivation_abort(&operation); - - /* Destroy the keys */ - psa_destroy_key(derived_key); - psa_destroy_key(base_key); - - mbedtls_psa_crypto_free(); -``` - -### Authenticating and encrypting or decrypting a message - -The PSA Crypto API provides a simple way to authenticate and encrypt with -associated data (AEAD), supporting the `PSA_ALG_CCM` algorithm. - -**Prerequisites to working with the AEAD cipher APIs:** -* Initialize the library with a successful call to `psa_crypto_init()`. -* The key attributes for the key used for derivation must have the - `PSA_KEY_USAGE_ENCRYPT` or `PSA_KEY_USAGE_DECRYPT` usage flags. - -This example shows how to authenticate and encrypt a message: -```C - psa_status_t status; - static const uint8_t key[] = { - 0xC0, 0xC1, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7, - 0xC8, 0xC9, 0xCA, 0xCB, 0xCC, 0xCD, 0xCE, 0xCF }; - static const uint8_t nonce[] = { - 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, - 0x08, 0x09, 0x0A, 0x0B }; - static const uint8_t additional_data[] = { - 0xEC, 0x46, 0xBB, 0x63, 0xB0, 0x25, - 0x20, 0xC3, 0x3C, 0x49, 0xFD, 0x70 }; - static const uint8_t input_data[] = { - 0xB9, 0x6B, 0x49, 0xE2, 0x1D, 0x62, 0x17, 0x41, - 0x63, 0x28, 0x75, 0xDB, 0x7F, 0x6C, 0x92, 0x43, - 0xD2, 0xD7, 0xC2 }; - uint8_t *output_data = NULL; - size_t output_size = 0; - size_t output_length = 0; - size_t tag_length = 16; - psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT; - psa_key_id_t key_id; - - printf("Authenticate encrypt...\t"); - fflush(stdout); - - /* Initialize PSA Crypto */ - status = psa_crypto_init(); - if (status != PSA_SUCCESS) { - printf("Failed to initialize PSA Crypto\n"); - return; - } - - output_size = sizeof(input_data) + tag_length; - output_data = (uint8_t *)malloc(output_size); - if (!output_data) { - printf("Out of memory\n"); - return; - } - - /* Import a key */ - psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_ENCRYPT); - psa_set_key_algorithm(&attributes, PSA_ALG_CCM); - psa_set_key_type(&attributes, PSA_KEY_TYPE_AES); - psa_set_key_bits(&attributes, 128); - status = psa_import_key(&attributes, key, sizeof(key), &key_id); - psa_reset_key_attributes(&attributes); - - /* Authenticate and encrypt */ - status = psa_aead_encrypt(key_id, PSA_ALG_CCM, - nonce, sizeof(nonce), - additional_data, sizeof(additional_data), - input_data, sizeof(input_data), - output_data, output_size, - &output_length); - if (status != PSA_SUCCESS) { - printf("Failed to authenticate and encrypt\n"); - return; - } - - printf("Authenticated and encrypted\n"); - - /* Clean up */ - free(output_data); - - /* Destroy the key */ - psa_destroy_key(key_id); - - mbedtls_psa_crypto_free(); -``` - -This example shows how to authenticate and decrypt a message: - -```C - psa_status_t status; - static const uint8_t key_data[] = { - 0xC0, 0xC1, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7, - 0xC8, 0xC9, 0xCA, 0xCB, 0xCC, 0xCD, 0xCE, 0xCF }; - static const uint8_t nonce[] = { - 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, - 0x08, 0x09, 0x0A, 0x0B }; - static const uint8_t additional_data[] = { - 0xEC, 0x46, 0xBB, 0x63, 0xB0, 0x25, - 0x20, 0xC3, 0x3C, 0x49, 0xFD, 0x70 }; - static const uint8_t input_data[] = { - 0x20, 0x30, 0xE0, 0x36, 0xED, 0x09, 0xA0, 0x45, 0xAF, 0x3C, 0xBA, 0xEE, - 0x0F, 0xC8, 0x48, 0xAF, 0xCD, 0x89, 0x54, 0xF4, 0xF6, 0x3F, 0x28, 0x9A, - 0xA1, 0xDD, 0xB2, 0xB8, 0x09, 0xCD, 0x7C, 0xE1, 0x46, 0xE9, 0x98 }; - uint8_t *output_data = NULL; - size_t output_size = 0; - size_t output_length = 0; - psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT; - psa_key_id_t key_id; - - printf("Authenticate decrypt...\t"); - fflush(stdout); - - /* Initialize PSA Crypto */ - status = psa_crypto_init(); - if (status != PSA_SUCCESS) { - printf("Failed to initialize PSA Crypto\n"); - return; - } - - output_size = sizeof(input_data); - output_data = (uint8_t *)malloc(output_size); - if (!output_data) { - printf("Out of memory\n"); - return; - } - - /* Import a key */ - psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_DECRYPT); - psa_set_key_algorithm(&attributes, PSA_ALG_CCM); - psa_set_key_type(&attributes, PSA_KEY_TYPE_AES); - psa_set_key_bits(&attributes, 128); - status = psa_import_key(&attributes, key_data, sizeof(key_data), &key_id); - if (status != PSA_SUCCESS) { - printf("Failed to import a key\n"); - return; - } - psa_reset_key_attributes(&attributes); - - /* Authenticate and decrypt */ - status = psa_aead_decrypt(key_id, PSA_ALG_CCM, - nonce, sizeof(nonce), - additional_data, sizeof(additional_data), - input_data, sizeof(input_data), - output_data, output_size, - &output_length); - if (status != PSA_SUCCESS) { - printf("Failed to authenticate and decrypt %ld\n", status); - return; - } - - printf("Authenticated and decrypted\n"); - - /* Clean up */ - free(output_data); - - /* Destroy the key */ - psa_destroy_key(key_id); - - mbedtls_psa_crypto_free(); -``` - -### Generating and exporting keys - -The PSA Crypto API provides a simple way to generate a key or key pair. - -**Prerequisites to using key generation and export APIs:** -* Initialize the library with a successful call to `psa_crypto_init()`. - -**To generate an ECDSA key:** -1. Set the desired key attributes for key generation by calling - `psa_set_key_algorithm()` with the chosen ECDSA algorithm (such as - `PSA_ALG_DETERMINISTIC_ECDSA(PSA_ALG_SHA_256)`). You only want to export the - public key, not the key pair (or private key); therefore, do not - set `PSA_KEY_USAGE_EXPORT`. -1. Generate a key by calling `psa_generate_key()`. -1. Export the generated public key by calling `psa_export_public_key()`: -```C - enum { - key_bits = 256, - }; - psa_status_t status; - size_t exported_length = 0; - static uint8_t exported[PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits)]; - psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT; - psa_key_id_t key_id; - - printf("Generate a key pair...\t"); - fflush(stdout); - - /* Initialize PSA Crypto */ - status = psa_crypto_init(); - if (status != PSA_SUCCESS) { - printf("Failed to initialize PSA Crypto\n"); - return; - } - - /* Generate a key */ - psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_SIGN_HASH); - psa_set_key_algorithm(&attributes, - PSA_ALG_DETERMINISTIC_ECDSA(PSA_ALG_SHA_256)); - psa_set_key_type(&attributes, - PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1)); - psa_set_key_bits(&attributes, key_bits); - status = psa_generate_key(&attributes, &key_id); - if (status != PSA_SUCCESS) { - printf("Failed to generate key\n"); - return; - } - psa_reset_key_attributes(&attributes); - - status = psa_export_public_key(key_id, exported, sizeof(exported), - &exported_length); - if (status != PSA_SUCCESS) { - printf("Failed to export public key %ld\n", status); - return; - } - - printf("Exported a public key\n"); - - /* Destroy the key */ - psa_destroy_key(key_id); - - mbedtls_psa_crypto_free(); -``` - -### More about the PSA Crypto API - -For more information about the PSA Crypto API, please see the -[PSA Cryptography API Specification](https://arm-software.github.io/psa-api/crypto/). From 6b8e8ff07918fecdf3395caf5d68d02554e15b00 Mon Sep 17 00:00:00 2001 From: Demi Marie Obenour Date: Sat, 11 Mar 2023 17:45:28 -0500 Subject: [PATCH 51/51] Fix segfault in mbedtls_oid_get_numeric_string When passed an empty OID, mbedtls_oid_get_numeric_string would read one byte from the zero-sized buffer and return an error code that depends on its value. This is demonstrated by the test suite changes, which check that an OID with length zero and an invalid buffer pointer does not cause Mbed TLS to segfault. Also check that second and subsequent subidentifiers are terminated, and add a test case for that. Furthermore, stop relying on integer division by 40, use the same loop for both the first and subsequent subidentifiers, and add additional tests. Signed-off-by: Demi Marie Obenour --- ChangeLog.d/fix-oid-to-string-bugs.txt | 6 +- library/oid.c | 87 +++++++++++--------------- tests/suites/test_suite_oid.data | 18 ++++++ tests/suites/test_suite_oid.function | 7 ++- 4 files changed, 65 insertions(+), 53 deletions(-) diff --git a/ChangeLog.d/fix-oid-to-string-bugs.txt b/ChangeLog.d/fix-oid-to-string-bugs.txt index 799f44474..3cf02c39c 100644 --- a/ChangeLog.d/fix-oid-to-string-bugs.txt +++ b/ChangeLog.d/fix-oid-to-string-bugs.txt @@ -3,4 +3,8 @@ Bugfix mbedtls_oid_get_numeric_string(). OIDs such as 2.40.0.25 are now printed correctly. * Reject OIDs with overlong-encoded subidentifiers when converting - OID-to-string. + them to a string. + * Reject OIDs with subidentifier values exceeding UINT_MAX. Such + subidentifiers can be valid, but Mbed TLS cannot currently handle them. + * Reject OIDs that have unterminated subidentifiers, or (equivalently) + have the most-significant bit set in their last byte. diff --git a/library/oid.c b/library/oid.c index 4ec752fb9..12a96503b 100644 --- a/library/oid.c +++ b/library/oid.c @@ -775,65 +775,26 @@ FN_OID_GET_ATTR2(mbedtls_oid_get_pkcs12_pbe_alg, cipher_alg) #endif /* MBEDTLS_PKCS12_C */ -#define OID_SAFE_SNPRINTF \ - do { \ - if (ret < 0 || (size_t) ret >= n) \ - return MBEDTLS_ERR_OID_BUF_TOO_SMALL; \ - \ - n -= (size_t) ret; \ - p += (size_t) ret; \ - } while (0) - /* Return the x.y.z.... style numeric string for the given OID */ int mbedtls_oid_get_numeric_string(char *buf, size_t size, const mbedtls_asn1_buf *oid) { int ret = MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED; - size_t i, n; - unsigned int value; - char *p; + char *p = buf; + size_t n = size; + unsigned int value = 0; - p = buf; - n = size; - - /* First subidentifier contains first two OID components */ - i = 0; - value = 0; - if ((oid->p[0]) == 0x80) { - /* Overlong encoding is not allowed */ - return MBEDTLS_ERR_ASN1_INVALID_DATA; + if (size > INT_MAX) { + /* Avoid overflow computing return value */ + return MBEDTLS_ERR_ASN1_INVALID_LENGTH; } - while (i < oid->len && ((oid->p[i] & 0x80) != 0)) { - /* Prevent overflow in value. */ - if (value > (UINT_MAX >> 7)) { - return MBEDTLS_ERR_ASN1_INVALID_DATA; - } - - value |= oid->p[i] & 0x7F; - value <<= 7; - i++; - } - if (i >= oid->len) { + if (oid->len <= 0) { + /* OID must not be empty */ return MBEDTLS_ERR_ASN1_OUT_OF_DATA; } - /* Last byte of first subidentifier */ - value |= oid->p[i] & 0x7F; - i++; - unsigned int component1 = value / 40; - if (component1 > 2) { - /* The first component can only be 0, 1 or 2. - * If oid->p[0] / 40 is greater than 2, the leftover belongs to - * the second component. */ - component1 = 2; - } - unsigned int component2 = value - (40 * component1); - ret = mbedtls_snprintf(p, n, "%u.%u", component1, component2); - OID_SAFE_SNPRINTF; - - value = 0; - for (; i < oid->len; i++) { + for (size_t i = 0; i < oid->len; i++) { /* Prevent overflow in value. */ if (value > (UINT_MAX >> 7)) { return MBEDTLS_ERR_ASN1_INVALID_DATA; @@ -848,12 +809,38 @@ int mbedtls_oid_get_numeric_string(char *buf, size_t size, if (!(oid->p[i] & 0x80)) { /* Last byte */ - ret = mbedtls_snprintf(p, n, ".%u", value); - OID_SAFE_SNPRINTF; + if (n == size) { + int component1; + unsigned int component2; + /* First subidentifier contains first two OID components */ + if (value >= 80) { + component1 = '2'; + component2 = value - 80; + } else if (value >= 40) { + component1 = '1'; + component2 = value - 40; + } else { + component1 = '0'; + component2 = value; + } + ret = mbedtls_snprintf(p, n, "%c.%u", component1, component2); + } else { + ret = mbedtls_snprintf(p, n, ".%u", value); + } + if (ret < 2 || (size_t) ret >= n) { + return MBEDTLS_ERR_OID_BUF_TOO_SMALL; + } + n -= (size_t) ret; + p += ret; value = 0; } } + if (value != 0) { + /* Unterminated subidentifier */ + return MBEDTLS_ERR_ASN1_OUT_OF_DATA; + } + return (int) (size - n); } diff --git a/tests/suites/test_suite_oid.data b/tests/suites/test_suite_oid.data index 38d8b7e1c..2d331418b 100644 --- a/tests/suites/test_suite_oid.data +++ b/tests/suites/test_suite_oid.data @@ -101,12 +101,30 @@ oid_get_numeric_string:"81010000863A00":0:"2.49.0.0.826.0" OID get numeric string - multi-byte first subidentifier oid_get_numeric_string:"8837":0:"2.999" +OID get numeric string - second subidentifier not terminated +oid_get_numeric_string:"0081":MBEDTLS_ERR_ASN1_OUT_OF_DATA:"" + OID get numeric string - empty oid buffer oid_get_numeric_string:"":MBEDTLS_ERR_ASN1_OUT_OF_DATA:"" OID get numeric string - no final / all bytes have top bit set oid_get_numeric_string:"818181":MBEDTLS_ERR_ASN1_OUT_OF_DATA:"" +OID get numeric string - 0.39 +oid_get_numeric_string:"27":0:"0.39" + +OID get numeric string - 1.0 +oid_get_numeric_string:"28":0:"1.0" + +OID get numeric string - 1.39 +oid_get_numeric_string:"4f":0:"1.39" + +OID get numeric string - 2.0 +oid_get_numeric_string:"50":0:"2.0" + +OID get numeric string - 1 byte first subidentifier beyond 2.39 +oid_get_numeric_string:"7f":0:"2.47" + # Encodes the number 0x0400000000 as a subidentifier which overflows 32-bits OID get numeric string - 32-bit overflow oid_get_numeric_string:"C080808000":MBEDTLS_ERR_ASN1_INVALID_DATA:"" diff --git a/tests/suites/test_suite_oid.function b/tests/suites/test_suite_oid.function index 7759baf36..c06e3373e 100644 --- a/tests/suites/test_suite_oid.function +++ b/tests/suites/test_suite_oid.function @@ -104,13 +104,16 @@ void oid_get_numeric_string(data_t *oid, int error_ret, char *result_str) int ret; input_oid.tag = MBEDTLS_ASN1_OID; - input_oid.p = oid->x; + /* Test that an empty OID is not dereferenced */ + input_oid.p = oid->len ? oid->x : (void *) 1; input_oid.len = oid->len; ret = mbedtls_oid_get_numeric_string(buf, sizeof(buf), &input_oid); if (error_ret == 0) { - TEST_ASSERT(strcmp(buf, result_str) == 0); + TEST_EQUAL(ret, strlen(result_str)); + TEST_ASSERT(ret >= 3); + TEST_EQUAL(strcmp(buf, result_str), 0); } else { TEST_EQUAL(ret, error_ret); }