Skip to content
This repository was archived by the owner on Apr 7, 2026. It is now read-only.

Commit a27256a

Browse files
zhen9910zhen9910
committed
Create user-defined ciphersuites.md
1 parent 3f7f54e commit a27256a

2 files changed

Lines changed: 80 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,3 +40,8 @@ The Azure RTOS and Azure Sphere better together sample can be found at:
4040
https://github.com/Azure-Samples/Azure-RTOS-on-Azure-Sphere-Mediatek-MT3620
4141

4242
This sample demonstrates how Azure Sphere and Azure RTOS are able to run together on the MediaTek MT3620 Development Kit.
43+
44+
## User-defined Crypto Ciphersuites
45+
46+
This [guide](./user-defined%20ciphersuites.md) demonstrates how to implement user-defined crypto ciphersuites used by Azure RTOS NetX Secure TLS stack.
47+

‎user-defined ciphersuites.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# User-defined Crypto Ciphersuites Used by Azure RTOS NetX Secure
2+
3+
## Introduction
4+
5+
[Azure RTOS NetX Crypto](https://learn.microsoft.com/en-us/azure/rtos/netx/netx-crypto/chapter1) is the default crypto ciphersuite used by [Azure RTOS NetX Secure](https://learn.microsoft.com/en-us/azure/rtos/netx-duo/netx-secure-tls/chapter1) TLS stack. If clients want to use different crypto algorithm implementation, such as hardware security engine, TF-M PSA, or PKCS#11 based crypto methods, this user guide will show how to implement user-defined crypto ciphersuite and utilize it for Azure RTOS NetX Secure TLS stack.
6+
7+
## General Process
8+
9+
There are four steps to implement and utilize a user-defined crypto ciphersuite.
10+
11+
1. Declare a [NX_CRYPTO_METHOD](https://github.com/azure-rtos/netxduo/blob/a69a06e35da0ac763b363388f555b508b0cd84b7/crypto_libraries/inc/nx_crypto.h#L320) struct for your crypto algorithm, which contains initialization, cleanup and crypto operations function pointers for the crypto method in use.
12+
13+
2. Define initialization, cleanup and crypto operation functions for this crypto method.
14+
15+
3. Define a struct to save meta data such as scrtch buffer, algotithm id, etc, which will be passed into above functions as as input parameter.
16+
17+
4. Add this newly defined `NX_CRYPTO_METHOD` into tls crypto array `_nx_azure_iot_tls_supported_crypto[]`, which will be automatically initialized during tls session creation and then utilized by NetX Secure TLS stack.
18+
19+
## Example
20+
21+
[The STMicroelectronics B-U585I-IOT02A sample project](https://github.com/azure-rtos/samples/releases/download/v6.1_rel/Azure_RTOS_6.1_B-U585I-IOT02A_IAR_Samples_Beta_2021_10_01.zip) implements TFM-PSA based ECDSA crypto ciphersuite for TLS device authentication. We will use it an an example to demonstrate the above process.
22+
23+
<p>
24+
All the changed files are under the path <em>B-U585I-IOT02A\Projects\B-U585I-IOT02A\Applications\TFM\TFM_Appli\NonSecure\Projects\B-U585I-IOT02A\Applications\TFM\TFM_Appli\NonSecure</em>.
25+
</p>
26+
27+
1. In <em>psa_crypto_ciphersuites/nx_crypto_psa_crypto_ciphersuites.c</em>, declare NX_CRYPTO_METHOD struct `crypto_method_ecdsa_psa_crypto` for PSA based ECDSA crypto method.
28+
29+
<pre>
30+
NX_CRYPTO_METHOD crypto_method_ecdsa_psa_crypto =
31+
{
32+
NX_CRYPTO_DIGITAL_SIGNATURE_ECDSA, /* ECDSA crypto algorithm name */
33+
0, /* Key size in bits */
34+
0, /* IV size in bits */
35+
0, /* ICV size in bits, not used */
36+
0, /* Block size in bytes */
37+
sizeof(NX_CRYPTO_ECDSA_PSA_CRYPTO), /* Metadata size in bytes */
38+
_nx_crypto_method_ecdsa_psa_crypto_init, /* ECDSA initialization routine */
39+
_nx_crypto_method_ecdsa_psa_crypto_cleanup, /* ECDSA cleanup routine */
40+
_nx_crypto_method_ecdsa_psa_crypto_operation, /* ECDSA operation */
41+
};
42+
</pre>
43+
44+
2. In <em>psa_crypto_ciphersuites/nx_crypto_ecdsa_psa_crypto.c</em>, define initialization, cleanup and crypto operations for this crypto method.
45+
- `_nx_crypto_method_ecdsa_psa_crypto_init()` for parameter check and metadata initialization;
46+
- `_nx_crypto_method_ecdsa_psa_crypto_cleanup()` for metadata clean up;
47+
- `_nx_crypto_method_ecdsa_psa_crypto_operation()` to perform ECDSA operations, including ECDSA signature, verify, EC curve setting.
48+
49+
3. In <em>psa_crypto_ciphersuites/nx_crypto_ecdsa_psa_crypto.h</em>, define a struct 'NX_CRYPTO_ECDSA_PSA_CRYPTO' to save metadata used by crypto functions, such as scrtch buffer, psa key handle, etc.
50+
51+
4. In <em>Src/nx_azure_iot_ciphersuites.c</em>, add this new defined NX_CRYPTO_METHOD `crypto_method_ecdsa_psa_crypto` into `_nx_azure_iot_tls_supported_crypto[]`.
52+
53+
<pre>
54+
const NX_CRYPTO_METHOD *_nx_azure_iot_tls_supported_crypto[] =
55+
{
56+
&crypto_method_hmac,
57+
&crypto_method_hmac_sha256,
58+
&crypto_method_tls_prf_sha256,
59+
&crypto_method_sha256,
60+
&crypto_method_aes_cbc_128,
61+
&crypto_method_rsa,
62+
#ifdef NX_SECURE_ENABLE_ECC_CIPHERSUITE
63+
#ifdef ENABLE_PSA_CRYPTO_CIPHERSUITES
64+
<b>&crypto_method_ecdsa_psa_crypto</b>,
65+
#else
66+
&crypto_method_ecdsa,
67+
#endif
68+
&crypto_method_ecdhe,
69+
&crypto_method_ec_secp384,
70+
&crypto_method_ec_secp256,
71+
#endif /* NX_SECURE_ENABLE_ECC_CIPHERSUITE */
72+
};
73+
</pre>
74+
75+
With these changes, the user-defined PSA based ECDSA crypto method will be used by NX secure TLS stack.

0 commit comments

Comments
 (0)