Merge pull request #31 from ARMmbed/AnotherButler-patch-2

Update tls_porting.md

Author: AnotherButler

docs/advanced/tls_porting.md

@@ -2,32 +2,35 @@
 
 This document explains how to port [mbed TLS](https://github.com/ARMmbed/mbedtls) to a new mbed development board.
 
-<span class="notes">**Note:** This part is critical for the security of your product and you should consult a cryptography expert while considering the choices and implementing them.</span>
+<span class="notes">**Note:** This part is critical for the security of your product, and you should consult a cryptography expert while considering the choices and implementing them.</span>
 
 ## 1. Why mbed TLS needs entropy
 
-Almost every cryptographic protocol requires random values that no one should be able to predict. A striking example is their use as session keys: it is easy to see that if an adversary can predict the session key, then he can decrypt the whole session. Even if the adversary can't predict it exactly, just with a relatively high probability, he can still recover the contents of the session. For example, if the adversary has a 0.00001% chance of predicting the 256 bit AES session key, then he can break it as easily as if we had used a 23 bit key (that is - very easily).
+Almost every cryptographic protocol requires random values that no one should be able to predict. A striking example is their use as session keys: It is easy to see that if an adversary can predict the session key, then he can decrypt the whole session. Even if the adversary can't predict it exactly, just with a relatively high probability, he can still recover the contents of the session. For example, if the adversary has a 0.00001% chance of predicting the 256 bit AES session key, then he can break it as easily as if we had used a 23 bit key (that is - very easily).
 
-Creating session keys is only one use for random values; they have far more complicated applications. And although in these more complex use cases the connection between the predictability of the values and the security of the protocol is not so obvious, it is no less crucial.
+Creating session keys is only one use for random values; they have far more complicated applications. In these more complex use cases, the connection between the predictability of the values and the security of the protocol is not as obvious, but it is still crucial.
 
 ## 2. Which entropy source to choose
 
 - If you have a target with a True Random Number Generator (TRNG), then follow Section 3 to allow mbed TLS to use it.
 
-- If you have a target without a TRNG, but with a non-volatile storage, then read Section 4 for instructions on making mbed TLS use a random seed as entropy. This seed should be separately initialized with a true random number for each device at manufacture time.
+- If you have a target without a TRNG, but with a non-volatile (NV) storage, then read Section 4 for instructions on making mbed TLS use a random seed as entropy. This seed should be separately initialized with a true random number for each device at manufacturing time.
 
 - If you just want to test mbed TLS on your target without implementing either of the above, and having no security at all is acceptable, then go to Section 5.
 
 ## 3. How to provide mbed TLS entropy from a hardware entropy source
 
 ### 3.1 What kind of a source can be added
 
-It is very important that you only add a TRNG as described in this section. For the purposes of this document a device is considered a TRNG only if
-    - It is dedicated to generating entropy to be used in cryptographic applications.
-    - Careful consideration has been given to how much the data generated is subject to adversarial manipulation.
-    - A thorough engineering study has been made to determine how much entropy it can actually provide.
+It is important that you only add a TRNG as described in this section. For the purposes of this document a device is considered a TRNG only if:
 
-For example, an integrated circuit extracting statistically random data from two oscillators of unknown frequencies and independent phases is considered a TRNG, while anything derived from a real time clock is NOT.
+- It is dedicated to generating entropy to be used in cryptographic applications.
+
+- Careful consideration has been given to how much the data generated is subject to adversarial manipulation.
+
+- A thorough engineering study has been made to determine how much entropy it can actually provide.
+
+For example, an integrated circuit extracting statistically random data from two oscillators of unknown frequencies and independent phases is considered a TRNG, but anything derived from a real time clock is NOT.
 
 ### 3.2 How to add an entropy source
 
@@ -42,15 +45,15 @@ The next two sections explain how to do this.
 
 ## How to implement the TRNG API
 
-The implementation of this interface has to be located in the mbed OS directory specific to your target. The name of this directory is of the form `targets/.../TARGET_<target name>`, for example in the case of K64F targets it is `targets/TARGET_Freescale/TARGET_KSDK2_MCUS/TARGET_MCU_K64F/`.
+The implementation of this interface has to be located in the mbed OS directory specific to your target. The name of this directory is of the form `targets/.../TARGET_<target name>`. For example, in the case of K64F targets, it is `targets/TARGET_Freescale/TARGET_KSDK2_MCUS/TARGET_MCU_K64F/`.
 
 ### Data structure
 
 You have to define a structure `trng_s` that holds all the information needed to operate the peripheral and describe its state.
 
-### Initialisation and release
+### Initialization and release
 
-To enable initializing and releasing the peripherial, you must implement the following functions:
+To enable initializing and releasing the peripheral, you must implement the following functions:
 
 ```C
 void trng_init(trng_t *obj);
@@ -65,15 +68,15 @@ The function `trng_get_bytes()` serves as the primary interface to the entropy s
 int trng_get_bytes(trng_t *obj, uint8_t *output, size_t length, size_t *output_length);
 ```
 
-- ``trng_t *obj``: `trng_t` is an alias to `trng_s` and it is the caller's responsibility to initialize it before passing it to this function and release it (with the help of `trng_init()` and `trng_free()` respectively) when it is not required anymore.
+- ``trng_t *obj``: `trng_t` is an alias to `trng_s`, and it is the caller's responsibility to initialize it before passing it to this function and release it (with the help of `trng_init()` and `trng_free()`, respectively) when it is not required anymore.
 
-- ``uint8_t *output``: A pointer to the output buffer. The function should write the entropy it collected to the buffer; mbed TLS then uses this data as entropy. Please consult your board's manual and write only the strongest entropy possible in this buffer.
+- ``uint8_t *output``: a pointer to the output buffer. The function should write the entropy it collected to the buffer; mbed TLS then uses this data as entropy. Please consult your board's manual, and write only the strongest entropy possible in this buffer.
 
-    **Warning:** Although it is possible to fill this buffer without a strong hardware entropy source, we strongly advise against it, because it will nullify any security provided by mbed TLS.
+    **Warning:** Although it is possible to fill this buffer without a strong hardware entropy source, we strongly advise against it because it will nullify any security provided by mbed TLS.
 
-- ``size_t length``: The length of the output buffer. The function shouldn't write more data than this to the output buffer under any circumstances.
+- ``size_t length``: the length of the output buffer. The function shouldn't write more data than this to the output buffer under any circumstances.
 
-- ``size_t *output_length``: The length of the data written into the output buffer. It tells the caller how much entropy has been collected and how many bytes of the output buffer it can use. It should always reflect the exact amount of entropy collected; setting it higher than the actual number of bytes collected is a serious security risk.
+- ``size_t *output_length``: the length of the data written into the output buffer. It tells the caller how much entropy has been collected and how many bytes of the output buffer it can use. It should always reflect the exact amount of entropy collected; setting it higher than the actual number of bytes collected is a serious security risk.
 
 
 ### Indicating the presence of a TRNG
@@ -84,7 +87,7 @@ To indicate that the target has an entropy source, you have to add `TRNG` to the
 "device_has": ["TRNG", etc.]
 ```
 
-## 4. How to implement the Non-Volatile seed entropy source
+## 4. How to implement the non-volatile seed entropy source
 
 If a hardware platform does not have a hardware entropy source to leverage into the entropy pool, alternatives have to be considered. As stated above, a strong entropy source is crucial for security of cryptographic and TLS operations. For platforms that support non-volatile memory, an option is to use the NV seed entropy source that is provided with mbed TLS.
 
@@ -104,7 +107,7 @@ This ensures the entropy pool knows it can use the NV seed entropy source.
 
 You can read more about how to add a macro for your target [here](mbed_targets.md).
 
-By default the platform adaptation functions write/read a seed file called *seedfile*. If you have a system that does not support regular POSIX file operations (mbed OS does not support them by default), the default platform-adaptation functions will not be useful to you and you will need to provide platform-adaptation functions (see next section).
+By default the platform adaptation functions write/read a seed file called *seedfile*. If you have a system that does not support regular POSIX file operations (mbed OS does not support them by default), the default platform-adaptation functions will not be useful to you, and you will need to provide platform-adaptation functions (see next section).
 
 ### 5. Providing platform-adaptation functions
 
@@ -121,19 +124,19 @@ Where `buf` is a pointer to the buffer to read/write a seed, and `buf_len` is th
 
 There are three methods for setting those functions pointers (similar to all platform adaptation functions in mbed TLS):
 
-* `MBEDTLS_PLATFORM_NV_SEED_ALT`. By enabling this macro, the `mbedtls_platform_set_nv_seed(nv_seed_read_func *, nv_seed_write_func*)` function becomes available and lets you set the pointers at run-time.
-* `MBEDTLS_PLATFORM_STD_NV_SEED_READ` and `MBEDTLS_PLATFORM_STD_NV_SEED_WRITE` (requires `MBEDTLS_PLATFORM_NV_SEED_ALT`). By setting these two macros to the relevant function names, the default read/write functions are replaced at compile-time and you still have the option to replace them at run-time as well.
+* `MBEDTLS_PLATFORM_NV_SEED_ALT`. By enabling this macro, the `mbedtls_platform_set_nv_seed(nv_seed_read_func *, nv_seed_write_func*)` function becomes available and lets you set the pointers at runtime.
+* `MBEDTLS_PLATFORM_STD_NV_SEED_READ` and `MBEDTLS_PLATFORM_STD_NV_SEED_WRITE` (requires `MBEDTLS_PLATFORM_NV_SEED_ALT`). By setting these two macros to the relevant function names, the default read/write functions are replaced at compile-time, and you still have the option to replace them at runtime as well.
 * `MBEDTLS_PLATFORM_NV_SEED_READ_MACRO` and `MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO`. By setting these two macros to the relevant functions names, the read/write functions are replaced at compile-time.
 
 ## How to test without entropy sources
 
-Both of the above options are secure if done properly, and depending on the platform may need more or less development work. In some cases it may be necessary to test mbed TLS on boards without entropy. For these kind of scenarios mbed TLS provides a compile time switch to enable testing without entropy sources.
+Both of the above options are secure if done properly, and depending on the platform may need more or less development work. In some cases it may be necessary to test mbed TLS on boards without entropy. For these kinds of scenarios, mbed TLS provides a compile time switch to enable testing without entropy sources.
 
 ### Setting the macros
 
-This option is very dangerous, because compiling with it results in a build that is not secure! You have to let mbed TLS know that you are using it deliberately and you are aware of the consequences. That is why you have to turn off any entropy sources explicitly first.
+This option is very dangerous because compiling with it results in a build that is not secure! You have to let mbed TLS know that you are using it deliberately and you are aware of the consequences. That is why you have to turn off any entropy sources explicitly first.
 
-Since it is a very dangerous option and no one should use it in production, we recommend to limit its scope as much as possible; you should apply these settings to the application specific configuration file, instead of the target related configuration as we did it above. You can read more about how to add a macro for your application [here](config_system.md).
+Because it is a very dangerous option and no one should use it in production, we recommend you limit its scope as much as possible; you should apply these settings to the application specific configuration file, instead of the target related configuration as we did it above. You can read more about how to add a macro for your application [here](config_system.md).
 
 To turn the unsafe testing mode on:
 
@@ -145,4 +148,3 @@ To turn the unsafe testing mode on:
 
 ### Warning!
 _**The `MBEDTLS_TEST_NULL_ENTROPY` option nullifies any security provided by mbed TLS! It is there exclusively for testing purposes and should never be used in production. It cannot be stressed enough: a library built with this option does not provide any security whatsoever!**_
-