8.2. 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.

8.2.1. SE05X usage in TLS handshake (ECC Ciphersuites)

SE05X is used for following operations during TLS handshake

  1. Verification using root CA pub key (root CA public key provisioned in SE05X)

  2. Calculate shared key using sss_derive_key_dh (only for ECDH cipher suites. For ECDHE, ecc key and shared secret are generated on host).

  3. Sign handshake messages using provisioned client key.

  4. Optional - All public key ECDSA verify operation.

8.2.2. SE05X usage in TLS handshake (RSA Ciphersuites)

SE05X is used for following operations during TLS handshake

  1. Verification using root CA pub key (root CA public key provisioned in SE05X).

  2. Sign handshake messages using provisioned client key.

  3. Optional - All public key ECDSA verify operation. Public key is set during TLS handshake.

8.2.3. Using SE05X for all Public key ECDSA verify operation

With default mbedtls config file, SE05X is used only for Root CA public key verify operation. To use secure element for all public key ecdsa verify operation, enable MBEDTLS_ECDSA_VERIFY_ALT in mbedtls config file.

This feature will add some limitations as explained below.

  1. NVM writes will be observed when public key is set in secured element during TLS handshake.

  2. NVM writes can be avoided by overwriting the existing keys without deleting the last created key. But this limits the number of key types that can be used for handshake due to limited transient memory.

To avoid the NVM writes, modify the function mbedtls_ecdsa_verify in sss/plugin/mbedtls/ecdsa_verify_alt.c. Create the required key type object in your application and use this key object in function mbedtls_ecdsa_verify for verify operation. Do not delete the keyobject at the end of verify operation.

Also when MBEDTLS_ECDSA_VERIFY_ALT is enabled, set the sss key store from application using api sss_mbedtls_set_sss_keystore. Refer example sss/ex/mbedtls/ex_sss_ssl2.c.

sss_mbedtls_set_sss_keystore(&pCtx->ks);

8.2.4. Using mbedTLS ALT

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

Here we initialize the keys and relevent objects.


/* pex_sss_demo_tls_ctx->obj will have the private key handle */
status = sss_key_object_init(&pex_sss_demo_tls_ctx->obj, &pCtx->ks);
if (status != kStatus_SSS_Success) {
    printf(" sss_key_object_init for keyPair Failed...\n");
    return kStatus_SSS_Fail;
}

status = sss_key_object_get_handle(&pex_sss_demo_tls_ctx->obj, SSS_KEYPAIR_INDEX_CLIENT_PRIVATE);
if (status != kStatus_SSS_Success) {
    printf(" sss_key_object_get_handle  for keyPair Failed...\n");
    return kStatus_SSS_Fail;
}

/*
* All ecdsa verification is done using the esdsa_alt file. No need to associate the root ca pub key.
*/
ined(MBEDTLS_ECDSA_VERIFY_ALT)
/* pex_sss_demo_tls_ctx->pub_obj will have the root CA public key */
status = sss_key_object_init(&pex_sss_demo_tls_ctx->pub_obj, &pCtx->ks);
if (status != kStatus_SSS_Success) {
    printf(" sss_key_object_init for Pub key Failed...\n");
    return kStatus_SSS_Fail;
}

status = sss_key_object_get_handle(&pex_sss_demo_tls_ctx->pub_obj, SSS_PUBKEY_INDEX_CA);
if (status != kStatus_SSS_Success) {
    printf(" sss_key_object_get_handle  for extPubkey Failed...\n");
    return kStatus_SSS_Fail;
}


/* pex_sss_demo_tls_ctx->dev_cert will have the our device certificate */
status = sss_key_object_init(&pex_sss_demo_tls_ctx->dev_cert, &pCtx->ks);
if (status != kStatus_SSS_Success) {
    printf(" sss_key_object_init for Pub key Failed...\n");
    return kStatus_SSS_Fail;
}
status = sss_key_object_get_handle(&pex_sss_demo_tls_ctx->dev_cert, SSS_CERTIFICATE_INDEX);
if (status != kStatus_SSS_Success) {
    printf(" sss_key_object_get_handle  for client Cert Failed...\n");
    return kStatus_SSS_Fail;
}

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

mbedtls_pk_free(&cacert.pk);
ret = sss_mbedtls_associate_pubkey(&cacert.pk, &pex_sss_demo_tls_ctx->pub_obj);

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

size_t KeyBitLen = SIZE_CLIENT_CERTIFICATE * 8;
size_t KeyByteLen = SIZE_CLIENT_CERTIFICATE;

ret_code = sss_key_store_get_key(
    &pCtx->ks, &pex_sss_demo_tls_ctx->dev_cert, aclient_cer, &KeyByteLen, &KeyBitLen);

