espressif/esp-idf
1
0
Fork 1
mirror of https://github.com/espressif/esp-idf.git synced 2025-07-30 02:37:19 +02:00
Code Issues Packages Projects Releases Wiki Activity

fix(docs): update for changes in provisioning security2 scheme

Browse Source
This commit is contained in:
Mahavir Jain
2025-03-03 10:47:45 +05:30
parent c18de74f77
commit d7095714ad
2 changed files with 58 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
docs/en/api-reference/provisioning/provisioning.rst
View File

@ -251,14 +251,56 @@ Details about the Security 2 scheme are shown in the below sequence diagram:
device verifies this M1 with the M1 obtained from Client"];
DEVICE -> DEVICE [label = "Verification\nToken", leftnote = "
Device generate device_proof M2 = H(A, M, K)"];
DEVICE -> DEVICE [label = "Initialization\nVector", leftnote = "dev_rand = gen_16byte_random()
This random number is to be used for AES-GCM operation
for encryption and decryption of the data using the shared secret"];
DEVICE -> DEVICE [label = "Initialization\nVector", leftnote = "dev_rand = gen_12byte_iv()
This random number is formed as session_id (8byte) + counter (4byte)
to be used for AES-GCM operation for encryption and decryption of
the data using the shared secret"];
DEVICE -> CLIENT [label = "SessionResp1(device_proof M2, dev_rand)"];
CLIENT -> CLIENT [label = "Verify Device", rightnote = "Client calculates device proof M2 as M2 = H(A, M, K)
client verifies this M2 with M2 obtained from device"];
}
Security 2 AES-GCM IV Handling
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Security 2 scheme uses AES-GCM for encryption and decryption of the data. The initialization vector (IV) consists of an 8-byte session ID and a 4-byte counter, for a total of 12 bytes. The counter starts at 1 and is incremented after each encryption/decryption operation on both the device and the client.
.. seqdiag::
:caption: Security 2 AES-GCM IV Handling
:align: center
seqdiag security2_gcm {
activation = none;
node_width = 80;
node_height = 60;
edge_length = 550;
span_height = 5;
default_shape = roundedbox;
default_fontsize = 12;
CLIENT [label = "Client\n(PhoneApp)"];
DEVICE [label = "Device\n(ESP)"];
=== Security 2 AES-GCM IV Handling ===
DEVICE -> DEVICE [label = "Initialize\nIV", leftnote = "Initial IV = session_id (8 bytes) || counter (4 bytes)
session_id = random 8 byte value
counter = 0x1 (stored as big-endian)"];
DEVICE -> CLIENT [label = "Send 12-byte IV to client (session_id || counter)"];
CLIENT -> CLIENT [label = "Initialize\nIV", rightnote = "Set initial IV from device:
- session_id (8 bytes from device)
- counter = 0x1"];
CLIENT -> DEVICE [label = "First Encrypted Command using initial IV"];
CLIENT -> CLIENT [label = "Increment\nCounter", rightnote = "After first command:
- Increment counter to 0x2
- New IV = session_id || counter"];
DEVICE -> DEVICE [label = "Increment\nCounter", leftnote = "Before first response:
- Increment counter to 0x2
- New IV = session_id || counter"];
DEVICE -> CLIENT [label = "Encrypted Response using updated IV"];
}
Sample Code
>>>>>>>>>>>

14
docs/en/api-reference/provisioning/wifi_provisioning.rst
View File

@ -217,7 +217,19 @@ Once connected to the device, the provisioning-related protocomm endpoints can b
- http://<mdns-hostname>.local/proto-ver
- the endpoint for retrieving version info
Immediately after connecting, the client application may fetch the version/capabilities information from the ``proto-ver`` endpoint. All communications to this endpoint are unencrypted, hence necessary information, which may be relevant for deciding compatibility, can be retrieved before establishing a secure session. The response is in JSON format and looks like : ``prov: { ver: v1.1, cap: [no_pop] }, my_app: { ver: 1.345, cap: [cloud, local_ctrl] },....``. Here label ``prov`` provides provisioning service version ``ver`` and capabilities ``cap``. For now, only the ``no_pop`` capability is supported, which indicates that the service does not require proof of possession for authentication. Any application-related version or capabilities are given by other labels, e.g., ``my_app`` in this example. These additional fields are set using :cpp:func:`wifi_prov_mgr_set_app_info()`.
Immediately after connecting, the client application may fetch the version/capabilities information from the ``proto-ver`` endpoint. All communications to this endpoint are unencrypted, hence necessary information, which may be relevant for deciding compatibility, can be retrieved before establishing a secure session. The response is in JSON format and looks like : ``prov: { ver: v1.1, sec_ver: 1, sec_patch_ver: 0, cap: [no_pop] }, my_app: { ver: 1.345, cap: [cloud, local_ctrl] },....``.
Here label ``prov`` provides:
- provisioning service version ``ver``
- security version ``sec_ver``
- security patch version ``sec_patch_ver`` (default is 0)
- capabilities ``cap``
For now, only the ``no_pop`` capability is supported, which indicates that the service does not require proof of possession for authentication. Any application-related version or capabilities are given by other labels, e.g., ``my_app`` in this example. These additional fields are set using :cpp:func:`wifi_prov_mgr_set_app_info()`.
.. important::
Client must take into account both the ``sec_ver`` and ``sec_patch_ver`` fields, as these are used to determine the security scheme to be used for the session establishment.
User side applications need to implement the signature handshaking required for establishing and authenticating secure protocomm sessions as per the security scheme configured for use, which is not needed when the manager is configured to use protocomm security 0.