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
Verification using root CA pub key (root CA public key provisioned in SE05X)
Calculate shared key using sss_derive_key_dh (only for ECDH cipher suites. For ECDHE, ecc key and shared secret are generated on host).
Sign handshake messages using provisioned client key.
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
Verification using root CA pub key (root CA public key provisioned in SE05X).
Sign handshake messages using provisioned client key.
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.
NVM writes will be observed when public key is set in secured element during TLS handshake.
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.
*/
#if !defined(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;
}
#endif
/* 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.
Complete Section 9.3 Steps needed before running ssscli tool
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.
orcreate_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.
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.
- Description
Implementation of key association between NXP Secure Element and mbedtls.
- History
1.0 30-jan-2018 : Initial version
Functions
-
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.
-
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.