ret = mbedtls_x509_crt_parse_der(&clicert,
    (const unsigned char *)aclient_cer,
    sizeof(aclient_cer));
if ((ret_code == kStatus_SSS_Success) && (ret == 0)) {
    client_certificate_loaded = 1;
}

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

sss_mbedtls_associate_keypair(&pkey, &pex_sss_demo_tls_ctx->obj);

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

sss_mbedtls_associate_ecdhctx(ssl.handshake, &pex_sss_demo_tls_ctx->obj, &pCtx->host_ks);

8.2.5. Testing

8.2.5.1. Building mbedTLS SSL/DTLS server for testing

Build mbedTLS server using the VS solution: CMake configurations: - RTOS_Default: ON - SSS_HAVE_HOSTCRYPTO_MBEDTLS: ON - SSS_HAVE_MBEDTLS_ALT_SSS: ON

  • Project: mbedtls_ex_orig_ssl_server2 / mbedtls_ex_orig_dtls_server

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

Build mbedTLS client using the VS solution: CMake configurations: - RTOS_Default: ON - SSS_HAVE_HOSTCRYPTO_MBEDTLS: ON - SSS_HAVE_MBEDTLS_ALT_SSS: ON

  • Project: mbedtls_ex_sss_ssl2_client / mbedtls_ex_sss_dtls_client

8.2.5.3. 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 Section 9.3 Steps needed before running ssscli tool

  2. 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.

  3. 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>
    
  4. 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.

8.2.6. SE050 Performance Measurements

The following measurements are performed on K-64 board with SE050 connected via T10I2C.

8.2.6.1. TLS1.2 using ECC Nist256 Keys (Using MbedTLS Alt)

Ciphersuite used for TLS - TLS-ECDH-ECDSA-WITH-AES-128-CBC-SHA

Read the numbers as MIN - AVG - MAX milliseconds.

Operation

SE05X (Auth - None)

K64 (with O0)

K64 (with O2)

Server Certificate Verification

49 - 49.6 - 50

1885 - 1885.4 - 1887

754 - 754.2 - 755

DH key generation

54 - 54 - 54

911 - 913.8 - 915

363 - 364.4 - 366

Sign Operation

50 - 51.8 - 59

952 - 956 - 959

382 - 384 - 386

sss_derive_key_dh is used for DH calulation. Time measured includes - set other party public key on host, Derive key, Get DH key from host.

8.2.6.2. TLS1.2 using RSA2048 (CRT) Keys (Using MbedTLS Alt)

Ciphersuite used for TLS - TLS-ECDHE-RSA-WITH-CHACHA20-POLY1305-SHA256

Read the numbers as MAX - AVG - MIN milliseconds.

Operation

SE05X (Auth - None)

K64 (with O0)

K64 (with O2)

Server Certificate Verification

49 - 49.8 - 50

172 - 172.2 - 172

26 - 26.8 - 27

DH key generation

NA - NA - NA

3151 - 3157.4 - 3179

813 - 834.6 - 847

Sign Operation

102 - 102.4 - 103

8450 - 8521 - 8571

1143 - 1152 - 1164

Secp521r1 key is used for DH.

8.2.7. mbedTLS ALT APIs

group ax_mbed_tls

mbedTLS ALT implementation.

Unnamed Group

int sss_mbedtls_associate_keypair(mbedtls_pk_context *pkey, sss_object_t *pkeyObject)

Associate a keypair provisioned in the secure element for subsequent operations.

Description

Implementation of key association between NXP Secure Element and mbedtls.

History

1.0 30-jan-2018 : Initial version

Return

0 if successful, or 1 if unsuccessful

Parameters
  • [out] pkey: Pointer to the mbedtls_pk_context which will be associated with data corresponding to the key_index

  • [in] pkeyObject: The object that we are going to be use.

int sss_mbedtls_associate_pubkey(mbedtls_pk_context *pkey, sss_object_t *pkeyObject)

Associate a pubkey provisioned in the secure element for subsequent operations.

Return

0 if successful, or 1 if unsuccessful

Parameters
  • [out] pkey: Pointer to the mbedtls_pk_context which will be associated with data corresponding to the key index

  • [in] pkeyObject: The object that we are going to be use.

int sss_mbedtls_associate_ecdhctx(mbedtls_ssl_handshake_params *handshake, sss_object_t *pkeyObject, sss_key_store_t *hostKs)

Update ECDSA HandShake key with given inded.

Return

0 if successful, or 1 if unsuccessful

Parameters
  • [inout] handshake: Pointer to the mbedtls_ssl_handshake_params which will be associated with data corresponding to the key index

  • [in] pkeyObject: The object that we are going to be use.

  • [in] hostKs: Keystore to host for session key.