From 107a41f5d98722b5bec46b1b0a54dac5566f84a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Mon, 11 May 2015 14:57:04 +0200 Subject: [PATCH] Add Irit's mbed-OS-specific Readme --- README.rst | 141 ----------------------------------------------------- Readme.md | 37 ++++++++++++++ 2 files changed, 37 insertions(+), 141 deletions(-) delete mode 100644 README.rst create mode 100644 Readme.md diff --git a/README.rst b/README.rst deleted file mode 100644 index bec0e4b6e..000000000 --- a/README.rst +++ /dev/null @@ -1,141 +0,0 @@ -=================== -README for mbed TLS -=================== - -Configuration -============= - -mbed TLS should build out of the box on most systems. Some platform specific options are available in the fully-documented configuration file *include/mbedtls/config.h*, which is also the place where features can be selected. -This file can be edited manually, or in a more programmatic way using the Perl -script *scripts/config.pl* (use *--help* for usage instructions). - -Compiler options can be set using standard variables such as *CC* and *CFLAGS* when using the Make and CMake build system (see below). - -Compiling -========= - -There are currently three active build systems within the mbed TLS releases: - -- Make -- CMake -- Microsoft Visual Studio (Visual Studio 6 and Visual Studio 2010) - -The main system used for development is CMake. That system is always the most up-to-date. The others should reflect all changes present in the CMake build system, but some features are not ported there by default. - -Make ----- - -We intentionally only use the absolute minimum of **Make** functionality, as we have discovered that a lot of **Make** features are not supported on all different implementations of Make on different platforms. As such, the Makefiles sometimes require some handwork or `export` statements in order to work for your platform. - -In order to build the source using Make, just enter at the command line:: - - make - -In order to run the tests, enter:: - - make check - -In order to build for a Windows platform, you should use WINDOWS_BUILD=1 if the target is Windows but the build environment is Unix-like (eg when cross-compiling, or compiling from an MSYS shell), and WINDOWS=1 if the build environment is a Windows shell. - -Setting the variable SHARED in your environment will build a shared library in addition to the static library. Setting DEBUG gives you a debug build. You can override CFLAGS and LDFLAGS by setting them in your environment or on the make command line; if you do so, essential parts such as -I will still be preserved. Warning options may be overridden separately using WARNING_CFLAGS. - -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 `_ 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 KB. - -CMake ------ - -In order to build the source using CMake, just enter at the command line:: - - cmake . - - make - -There are many different build modes available within the CMake buildsystem. Most of them are available for gcc and clang, though some are compiler-specific: - -- Release. - This generates the default code without any unnecessary information in the binary files. -- Debug. - This generates debug information and disables optimization of the code. -- Coverage. - This generates code coverage information in addition to debug information. -- ASan. - This instruments the code with AddressSanitizer to check for memory errors. - (This includes LeakSanitizer, with recent version of gcc and clang.) - (With recent version of clang, this mode also instruments the code with - UndefinedSanitizer to check for undefined behaviour.) -- ASanDbg. - Same as ASan but slower, with debug information and better stack traces. -- MemSan. - This instruments the code with MemorySanitizer to check for uninitialised - memory reads. Experimental, needs recent clang on Linux/x86_64. -- MemSanDbg. - Same as ASan but slower, with debug information, better stack traces and - origin tracking. -- Check. - This activates the compiler warnings that depend on optimization and treats - all warnings as errors. - -Switching build modes in CMake is simple. For debug mode, enter at the command line: - - cmake -D CMAKE_BUILD_TYPE:String="Debug" . - -Note that, with CMake, if you want to change the compiler or its options after you already ran CMake, you need to clear its cache first, eg (using GNU find):: - - find . -iname '*cmake*' -not -name CMakeLists.txt -exec rm -rf {} + - CC=gcc CFLAGS='-fstack-protector-strong -Wa,--noexecstack' cmake . - -In order to run the tests, enter:: - - make test - -Microsoft Visual Studio ------------------------ - -The build files for Microsoft Visual Studio are generated for Visual Studio 6.0 and Visual Studio 2010. - -The workspace 'mbedtls.dsw' contains all the basic projects needed to build the library and all the programs. The files in tests are not generated and compiled, as these need a perl environment as well. - -Example programs -================ - -We've included example programs for a lot of different features and uses in *programs/*. Most programs only focus on a single feature or usage scenario, so keep that in mind when copying parts of the code. - -Tests -===== - -mbed TLS includes an elaborate test suite in *tests/* that initially requires Perl to generate the tests files (e.g. *test_suite_mpi.c*). These files are generates 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 template for each test function. The **data file** contains the test cases, specified as parameters that should be pushed into a template function. - -For machines with a Unix shell and OpenSSL (and optionally GnuTLS) installed, additional test scripts are available: - -- *tests/ssl-opt.sh* runs integration tests for various TLS options (renegotiation, resumption, etc.) and tests interoperability of these options with other implementations. -- *tests/compat.sh* tests interoperability of every ciphersuite with other implementations. -- *tests/scripts/test-ref-configs.pl* test builds in various reduced configurations. -- *tests/scripts/all.sh* runs a combination of the above tests with various build options (eg ASan). - -Configurations -============== - -We provide some non-standard configurations focused on specific use cases in the configs/ directory. You can read more about those in configs/README.txt - -Contributing -============ - -We graciously accept bugs and contributions from the community. There are some requirements we need to fulfil in order to be able to integrate contributions in the main code. - -Simple bug fixes to existing code do not contain copyright themselves and we can integrate those without any issue. The same goes for trivial contributions. - -For larger contributions, e.g. a new feature, the code possible falls under copyright law. We then need your consent to share in the ownership of the copyright. We have a form for that, which we will mail to you in case you submit a contribution or pull request that we deem this necessary for. - -Process -------- -#. `Check for open issues `_ or - `start a discussion `_ around a feature - idea or a bug. -#. Fork the `mbed TLS repository on Github `_ - to start making your changes. -#. Write a test which shows that the bug was fixed or that the feature works - as expected. -#. Send a pull request and bug us until it gets merged and published. We will - include your name in the ChangeLog :) diff --git a/Readme.md b/Readme.md new file mode 100644 index 000000000..ed8b0bc0e --- /dev/null +++ b/Readme.md @@ -0,0 +1,37 @@ +# mbed TLS + +mbed TLS (formerly known as PolarSSL) makes it trivially easy for developers to include cryptographic and SSL/TLS capabilities in their (embedded) products, facilitating this functionality with a minimal coding footprint. It offers an SSL library with an intuitive API and readable source code. + +The Alpha 3 release of mbed TLS is an integration of TLS, mbed SDK and yotta. It is a testing preview only and **not suitable for deployment**: there is currently no source of random numbers, meaning no security at all for (D)TLS communication and other protocols that rely on random numbers. + +## Sample programs + +This release includes the [following samples](https://github.com/ARMmbed/mbedtls-examples): + +1. [**TLS client:**](https://github.com/ARMmbed/mbedtls-examples/tree/master/tls-client) downloads a file from an HTTPS server (mbed.org) and looks for a specific string in that file. + +2. [**Self test:**](https://github.com/ARMmbed/mbedtls-examples/tree/master/selftest) tests different TLS base functionalities. + +3. [**Benchmark:**](https://github.com/ARMmbed/mbedtls-examples/tree/master/be nchmark): tests the time and memory required to perform TLS base functions. + +## Running TLS + +Please follow the instructions in the [TLS client sample](https://github.com/ARMmbed/mbedtls-examples/tree/master/tls-client). These include a list of prerequisites and an explanation of building TLS with yotta. + +## Contributing + +We graciously accept bugs and contributions from the community. There are some requirements we need to fulfil in order to be able to integrate contributions in the main code: + +* Simple bug fixes to existing code do not contain copyright themselves and we can integrate those without any issue. The same goes for trivial contributions. + +* For larger contributions, e.g. a new feature, the code possibly falls under copyright law. We then need your consent to share in the ownership of the copyright. We have a form for that, which we will mail to you in case you submit a contribution or pull request that we deem this necessary for. + +To contribute, please: + +* [Check for open issues](https://github.com/ARMmbed/mbedtls/issues) or [start a discussion](https://tls.mbed.org/discussions) around a feature idea or a bug. + +* Fork the [mbed TLS repository on Github](https://github.com/ARMmbed/mbedtls>) to start making your changes. + +* Write a test that shows that the bug was fixed or that the feature works as expected. + +* Send a pull request and bug us until it gets merged and published. We will include your name in the ChangeLog :)