..
    Copyright 2019 NXP


.. _mbedTLS-alt:

Introduction on mbedTLS ALT Implementation
============================================

MbedTLS ALT implementation allows mbedTLS stack use the secure element
access using SSS layer. Crypto operations performed during TLS handshake
between client and server are performed using the secure element.


Using mbedTLS ALT
----------------------

For reference, let's look at the :file:`sss/ex/mbedtls/ex_sss_ssl2.c`.
The important sections of the file are.

Here we initialize the keys and relevent objects.

.. literalinclude:: ../../../ex/mbedtls/ex_sss_ssl2.c
    :language: c
    :dedent: 8
    :start-after: /* doc+:initialize-key-objs */
    :end-before: /* doc-:initialize-key-objs */

Here, we tell mbedTLS to use the root CA public key from the SE.

.. literalinclude:: ../../../ex/mbedtls/ex_sss_ssl2.c
    :language: c
    :dedent: 8
    :start-after: /* doc+:use-public-key-from-se */
    :end-before: /* doc-:use-public-key-from-se */

Here, get certificate in DER format from the SE, and then convert it to PEM and share it with the mbedTLS stack.

.. literalinclude:: ../../../ex/mbedtls/ex_sss_ssl2.c
    :language: c
    :dedent: 12
    :start-after: /* doc+:load-certificate-from-se */
    :end-before: /* doc-:load-certificate-from-se */

Here, we tell mbedTLS to use the device private key from the SE, generally for signing any contents.

.. literalinclude:: ../../../ex/mbedtls/ex_sss_ssl2.c
    :language: c
    :dedent: 8
    :start-after: /* doc+:set-handle-to-use-private-key-from-se */
    :end-before: /* doc-:set-handle-to-use-private-key-from-se */

Here, we tell mbedTLS to use the private key from the SE for ECDH handshake.

.. literalinclude:: ../../../ex/mbedtls/ex_sss_ssl2.c
    :language: c
    :dedent: 12
    :start-after: /* doc+:use-private-key-for-ecdh */
    :end-before: /* doc-:use-private-key-for-ecdh */


Testing
-------

Building mbedTLS SSL/DTLS server for testing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Build mbedTLS server using the VS solution:
CMake configurations:
- ``RTOS_Default``: ON
- ``WithHostCrypto_MBEDTLS``: ON
- ``WithmbedTLS_ALT_SSS``: ON

- Project: ``mbedtls_ex_orig_ssl_server2`` / ``mbedtls_ex_orig_dtls_server``

Building mbedTLS SSL/DTLS client (with SSS-APIs integration)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Build mbedTLS client using the VS solution:
CMake configurations:
- ``RTOS_Default``: ON
- ``WithHostCrypto_MBEDTLS``: ON
- ``WithmbedTLS_ALT_SSS``: ON

- Project: ``mbedtls_ex_sss_ssl2_client`` / ``mbedtls_ex_sss_dtls_client``

Testings mbedTLS ALT
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Directory ``simw-top\sss\plugin\mbedtls\scripts`` contains test scripts for
starting mbedTLS server and client applications with different cipher suites.
Before executing some test scripts, the secure element must first be
provisioned.

1)  Complete :numref:`cli-doc-pre-steps` :ref:`cli-doc-pre-steps`


#)  Provision secure element using python scripts in directory
    ``simw-top\sss\plugin\mbedtls\scripts``.
    Run the following commands in virtual environment:

    To provision secure element for ECC
        ``python3 create_and_provision_ecc_keys.py <keyType> <connection_type> <connection_string> <iot_se (optional. Default - se050)> <auth (optional. Default - None)> <auth_key>``

    To configure secure element for RSA
        ``python3 create_and_provision_rsa_keys.py <keyType> <connection_type> <connection_string> <auth (optional. Default - None)> <auth_key>``

    To see possible values of input arguments, run without any parameters
        ``create_and_provision_ecc_keys.py.`` or ``create_and_provision_rsa_keys.py``

    .. note::
        Once provisioning is done the virtual environment is not needed anymore.

#)  Starting mbedTLS SSL client and server applications::

        python3 start_ssl2_server.py <ec_curve>/<rsa_type>
        python3 start_ssl2_client.py <ec_curve>/<rsa_type> <cipher suite> <connection_string>

#)  Starting mbedTLS DTLS client and server applications::

        python3 start_dtls_server.py <ec_curve>/<rsa_type>
        python3 start_dtls_client.py <ec_curve>/<rsa_type> <cipher suite> <connection_string>

    .. note::

        Ensure that ``ec_curve``/``rsa_type`` used in server and client
        applications is the same as used while provisioning the SE in step 2.

mbedTLS ALT APIs
----------------------

.. doxygengroup:: ax_mbed_tls
    :no-link:
    :members:
    :protected-members:
    :private-members:
    :undoc-members: