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

6.2.1. 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;
}

/* pex_sss_demo_tls_ctx->obj will have the private key handle */
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;
}

/* pex_sss_demo_tls_ctx->obj will have the public key of couter part */
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 public key from the SE.

// for private key, we use the KEY from 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 public 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 public key from the SE for ECDH handshake.

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

6.2.2. Testing

6.2.2.1. 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 / ex_mbedtls_origin_dtls_server

6.2.2.2. 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 / mbedtls_ex_sss_dtls

6.2.2.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 7.3 Steps needed before running ssscli tool

  2. Provision secure element using batch scripts in directory simw-top\sss\plugin\mbedtls\scripts. Run the following commands in virtual environment:

    To configure secure element for ECC

    windowsProvisionEC.bat <ec_curve> jrcpv2/vcom 127.0.0.1:8050/COM#

    To configure secure element for RSA

    windowsProvisionRSA.bat <rsa_type> jrcpv2/vcom 127.0.0.1:8050/COM#

    To see usage, run without any parameters

    windowsProvisionRSA.bat or windowsProvisionEC.bat

    Note

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

  3. Starting mbedTLS SSL client and server applications:

    start_ssl2_server.bat <ec_curve>/<rsa_type>
    start_ssl2_client.bat <ec_curve>/<rsa_type> <cipher suite> 127.0.0.1:8050/COM#
    
  4. Starting mbedTLS DTLS client and server applications:

    start_dtls_server.bat <ec_curve>/<rsa_type>
    start_dtls_client.bat <ec_curve>/<rsa_type> <cipher suite> 127.0.0.1:8050/COM#
    

    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.

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

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.