1#!/usr/bin/env python3
2
3"""Mbed TLS configuration file manipulation library and tool
4
5Basic usage, to read the Mbed TLS or Mbed Crypto configuration:
6    config = ConfigFile()
7    if 'MBEDTLS_RSA_C' in config: print('RSA is enabled')
8"""
9
10## Copyright The Mbed TLS Contributors
11## SPDX-License-Identifier: Apache-2.0
12##
13## Licensed under the Apache License, Version 2.0 (the "License"); you may
14## not use this file except in compliance with the License.
15## You may obtain a copy of the License at
16##
17## http://www.apache.org/licenses/LICENSE-2.0
18##
19## Unless required by applicable law or agreed to in writing, software
20## distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
21## WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
22## See the License for the specific language governing permissions and
23## limitations under the License.
24
25import os
26import re
27
28class Setting:
29    """Representation of one Mbed TLS mbedtls_config.h setting.
30
31    Fields:
32    * name: the symbol name ('MBEDTLS_xxx').
33    * value: the value of the macro. The empty string for a plain #define
34      with no value.
35    * active: True if name is defined, False if a #define for name is
36      present in mbedtls_config.h but commented out.
37    * section: the name of the section that contains this symbol.
38    """
39    # pylint: disable=too-few-public-methods
40    def __init__(self, active, name, value='', section=None):
41        self.active = active
42        self.name = name
43        self.value = value
44        self.section = section
45
46class Config:
47    """Representation of the Mbed TLS configuration.
48
49    In the documentation of this class, a symbol is said to be *active*
50    if there is a #define for it that is not commented out, and *known*
51    if there is a #define for it whether commented out or not.
52
53    This class supports the following protocols:
54    * `name in config` is `True` if the symbol `name` is active, `False`
55      otherwise (whether `name` is inactive or not known).
56    * `config[name]` is the value of the macro `name`. If `name` is inactive,
57      raise `KeyError` (even if `name` is known).
58    * `config[name] = value` sets the value associated to `name`. `name`
59      must be known, but does not need to be set. This does not cause
60      name to become set.
61    """
62
63    def __init__(self):
64        self.settings = {}
65
66    def __contains__(self, name):
67        """True if the given symbol is active (i.e. set).
68
69        False if the given symbol is not set, even if a definition
70        is present but commented out.
71        """
72        return name in self.settings and self.settings[name].active
73
74    def all(self, *names):
75        """True if all the elements of names are active (i.e. set)."""
76        return all(self.__contains__(name) for name in names)
77
78    def any(self, *names):
79        """True if at least one symbol in names are active (i.e. set)."""
80        return any(self.__contains__(name) for name in names)
81
82    def known(self, name):
83        """True if a #define for name is present, whether it's commented out or not."""
84        return name in self.settings
85
86    def __getitem__(self, name):
87        """Get the value of name, i.e. what the preprocessor symbol expands to.
88
89        If name is not known, raise KeyError. name does not need to be active.
90        """
91        return self.settings[name].value
92
93    def get(self, name, default=None):
94        """Get the value of name. If name is inactive (not set), return default.
95
96        If a #define for name is present and not commented out, return
97        its expansion, even if this is the empty string.
98
99        If a #define for name is present but commented out, return default.
100        """
101        if name in self.settings:
102            return self.settings[name].value
103        else:
104            return default
105
106    def __setitem__(self, name, value):
107        """If name is known, set its value.
108
109        If name is not known, raise KeyError.
110        """
111        self.settings[name].value = value
112
113    def set(self, name, value=None):
114        """Set name to the given value and make it active.
115
116        If value is None and name is already known, don't change its value.
117        If value is None and name is not known, set its value to the empty
118        string.
119        """
120        if name in self.settings:
121            if value is not None:
122                self.settings[name].value = value
123            self.settings[name].active = True
124        else:
125            self.settings[name] = Setting(True, name, value=value)
126
127    def unset(self, name):
128        """Make name unset (inactive).
129
130        name remains known if it was known before.
131        """
132        if name not in self.settings:
133            return
134        self.settings[name].active = False
135
136    def adapt(self, adapter):
137        """Run adapter on each known symbol and (de)activate it accordingly.
138
139        `adapter` must be a function that returns a boolean. It is called as
140        `adapter(name, active, section)` for each setting, where `active` is
141        `True` if `name` is set and `False` if `name` is known but unset,
142        and `section` is the name of the section containing `name`. If
143        `adapter` returns `True`, then set `name` (i.e. make it active),
144        otherwise unset `name` (i.e. make it known but inactive).
145        """
146        for setting in self.settings.values():
147            setting.active = adapter(setting.name, setting.active,
148                                     setting.section)
149
150    def change_matching(self, regexs, enable):
151        """Change all symbols matching one of the regexs to the desired state."""
152        if not regexs:
153            return
154        regex = re.compile('|'.join(regexs))
155        for setting in self.settings.values():
156            if regex.search(setting.name):
157                setting.active = enable
158
159def is_full_section(section):
160    """Is this section affected by "config.py full" and friends?"""
161    return section.endswith('support') or section.endswith('modules')
162
163def realfull_adapter(_name, active, section):
164    """Activate all symbols found in the system and feature sections."""
165    if not is_full_section(section):
166        return active
167    return True
168
169# The goal of the full configuration is to have everything that can be tested
170# together. This includes deprecated or insecure options. It excludes:
171# * Options that require additional build dependencies or unusual hardware.
172# * Options that make testing less effective.
173# * Options that are incompatible with other options, or more generally that
174#   interact with other parts of the code in such a way that a bulk enabling
175#   is not a good way to test them.
176# * Options that remove features.
177EXCLUDE_FROM_FULL = frozenset([
178    #pylint: disable=line-too-long
179    'MBEDTLS_CTR_DRBG_USE_128_BIT_KEY', # interacts with ENTROPY_FORCE_SHA256
180    'MBEDTLS_DEPRECATED_REMOVED', # conflicts with deprecated options
181    'MBEDTLS_DEPRECATED_WARNING', # conflicts with deprecated options
182    'MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED', # influences the use of ECDH in TLS
183    'MBEDTLS_ECP_NO_FALLBACK', # removes internal ECP implementation
184    'MBEDTLS_ECP_RESTARTABLE', # incompatible with USE_PSA_CRYPTO
185    'MBEDTLS_ENTROPY_FORCE_SHA256', # interacts with CTR_DRBG_128_BIT_KEY
186    'MBEDTLS_HAVE_SSE2', # hardware dependency
187    'MBEDTLS_MEMORY_BACKTRACE', # depends on MEMORY_BUFFER_ALLOC_C
188    'MBEDTLS_MEMORY_BUFFER_ALLOC_C', # makes sanitizers (e.g. ASan) less effective
189    'MBEDTLS_MEMORY_DEBUG', # depends on MEMORY_BUFFER_ALLOC_C
190    'MBEDTLS_NO_64BIT_MULTIPLICATION', # influences anything that uses bignum
191    'MBEDTLS_NO_DEFAULT_ENTROPY_SOURCES', # removes a feature
192    'MBEDTLS_NO_PLATFORM_ENTROPY', # removes a feature
193    'MBEDTLS_NO_UDBL_DIVISION', # influences anything that uses bignum
194    'MBEDTLS_PLATFORM_NO_STD_FUNCTIONS', # removes a feature
195    'MBEDTLS_PSA_CRYPTO_CONFIG', # toggles old/new style PSA config
196    'MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG', # behavior change + build dependency
197    'MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER', # incompatible with USE_PSA_CRYPTO
198    'MBEDTLS_PSA_CRYPTO_SPM', # platform dependency (PSA SPM)
199    'MBEDTLS_PSA_INJECT_ENTROPY', # build dependency (hook functions)
200    'MBEDTLS_RSA_NO_CRT', # influences the use of RSA in X.509 and TLS
201    'MBEDTLS_TEST_CONSTANT_FLOW_MEMSAN', # build dependency (clang+memsan)
202    'MBEDTLS_TEST_CONSTANT_FLOW_VALGRIND', # build dependency (valgrind headers)
203    'MBEDTLS_X509_REMOVE_INFO', # removes a feature
204])
205
206def is_seamless_alt(name):
207    """Whether the xxx_ALT symbol should be included in the full configuration.
208
209    Include alternative implementations of platform functions, which are
210    configurable function pointers that default to the built-in function.
211    This way we test that the function pointers exist and build correctly
212    without changing the behavior, and tests can verify that the function
213    pointers are used by modifying those pointers.
214
215    Exclude alternative implementations of library functions since they require
216    an implementation of the relevant functions and an xxx_alt.h header.
217    """
218    if name == 'MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT':
219        # Similar to non-platform xxx_ALT, requires platform_alt.h
220        return False
221    return name.startswith('MBEDTLS_PLATFORM_')
222
223def include_in_full(name):
224    """Rules for symbols in the "full" configuration."""
225    if name in EXCLUDE_FROM_FULL:
226        return False
227    if name.endswith('_ALT'):
228        return is_seamless_alt(name)
229    return True
230
231def full_adapter(name, active, section):
232    """Config adapter for "full"."""
233    if not is_full_section(section):
234        return active
235    return include_in_full(name)
236
237# The baremetal configuration excludes options that require a library or
238# operating system feature that is typically not present on bare metal
239# systems. Features that are excluded from "full" won't be in "baremetal"
240# either (unless explicitly turned on in baremetal_adapter) so they don't
241# need to be repeated here.
242EXCLUDE_FROM_BAREMETAL = frozenset([
243    #pylint: disable=line-too-long
244    'MBEDTLS_ENTROPY_NV_SEED', # requires a filesystem and FS_IO or alternate NV seed hooks
245    'MBEDTLS_FS_IO', # requires a filesystem
246    'MBEDTLS_HAVE_TIME', # requires a clock
247    'MBEDTLS_HAVE_TIME_DATE', # requires a clock
248    'MBEDTLS_NET_C', # requires POSIX-like networking
249    'MBEDTLS_PLATFORM_FPRINTF_ALT', # requires FILE* from stdio.h
250    'MBEDTLS_PLATFORM_NV_SEED_ALT', # requires a filesystem and ENTROPY_NV_SEED
251    'MBEDTLS_PLATFORM_TIME_ALT', # requires a clock and HAVE_TIME
252    'MBEDTLS_PSA_CRYPTO_SE_C', # requires a filesystem and PSA_CRYPTO_STORAGE_C
253    'MBEDTLS_PSA_CRYPTO_STORAGE_C', # requires a filesystem
254    'MBEDTLS_PSA_ITS_FILE_C', # requires a filesystem
255    'MBEDTLS_THREADING_C', # requires a threading interface
256    'MBEDTLS_THREADING_PTHREAD', # requires pthread
257    'MBEDTLS_TIMING_C', # requires a clock
258])
259
260def keep_in_baremetal(name):
261    """Rules for symbols in the "baremetal" configuration."""
262    if name in EXCLUDE_FROM_BAREMETAL:
263        return False
264    return True
265
266def baremetal_adapter(name, active, section):
267    """Config adapter for "baremetal"."""
268    if not is_full_section(section):
269        return active
270    if name == 'MBEDTLS_NO_PLATFORM_ENTROPY':
271        # No OS-provided entropy source
272        return True
273    return include_in_full(name) and keep_in_baremetal(name)
274
275def include_in_crypto(name):
276    """Rules for symbols in a crypto configuration."""
277    if name.startswith('MBEDTLS_X509_') or \
278       name.startswith('MBEDTLS_SSL_') or \
279       name.startswith('MBEDTLS_KEY_EXCHANGE_'):
280        return False
281    if name in [
282            'MBEDTLS_DEBUG_C', # part of libmbedtls
283            'MBEDTLS_NET_C', # part of libmbedtls
284    ]:
285        return False
286    return True
287
288def crypto_adapter(adapter):
289    """Modify an adapter to disable non-crypto symbols.
290
291    ``crypto_adapter(adapter)(name, active, section)`` is like
292    ``adapter(name, active, section)``, but unsets all X.509 and TLS symbols.
293    """
294    def continuation(name, active, section):
295        if not include_in_crypto(name):
296            return False
297        if adapter is None:
298            return active
299        return adapter(name, active, section)
300    return continuation
301
302def no_deprecated_adapter(adapter):
303    """Modify an adapter to disable deprecated symbols.
304
305    ``no_deprecated_adapter(adapter)(name, active, section)`` is like
306    ``adapter(name, active, section)``, but unsets all deprecated symbols
307    and sets ``MBEDTLS_DEPRECATED_REMOVED``.
308    """
309    def continuation(name, active, section):
310        if name == 'MBEDTLS_DEPRECATED_REMOVED':
311            return True
312        if adapter is None:
313            return active
314        return adapter(name, active, section)
315    return continuation
316
317class ConfigFile(Config):
318    """Representation of the Mbed TLS configuration read for a file.
319
320    See the documentation of the `Config` class for methods to query
321    and modify the configuration.
322    """
323
324    _path_in_tree = 'include/mbedtls/mbedtls_config.h'
325    default_path = [_path_in_tree,
326                    os.path.join(os.path.dirname(__file__),
327                                 os.pardir,
328                                 _path_in_tree),
329                    os.path.join(os.path.dirname(os.path.abspath(os.path.dirname(__file__))),
330                                 _path_in_tree)]
331
332    def __init__(self, filename=None):
333        """Read the Mbed TLS configuration file."""
334        if filename is None:
335            for candidate in self.default_path:
336                if os.path.lexists(candidate):
337                    filename = candidate
338                    break
339            else:
340                raise Exception('Mbed TLS configuration file not found',
341                                self.default_path)
342        super().__init__()
343        self.filename = filename
344        self.current_section = 'header'
345        with open(filename, 'r', encoding='utf-8') as file:
346            self.templates = [self._parse_line(line) for line in file]
347        self.current_section = None
348
349    def set(self, name, value=None):
350        if name not in self.settings:
351            self.templates.append((name, '', '#define ' + name + ' '))
352        super().set(name, value)
353
354    _define_line_regexp = (r'(?P<indentation>\s*)' +
355                           r'(?P<commented_out>(//\s*)?)' +
356                           r'(?P<define>#\s*define\s+)' +
357                           r'(?P<name>\w+)' +
358                           r'(?P<arguments>(?:\((?:\w|\s|,)*\))?)' +
359                           r'(?P<separator>\s*)' +
360                           r'(?P<value>.*)')
361    _section_line_regexp = (r'\s*/?\*+\s*[\\@]name\s+SECTION:\s*' +
362                            r'(?P<section>.*)[ */]*')
363    _config_line_regexp = re.compile(r'|'.join([_define_line_regexp,
364                                                _section_line_regexp]))
365    def _parse_line(self, line):
366        """Parse a line in mbedtls_config.h and return the corresponding template."""
367        line = line.rstrip('\r\n')
368        m = re.match(self._config_line_regexp, line)
369        if m is None:
370            return line
371        elif m.group('section'):
372            self.current_section = m.group('section')
373            return line
374        else:
375            active = not m.group('commented_out')
376            name = m.group('name')
377            value = m.group('value')
378            template = (name,
379                        m.group('indentation'),
380                        m.group('define') + name +
381                        m.group('arguments') + m.group('separator'))
382            self.settings[name] = Setting(active, name, value,
383                                          self.current_section)
384            return template
385
386    def _format_template(self, name, indent, middle):
387        """Build a line for mbedtls_config.h for the given setting.
388
389        The line has the form "<indent>#define <name> <value>"
390        where <middle> is "#define <name> ".
391        """
392        setting = self.settings[name]
393        value = setting.value
394        if value is None:
395            value = ''
396        # Normally the whitespace to separte the symbol name from the
397        # value is part of middle, and there's no whitespace for a symbol
398        # with no value. But if a symbol has been changed from having a
399        # value to not having one, the whitespace is wrong, so fix it.
400        if value:
401            if middle[-1] not in '\t ':
402                middle += ' '
403        else:
404            middle = middle.rstrip()
405        return ''.join([indent,
406                        '' if setting.active else '//',
407                        middle,
408                        value]).rstrip()
409
410    def write_to_stream(self, output):
411        """Write the whole configuration to output."""
412        for template in self.templates:
413            if isinstance(template, str):
414                line = template
415            else:
416                line = self._format_template(*template)
417            output.write(line + '\n')
418
419    def write(self, filename=None):
420        """Write the whole configuration to the file it was read from.
421
422        If filename is specified, write to this file instead.
423        """
424        if filename is None:
425            filename = self.filename
426        with open(filename, 'w', encoding='utf-8') as output:
427            self.write_to_stream(output)
428
429if __name__ == '__main__':
430    def main():
431        """Command line mbedtls_config.h manipulation tool."""
432        parser = argparse.ArgumentParser(description="""
433        Mbed TLS and Mbed Crypto configuration file manipulation tool.
434        """)
435        parser.add_argument('--file', '-f',
436                            help="""File to read (and modify if requested).
437                            Default: {}.
438                            """.format(ConfigFile.default_path))
439        parser.add_argument('--force', '-o',
440                            action='store_true',
441                            help="""For the set command, if SYMBOL is not
442                            present, add a definition for it.""")
443        parser.add_argument('--write', '-w', metavar='FILE',
444                            help="""File to write to instead of the input file.""")
445        subparsers = parser.add_subparsers(dest='command',
446                                           title='Commands')
447        parser_get = subparsers.add_parser('get',
448                                           help="""Find the value of SYMBOL
449                                           and print it. Exit with
450                                           status 0 if a #define for SYMBOL is
451                                           found, 1 otherwise.
452                                           """)
453        parser_get.add_argument('symbol', metavar='SYMBOL')
454        parser_set = subparsers.add_parser('set',
455                                           help="""Set SYMBOL to VALUE.
456                                           If VALUE is omitted, just uncomment
457                                           the #define for SYMBOL.
458                                           Error out of a line defining
459                                           SYMBOL (commented or not) is not
460                                           found, unless --force is passed.
461                                           """)
462        parser_set.add_argument('symbol', metavar='SYMBOL')
463        parser_set.add_argument('value', metavar='VALUE', nargs='?',
464                                default='')
465        parser_set_all = subparsers.add_parser('set-all',
466                                               help="""Uncomment all #define
467                                               whose name contains a match for
468                                               REGEX.""")
469        parser_set_all.add_argument('regexs', metavar='REGEX', nargs='*')
470        parser_unset = subparsers.add_parser('unset',
471                                             help="""Comment out the #define
472                                             for SYMBOL. Do nothing if none
473                                             is present.""")
474        parser_unset.add_argument('symbol', metavar='SYMBOL')
475        parser_unset_all = subparsers.add_parser('unset-all',
476                                                 help="""Comment out all #define
477                                                 whose name contains a match for
478                                                 REGEX.""")
479        parser_unset_all.add_argument('regexs', metavar='REGEX', nargs='*')
480
481        def add_adapter(name, function, description):
482            subparser = subparsers.add_parser(name, help=description)
483            subparser.set_defaults(adapter=function)
484        add_adapter('baremetal', baremetal_adapter,
485                    """Like full, but exclude features that require platform
486                    features such as file input-output.""")
487        add_adapter('full', full_adapter,
488                    """Uncomment most features.
489                    Exclude alternative implementations and platform support
490                    options, as well as some options that are awkward to test.
491                    """)
492        add_adapter('full_no_deprecated', no_deprecated_adapter(full_adapter),
493                    """Uncomment most non-deprecated features.
494                    Like "full", but without deprecated features.
495                    """)
496        add_adapter('realfull', realfull_adapter,
497                    """Uncomment all boolean #defines.
498                    Suitable for generating documentation, but not for building.""")
499        add_adapter('crypto', crypto_adapter(None),
500                    """Only include crypto features. Exclude X.509 and TLS.""")
501        add_adapter('crypto_baremetal', crypto_adapter(baremetal_adapter),
502                    """Like baremetal, but with only crypto features,
503                    excluding X.509 and TLS.""")
504        add_adapter('crypto_full', crypto_adapter(full_adapter),
505                    """Like full, but with only crypto features,
506                    excluding X.509 and TLS.""")
507
508        args = parser.parse_args()
509        config = ConfigFile(args.file)
510        if args.command is None:
511            parser.print_help()
512            return 1
513        elif args.command == 'get':
514            if args.symbol in config:
515                value = config[args.symbol]
516                if value:
517                    sys.stdout.write(value + '\n')
518            return 0 if args.symbol in config else 1
519        elif args.command == 'set':
520            if not args.force and args.symbol not in config.settings:
521                sys.stderr.write("A #define for the symbol {} "
522                                 "was not found in {}\n"
523                                 .format(args.symbol, config.filename))
524                return 1
525            config.set(args.symbol, value=args.value)
526        elif args.command == 'set-all':
527            config.change_matching(args.regexs, True)
528        elif args.command == 'unset':
529            config.unset(args.symbol)
530        elif args.command == 'unset-all':
531            config.change_matching(args.regexs, False)
532        else:
533            config.adapt(args.adapter)
534        config.write(args.write)
535        return 0
536
537    # Import modules only used by main only if main is defined and called.
538    # pylint: disable=wrong-import-position
539    import argparse
540    import sys
541    sys.exit(main())
542