From 7c195160df1141640920d0ce7226024db73355df Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 12 Oct 2022 16:27:14 +0100 Subject: [PATCH 1/6] Update documentation links Signed-off-by: Dave Rodgman --- CONTRIBUTING.md | 6 +++--- README.md | 14 ++++++++------ SUPPORT.md | 2 +- 3 files changed, 12 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 319f02d204..66fe5f1af0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,7 +7,7 @@ We gratefully accept bug reports and contributions from the community. There are Coding Standards ---------------- -- We would ask that contributions conform to [our coding standards](https://tls.mbed.org/kb/development/mbedtls-coding-standards), and that contributions are fully tested before submission, as mentioned in the [Tests](#tests) and [Continuous Integration](#continuous-integration-tests) sections. +- We would ask that contributions conform to [our coding standards](https://mbed-tls.readthedocs.io/en/latest/kb/development/mbedtls-coding-standards/), and that contributions are fully tested before submission, as mentioned in the [Tests](#tests) and [Continuous Integration](#continuous-integration-tests) sections. - The code should be written in a clean and readable style. - The code should be written in a portable generic way, that will benefit the whole community, and not only your own needs. - The code should be secure, and will be reviewed from a security point of view as well. @@ -56,7 +56,7 @@ As mentioned, tests that show the correctness of the feature or bug fix should b Mbed TLS includes a comprehensive set of test suites in the `tests/` directory that are dynamically generated to produce the actual test source files (e.g. `test_suite_mpi.c`). These files are generated from a `function file` (e.g. `suites/test_suite_mpi.function`) and a `data file` (e.g. `suites/test_suite_mpi.data`). The function file contains the test functions. The data file contains the test cases, specified as parameters that will be passed to the test function. -[A Knowledge Base article describing how to add additional tests is available on the Mbed TLS website](https://tls.mbed.org/kb/development/test_suites). +[A Knowledge Base article describing how to add additional tests is available on the Mbed TLS website](https://mbed-tls.readthedocs.io/en/latest/kb/development/test_suites/). A test script `tests/scripts/basic-build-test.sh` is available to show test coverage of the library. New code contributions should provide a similar level of code coverage to that which already exists for the library. @@ -75,7 +75,7 @@ Mbed TLS is well documented, but if you think documentation is needed, speak out 1. All interfaces should be documented through Doxygen. New APIs should introduce Doxygen documentation. 1. Complex parts in the code should include comments. 1. If needed, a Readme file is advised. -1. If a [Knowledge Base (KB)](https://tls.mbed.org/kb) article should be added, write this as a comment in the PR description. +1. If a [Knowledge Base (KB)](https://mbed-tls.readthedocs.io/en/latest/kb/) article should be added, write this as a comment in the PR description. 1. A [ChangeLog](https://github.com/Mbed-TLS/mbedtls/blob/development/ChangeLog.d/00README.md) entry should be added for this contribution. License and Copyright diff --git a/README.md b/README.md index 8978fafb61..859275991d 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,9 @@ We provide some non-standard configurations focused on specific use cases in the Documentation ------------- -Documentation for the Mbed TLS interfaces in the default library configuration is available as part of the [Mbed TLS documentation](https://tls.mbed.org/api/). +The main Mbed TLS documentation is available via [ReadTheDocs](https://mbed-tls.readthedocs.io/). + +Documentation for the PSA Crypto interface is available [on GitHub](https://armmbed.github.io/mbed-crypto/psa/#application-programming-interface). To generate a local copy of the library documentation in HTML format, tailored to your compile-time configuration: @@ -103,9 +105,9 @@ Setting the variable `SHARED` in your environment will build shared libraries in Please note that setting `CFLAGS` overrides its default value of `-O2` and setting `WARNING_CFLAGS` overrides its default value (starting with `-Wall -Wextra`), so if you just want to add some warning options to the default ones, you can do so by setting `CFLAGS=-O2 -Werror` for example. Setting `WARNING_CFLAGS` is useful when you want to get rid of its default content (for example because your compiler doesn't accept `-Wall` as an option). Directory-specific options cannot be overridden from the command line. -Depending on your platform, you might run into some issues. Please check the Makefiles in `library/`, `programs/` and `tests/` for options to manually add or remove for specific platforms. You can also check [the Mbed TLS Knowledge Base](https://tls.mbed.org/kb) for articles on your platform or issue. +Depending on your platform, you might run into some issues. Please check the Makefiles in `library/`, `programs/` and `tests/` for options to manually add or remove for specific platforms. You can also check [the Mbed TLS Knowledge Base](https://mbed-tls.readthedocs.io/en/latest/kb/) for articles on your platform or issue. -In case you find that you need to do something else as well, please let us know what, so we can add it to the [Mbed TLS Knowledge Base](https://tls.mbed.org/kb). +In case you find that you need to do something else as well, please let us know what, so we can add it to the [Mbed TLS Knowledge Base](https://mbed-tls.readthedocs.io/en/latest/kb/). ### CMake @@ -248,9 +250,9 @@ Porting Mbed TLS Mbed TLS can be ported to many different architectures, OS's and platforms. Before starting a port, you may find the following Knowledge Base articles useful: -- [Porting Mbed TLS to a new environment or OS](https://tls.mbed.org/kb/how-to/how-do-i-port-mbed-tls-to-a-new-environment-OS) -- [What external dependencies does Mbed TLS rely on?](https://tls.mbed.org/kb/development/what-external-dependencies-does-mbedtls-rely-on) -- [How do I configure Mbed TLS](https://tls.mbed.org/kb/compiling-and-building/how-do-i-configure-mbedtls) +- [Porting Mbed TLS to a new environment or OS](https://mbed-tls.readthedocs.io/en/latest/kb/how-to/how-do-i-port-mbed-tls-to-a-new-environment-OS/) +- [What external dependencies does Mbed TLS rely on?](https://mbed-tls.readthedocs.io/en/latest/kb/development/what-external-dependencies-does-mbedtls-rely-on/) +- [How do I configure Mbed TLS](https://mbed-tls.readthedocs.io/en/latest/kb/compiling-and-building/how-do-i-configure-mbedtls/) Mbed TLS is mostly written in portable C99; however, it has a few platform requirements that go beyond the standard, but are met by most modern architectures: diff --git a/SUPPORT.md b/SUPPORT.md index dab7ac54f2..8fec8b2a85 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -2,10 +2,10 @@ Here are some useful sources of information about using Mbed TLS: +- [ReadTheDocs](https://tls.mbed.org/kb); - API documentation, see the [Documentation section of the README](README.md#License); - the `docs` directory in the source tree; -- the [Mbed TLS knowledge Base](https://tls.mbed.org/kb); - the [Mbed TLS mailing-list archives](https://lists.trustedfirmware.org/archives/list/mbed-tls@lists.trustedfirmware.org/). From b319684bca4eabcfabe069aafc57c17820fe5b60 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 12 Oct 2022 16:47:08 +0100 Subject: [PATCH 2/6] Additional updates to docs links Signed-off-by: Dave Rodgman --- ChangeLog | 2 +- SUPPORT.md | 2 +- docs/3.0-migration-guide.md | 2 +- docs/architecture/alternative-implementations.md | 2 +- docs/architecture/testing/test-framework.md | 2 +- docs/architecture/tls13-support.md | 2 +- include/mbedtls/mbedtls_config.h | 6 +++--- include/mbedtls/ssl.h | 2 +- 8 files changed, 10 insertions(+), 10 deletions(-) diff --git a/ChangeLog b/ChangeLog index 6dfb23fa6a..80b86175f0 100644 --- a/ChangeLog +++ b/ChangeLog @@ -463,7 +463,7 @@ API changes provides better randomness. Instead of HAVEGE, declare OS or hardware RNG interfaces with mbedtls_entropy_add_source() and/or use an entropy seed file created securely during device provisioning. See - https://tls.mbed.org/kb/how-to/add-entropy-sources-to-entropy-pool for + https://mbed-tls.readthedocs.io/en/latest/kb/how-to/add-entropy-sources-to-entropy-pool/ for more information. * Add missing const attributes to API functions. * Remove helpers for the transition from Mbed TLS 1.3 to Mbed TLS 2.0: the diff --git a/SUPPORT.md b/SUPPORT.md index 8fec8b2a85..2ef5b54eb9 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -2,7 +2,7 @@ Here are some useful sources of information about using Mbed TLS: -- [ReadTheDocs](https://tls.mbed.org/kb); +- [ReadTheDocs](https://mbed-tls.readthedocs.io/); - API documentation, see the [Documentation section of the README](README.md#License); - the `docs` directory in the source tree; diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 884810da50..63a13ad876 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -141,7 +141,7 @@ recommended), or users who used it through the entropy module but had it as the only source of entropy. If you're in that case, please declare OS or hardware RNG interfaces with `mbedtls_entropy_add_source()` and/or use an entropy seed file created securely during device provisioning. See - for more + for more information. ### Remove helpers for the transition from Mbed TLS 1.3 to Mbed TLS 2.0 diff --git a/docs/architecture/alternative-implementations.md b/docs/architecture/alternative-implementations.md index 7fe6332b47..eacdea7c3a 100644 --- a/docs/architecture/alternative-implementations.md +++ b/docs/architecture/alternative-implementations.md @@ -38,7 +38,7 @@ The general principle of an alternative implementation is: * Create a header file `xxx_alt.h` that defines the context type(s) used by the module. For example, `mbedtls_aes_context` for AES. * Implement all the functions from the module, i.e. the functions declared in `include/mbedtls/xxx.h`. -See https://tls.mbed.org/kb/development/hw_acc_guidelines for a more detailed guide. +See https://mbed-tls.readthedocs.io/en/latest/kb/development/hw_acc_guidelines for a more detailed guide. ### Constraints on context types diff --git a/docs/architecture/testing/test-framework.md b/docs/architecture/testing/test-framework.md index d0d4776112..7780949e16 100644 --- a/docs/architecture/testing/test-framework.md +++ b/docs/architecture/testing/test-framework.md @@ -6,7 +6,7 @@ This document is incomplete. You can help by expanding it. ## Unit tests -See +See ### Unit test descriptions diff --git a/docs/architecture/tls13-support.md b/docs/architecture/tls13-support.md index 10da3c5ab2..fc0087ff83 100644 --- a/docs/architecture/tls13-support.md +++ b/docs/architecture/tls13-support.md @@ -181,7 +181,7 @@ Coding rules checklist for TLS 1.3 The following coding rules are aimed to be a checklist for TLS 1.3 upstreaming work to reduce review rounds and the number of comments in each round. They come along (do NOT replace) the project coding rules -(https://tls.mbed.org/kb/development/mbedtls-coding-standards). They have been +(https://mbed-tls.readthedocs.io/en/latest/kb/development/mbedtls-coding-standards). They have been established and discussed following the review of #4882 that was the PR upstreaming the first part of TLS 1.3 ClientHello writing code. diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 9e8ae37c7f..7269f135b3 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -2552,7 +2552,7 @@ * * \note See also our Knowledge Base article about porting to a new * environment: - * https://tls.mbed.org/kb/how-to/how-do-i-port-mbed-tls-to-a-new-environment-OS + * https://mbed-tls.readthedocs.io/en/latest/kb/how-to/how-do-i-port-mbed-tls-to-a-new-environment-OS * * Module: library/net_sockets.c * @@ -3108,7 +3108,7 @@ * contexts are not shared between threads. If you do intend to use contexts * between threads, you will need to enable this layer to prevent race * conditions. See also our Knowledge Base article about threading: - * https://tls.mbed.org/kb/development/thread-safety-and-multi-threading + * https://mbed-tls.readthedocs.io/en/latest/kb/development/thread-safety-and-multi-threading * * Module: library/threading.c * @@ -3140,7 +3140,7 @@ * * \note See also our Knowledge Base article about porting to a new * environment: - * https://tls.mbed.org/kb/how-to/how-do-i-port-mbed-tls-to-a-new-environment-OS + * https://mbed-tls.readthedocs.io/en/latest/kb/how-to/how-do-i-port-mbed-tls-to-a-new-environment-OS * * Module: library/timing.c */ diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index eda6bc2f21..385c250292 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -2322,7 +2322,7 @@ int mbedtls_ssl_check_record( mbedtls_ssl_context const *ssl, * here, except if using an event-driven style. * * \note See also the "DTLS tutorial" article in our knowledge base. - * https://tls.mbed.org/kb/how-to/dtls-tutorial + * https://mbed-tls.readthedocs.io/en/latest/kb/how-to/dtls-tutorial */ void mbedtls_ssl_set_timer_cb( mbedtls_ssl_context *ssl, void *p_timer, From 7dbfed3b449abf2e993a887ea4a33bfcf7e2be8d Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 12 Oct 2022 17:27:32 +0100 Subject: [PATCH 3/6] Improve wording re: PSA Crypto Signed-off-by: Dave Rodgman --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 859275991d..9c9cf9112e 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Documentation The main Mbed TLS documentation is available via [ReadTheDocs](https://mbed-tls.readthedocs.io/). -Documentation for the PSA Crypto interface is available [on GitHub](https://armmbed.github.io/mbed-crypto/psa/#application-programming-interface). +Documentation for the PSA Cryptography API is available [on GitHub](https://armmbed.github.io/mbed-crypto/psa/#application-programming-interface). To generate a local copy of the library documentation in HTML format, tailored to your compile-time configuration: From 032b594ec99e7f2d814aab30dfe42a33f3775eb9 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Fri, 14 Oct 2022 10:40:56 +0100 Subject: [PATCH 4/6] Update SUPPORT.md Co-authored-by: Paul Elliott <62069445+paul-elliott-arm@users.noreply.github.com> Signed-off-by: Dave Rodgman --- SUPPORT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SUPPORT.md b/SUPPORT.md index 2ef5b54eb9..8710d149aa 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -4,7 +4,7 @@ Here are some useful sources of information about using Mbed TLS: - [ReadTheDocs](https://mbed-tls.readthedocs.io/); - API documentation, see the [Documentation section of the - README](README.md#License); + README](README.md#documentation); - the `docs` directory in the source tree; - the [Mbed TLS mailing-list archives](https://lists.trustedfirmware.org/archives/list/mbed-tls@lists.trustedfirmware.org/). From ce164b70164b6be8d18c0484afe0fd49ab5ed9e3 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Fri, 14 Oct 2022 10:47:04 +0100 Subject: [PATCH 5/6] Update SUPPORT.md Signed-off-by: Dave Rodgman --- SUPPORT.md | 1 + 1 file changed, 1 insertion(+) diff --git a/SUPPORT.md b/SUPPORT.md index 8710d149aa..e12038779a 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -6,6 +6,7 @@ Here are some useful sources of information about using Mbed TLS: - API documentation, see the [Documentation section of the README](README.md#documentation); - the `docs` directory in the source tree; +- the [Mbed TLS knowledge Base](https://mbed-tls.readthedocs.io/en/latest/kb/); - the [Mbed TLS mailing-list archives](https://lists.trustedfirmware.org/archives/list/mbed-tls@lists.trustedfirmware.org/). From f1ebf128e74185f8c13d9ba2a82b076065c37bbf Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Fri, 14 Oct 2022 10:48:52 +0100 Subject: [PATCH 6/6] Fix capitalisation Signed-off-by: Dave Rodgman --- SUPPORT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SUPPORT.md b/SUPPORT.md index e12038779a..b550e08e5d 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -6,7 +6,7 @@ Here are some useful sources of information about using Mbed TLS: - API documentation, see the [Documentation section of the README](README.md#documentation); - the `docs` directory in the source tree; -- the [Mbed TLS knowledge Base](https://mbed-tls.readthedocs.io/en/latest/kb/); +- the [Mbed TLS Knowledge Base](https://mbed-tls.readthedocs.io/en/latest/kb/); - the [Mbed TLS mailing-list archives](https://lists.trustedfirmware.org/archives/list/mbed-tls@lists.trustedfirmware.org/).