Merge branch 'feature/sec1_sec2_support_esp_local_ctrl_example' into 'master'

esp_local_ctrl: added sec1 and sec2 support in esp_local_ctrl example

See merge request espressif/esp-idf!20492

docs/en/api-reference/protocols/esp_local_ctrl.rst

@@ -27,7 +27,7 @@ Initialization of the **esp_local_ctrl** service over BLE transport is performed
             .proto_sec = {
                 .version = PROTOCOM_SEC0,
                 .custom_handle = NULL,
-                .pop = NULL,
+                .sec_params = NULL,
             },
             .handlers = {
                 /* User defined handler functions */
@@ -73,7 +73,7 @@ Similarly for HTTPS transport:
             .proto_sec = {
                 .version = PROTOCOM_SEC0,
                 .custom_handle = NULL,
-                .pop = NULL,
+                .sec_params = NULL,
             },
             .handlers = {
                 /* User defined handler functions */

examples/protocols/esp_local_ctrl/README.md

@@ -31,16 +31,17 @@ Sample output:
 After you've tested the name resolution, run:
 
 ```
-python scripts/esp_local_ctrl.py --sec_ver 0
+python scripts/esp_local_ctrl.py --sec_ver 2 --sec2_username wifiprov --sec2_pwd abcd1234
 ```
 Sample output:
 
 ```
-python scripts/esp_local_ctrl.py --sec_ver 0
+python scripts/esp_local_ctrl.py --sec_ver 2 --sec2_username wifiprov --sec2_pwd abcd1234
 
-==== Acquiring properties information ====
+++++ Connecting to my_esp_ctrl_device.local++++
 
-==== Acquired properties information ====
+==== Starting Session ====
+==== Session Established ====
 
 ==== Available Properties ====
 S.N. Name             Type       Flags            Value

examples/protocols/esp_local_ctrl/main/Kconfig.projbuild

@@ -0,0 +1,44 @@
+menu "Example Configuration"
+
+    choice EXAMPLE_PROTOCOMM_SECURITY_VERSION
+        bool "Protocomm security version"
+        default EXAMPLE_PROTOCOMM_SECURITY_VERSION_2
+        help
+            Local Control component offers 3 security versions.
+            The example offers a choice between security version 0, 1 and 2.
+
+        config EXAMPLE_PROTOCOMM_SECURITY_VERSION_0
+            bool "Security Version 0"
+            select ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_0
+
+        config EXAMPLE_PROTOCOMM_SECURITY_VERSION_1
+            bool "Security version 1"
+            select ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_1
+
+        config EXAMPLE_PROTOCOMM_SECURITY_VERSION_2
+            bool "Security version 2"
+            select ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_2
+    endchoice
+
+    choice EXAMPLE_PROTOCOMM_SEC2_MODE
+        bool "Security version 2 mode"
+        depends on EXAMPLE_PROTOCOMM_SECURITY_VERSION_2
+        default EXAMPLE_PROTOCOMM_SEC2_DEV_MODE
+
+        config EXAMPLE_PROTOCOMM_SEC2_DEV_MODE
+            bool "Security version 2 development mode"
+            depends on EXAMPLE_PROTOCOMM_SECURITY_VERSION_2
+            help
+                This enables the development mode for
+                security version 2.
+                Please note that this mode is NOT recommended for production purpose.
+
+        config EXAMPLE_PROTOCOMM_SEC2_PROD_MODE
+            bool "Security version 2 production mode"
+            depends on EXAMPLE_PROTOCOMM_SECURITY_VERSION_2
+            help
+                This enables the production mode for
+                security version 2.
+    endchoice
+
+endmenu

examples/protocols/esp_local_ctrl/main/esp_local_ctrl_service.c

@@ -25,6 +25,72 @@ static const char *TAG = "control";
 
 #define SERVICE_NAME "my_esp_ctrl_device"
 
+#if CONFIG_EXAMPLE_PROTOCOMM_SECURITY_VERSION_2
+#if CONFIG_EXAMPLE_PROTOCOMM_SEC2_DEV_MODE
+#define EXAMPLE_PROTOCOMM_SEC2_USERNAME          "wifiprov"
+#define EXAMPLE_PROTOCOMM_SEC2_PWD               "abcd1234"
+
+/* This salt,verifier has been generated for username = "localctrl" and password = "abcd1234"
+ * IMPORTANT NOTE: For production cases, this must be unique to every device
+ * and should come from device manufacturing partition.*/
+static const char sec2_salt[] = {
+    0x03, 0x6e, 0xe0, 0xc7, 0xbc, 0xb9, 0xed, 0xa8, 0x4c, 0x9e, 0xac, 0x97, 0xd9, 0x3d, 0xec, 0xf4
+};
+
+static const char sec2_verifier[] = {
+    0x7c, 0x7c, 0x85, 0x47, 0x65, 0x08, 0x94, 0x6d, 0xd6, 0x36, 0xaf, 0x37, 0xd7, 0xe8, 0x91, 0x43,
+    0x78, 0xcf, 0xfd, 0x61, 0x6c, 0x59, 0xd2, 0xf8, 0x39, 0x08, 0x12, 0x72, 0x38, 0xde, 0x9e, 0x24,
+    0xa4, 0x70, 0x26, 0x1c, 0xdf, 0xa9, 0x03, 0xc2, 0xb2, 0x70, 0xe7, 0xb1, 0x32, 0x24, 0xda, 0x11,
+    0x1d, 0x97, 0x18, 0xdc, 0x60, 0x72, 0x08, 0xcc, 0x9a, 0xc9, 0x0c, 0x48, 0x27, 0xe2, 0xae, 0x89,
+    0xaa, 0x16, 0x25, 0xb8, 0x04, 0xd2, 0x1a, 0x9b, 0x3a, 0x8f, 0x37, 0xf6, 0xe4, 0x3a, 0x71, 0x2e,
+    0xe1, 0x27, 0x86, 0x6e, 0xad, 0xce, 0x28, 0xff, 0x54, 0x46, 0x60, 0x1f, 0xb9, 0x96, 0x87, 0xdc,
+    0x57, 0x40, 0xa7, 0xd4, 0x6c, 0xc9, 0x77, 0x54, 0xdc, 0x16, 0x82, 0xf0, 0xed, 0x35, 0x6a, 0xc4,
+    0x70, 0xad, 0x3d, 0x90, 0xb5, 0x81, 0x94, 0x70, 0xd7, 0xbc, 0x65, 0xb2, 0xd5, 0x18, 0xe0, 0x2e,
+    0xc3, 0xa5, 0xf9, 0x68, 0xdd, 0x64, 0x7b, 0xb8, 0xb7, 0x3c, 0x9c, 0xfc, 0x00, 0xd8, 0x71, 0x7e,
+    0xb7, 0x9a, 0x7c, 0xb1, 0xb7, 0xc2, 0xc3, 0x18, 0x34, 0x29, 0x32, 0x43, 0x3e, 0x00, 0x99, 0xe9,
+    0x82, 0x94, 0xe3, 0xd8, 0x2a, 0xb0, 0x96, 0x29, 0xb7, 0xdf, 0x0e, 0x5f, 0x08, 0x33, 0x40, 0x76,
+    0x52, 0x91, 0x32, 0x00, 0x9f, 0x97, 0x2c, 0x89, 0x6c, 0x39, 0x1e, 0xc8, 0x28, 0x05, 0x44, 0x17,
+    0x3f, 0x68, 0x02, 0x8a, 0x9f, 0x44, 0x61, 0xd1, 0xf5, 0xa1, 0x7e, 0x5a, 0x70, 0xd2, 0xc7, 0x23,
+    0x81, 0xcb, 0x38, 0x68, 0xe4, 0x2c, 0x20, 0xbc, 0x40, 0x57, 0x76, 0x17, 0xbd, 0x08, 0xb8, 0x96,
+    0xbc, 0x26, 0xeb, 0x32, 0x46, 0x69, 0x35, 0x05, 0x8c, 0x15, 0x70, 0xd9, 0x1b, 0xe9, 0xbe, 0xcc,
+    0xa9, 0x38, 0xa6, 0x67, 0xf0, 0xad, 0x50, 0x13, 0x19, 0x72, 0x64, 0xbf, 0x52, 0xc2, 0x34, 0xe2,
+    0x1b, 0x11, 0x79, 0x74, 0x72, 0xbd, 0x34, 0x5b, 0xb1, 0xe2, 0xfd, 0x66, 0x73, 0xfe, 0x71, 0x64,
+    0x74, 0xd0, 0x4e, 0xbc, 0x51, 0x24, 0x19, 0x40, 0x87, 0x0e, 0x92, 0x40, 0xe6, 0x21, 0xe7, 0x2d,
+    0x4e, 0x37, 0x76, 0x2f, 0x2e, 0xe2, 0x68, 0xc7, 0x89, 0xe8, 0x32, 0x13, 0x42, 0x06, 0x84, 0x84,
+    0x53, 0x4a, 0xb3, 0x0c, 0x1b, 0x4c, 0x8d, 0x1c, 0x51, 0x97, 0x19, 0xab, 0xae, 0x77, 0xff, 0xdb,
+    0xec, 0xf0, 0x10, 0x95, 0x34, 0x33, 0x6b, 0xcb, 0x3e, 0x84, 0x0f, 0xb9, 0xd8, 0x5f, 0xb8, 0xa0,
+    0xb8, 0x55, 0x53, 0x3e, 0x70, 0xf7, 0x18, 0xf5, 0xce, 0x7b, 0x4e, 0xbf, 0x27, 0xce, 0xce, 0xa8,
+    0xb3, 0xbe, 0x40, 0xc5, 0xc5, 0x32, 0x29, 0x3e, 0x71, 0x64, 0x9e, 0xde, 0x8c, 0xf6, 0x75, 0xa1,
+    0xe6, 0xf6, 0x53, 0xc8, 0x31, 0xa8, 0x78, 0xde, 0x50, 0x40, 0xf7, 0x62, 0xde, 0x36, 0xb2, 0xba
+};
+#endif
+
+static esp_err_t example_get_sec2_salt(const char **salt, uint16_t *salt_len) {
+#if CONFIG_EXAMPLE_PROTOCOMM_SEC2_DEV_MODE
+    ESP_LOGI(TAG, "Development mode: using hard coded salt");
+    *salt = sec2_salt;
+    *salt_len = sizeof(sec2_salt);
+    return ESP_OK;
+#elif CONFIG_EXAMPLE_PROTOCOMM_SEC2_PROD_MODE
+    ESP_LOGE(TAG, "Not implemented!");
+    return ESP_FAIL;
+#endif
+}
+
+static esp_err_t example_get_sec2_verifier(const char **verifier, uint16_t *verifier_len) {
+#if CONFIG_EXAMPLE_PROTOCOMM_SEC2_DEV_MODE
+    ESP_LOGI(TAG, "Development mode: using hard coded verifier");
+    *verifier = sec2_verifier;
+    *verifier_len = sizeof(sec2_verifier);
+    return ESP_OK;
+#elif CONFIG_EXAMPLE_PROTOCOMM_SEC2_PROD_MODE
+    /* This code needs to be updated with appropriate implementation to provide verifier */
+    ESP_LOGE(TAG, "Not implemented!");
+    return ESP_FAIL;
+#endif
+}
+#endif
+
 /* Custom allowed property types */
 enum property_types {
     PROP_TYPE_TIMESTAMP = 0,
@@ -173,15 +239,56 @@ void start_esp_local_ctrl_service(void)
     https_conf.prvtkey_pem = prvtkey_pem_start;
     https_conf.prvtkey_len = prvtkey_pem_end - prvtkey_pem_start;
 
+#ifdef CONFIG_EXAMPLE_PROTOCOMM_SECURITY_VERSION_1
+    /* What is the security level that we want (0, 1, 2):
+     *      - PROTOCOMM_SECURITY_0 is simply plain text communication.
+     *      - PROTOCOMM_SECURITY_1 is secure communication which consists of secure handshake
+     *          using X25519 key exchange and proof of possession (pop) and AES-CTR
+     *          for encryption/decryption of messages.
+     *      - PROTOCOMM_SECURITY_2 SRP6a based authentication and key exchange
+     *        + AES-GCM encryption/decryption of messages
+     */
+    esp_local_ctrl_proto_sec_t security = PROTOCOM_SEC1;
+
+    /* Do we want a proof-of-possession (ignored if Security 0 is selected):
+     *      - this should be a string with length > 0
+     *      - NULL if not used
+     */
+    const char *pop = "abcd1234";
+
+    /* This is the structure for passing security parameters
+     * for the protocomm security 1.
+     */
+    protocomm_security1_params_t sec_params = {
+        .data = (const uint8_t *)pop,
+        .len = strlen(pop),
+    };
+
+#elif CONFIG_EXAMPLE_PROTOCOMM_SECURITY_VERSION_2
+    esp_local_ctrl_proto_sec_t security = PROTOCOM_SEC2;
+
+    /* This is the structure for passing security parameters
+     * for the protocomm security 2.
+     */
+    protocomm_security2_params_t sec_params = {};
+
+    ESP_ERROR_CHECK(example_get_sec2_salt(&sec_params.salt, &sec_params.salt_len));
+    ESP_ERROR_CHECK(example_get_sec2_verifier(&sec_params.verifier, &sec_params.verifier_len));
+
+#else /* CONFIG_EXAMPLE_PROTOCOMM_SECURITY_VERSION_0 */
+    esp_local_ctrl_proto_sec_t security = PROTOCOM_SEC0;
+    const void *sec_params = NULL;
+
+#endif
     esp_local_ctrl_config_t config = {
         .transport = ESP_LOCAL_CTRL_TRANSPORT_HTTPD,
         .transport_config = {
             .httpd = &https_conf
         },
         .proto_sec = {
-            .version = 0,
+            .version = security,
             .custom_handle = NULL,
-            .sec_params = NULL,
+            .sec_params = &sec_params,
         },
         .handlers = {
             /* User defined handler functions */

examples/protocols/esp_local_ctrl/pytest_esp_local_ctrl.py

@@ -66,7 +66,9 @@ def test_examples_esp_local_ctrl(dut: Dut) -> None:
     # Running mDNS services in docker is not a trivial task. Therefore, the script won't connect to the host name but
     # to IP address. However, the certificates were generated for the host name and will be rejected.
     cmd = ' '.join([sys.executable, os.path.join(idf_path, rel_project_path, 'scripts/esp_local_ctrl.py'),
-                    '--sec_ver 0',
+                    '--sec_ver 2',
+                    '--sec2_username wifiprov',
+                    '--sec2_pwd abcd1234',
                     '--name', dut_ip,
                     '--dont-check-hostname'])  # don't reject the certificate because of the hostname
     esp_local_ctrl_log = os.path.join(idf_path, rel_project_path, 'esp_local_ctrl.log')

examples/protocols/esp_local_ctrl/scripts/esp_local_ctrl.py

@@ -12,6 +12,7 @@ import ssl
 import struct
 import sys
 import textwrap
+from getpass import getpass
 
 import proto_lc
 
@@ -112,10 +113,12 @@ def on_except(err):
         print(err)
 
 
-def get_security(secver, pop=None, verbose=False):
+def get_security(secver, username, password, pop='', verbose=False):
+    if secver == 2:
+        return security.Security2(username, password, verbose)
     if secver == 1:
         return security.Security1(pop, verbose)
-    elif secver == 0:
+    if secver == 0:
         return security.Security0(verbose)
     return None
 
@@ -145,10 +148,10 @@ async def get_transport(sel_transport, service_name, check_hostname):
 
 async def version_match(tp, protover, verbose=False):
     try:
-        response = await tp.send_data('proto-ver', protover)
+        response = await tp.send_data('esp_local_ctrl/version', protover)
 
         if verbose:
-            print('proto-ver response : ', response)
+            print('esp_local_ctrl/version response : ', response)
 
         # First assume this to be a simple version string
         if response.lower() == protover.lower():
@@ -176,10 +179,10 @@ async def has_capability(tp, capability='none', verbose=False):
     # Note : default value of `capability` argument cannot be empty string
     # because protocomm_httpd expects non zero content lengths
     try:
-        response = await tp.send_data('proto-ver', capability)
+        response = await tp.send_data('esp_local_ctrl/version', capability)
 
         if verbose:
-            print('proto-ver response : ', response)
+            print('esp_local_ctrl/version response : ', response)
 
         try:
             # Interpret this as JSON structure containing
@@ -281,20 +284,32 @@ async def main():
 
     parser.add_argument('--sec_ver', dest='secver', type=int, default=None,
                         help=desc_format(
-                            'Protocomm security scheme used by the provisioning service for secure '
+                            'Protocomm security scheme used for secure '
                             'session establishment. Accepted values are :',
                             '\t- 0 : No security',
                             '\t- 1 : X25519 key exchange + AES-CTR encryption',
-                            '\t      + Authentication using Proof of Possession (PoP)',
+                            '\t- 2 : SRP6a + AES-GCM encryption',
-                            'In case device side application uses IDF\'s provisioning manager, '
+                            '\t      + Authentication using Proof of Possession (PoP)'))
-                            'the compatible security version is automatically determined from '
-                            'capabilities retrieved via the version endpoint'))
 
     parser.add_argument('--pop', dest='pop', type=str, default='',
                         help=desc_format(
                             'This specifies the Proof of possession (PoP) when security scheme 1 '
                             'is used'))
 
+    parser.add_argument('--sec2_username', dest='sec2_usr', type=str, default='',
+                        help=desc_format(
+                            'Username for security scheme 2 (SRP6a)'))
+
+    parser.add_argument('--sec2_pwd', dest='sec2_pwd', type=str, default='',
+                        help=desc_format(
+                            'Password for security scheme 2 (SRP6a)'))
+
+    parser.add_argument('--sec2_gen_cred', help='Generate salt and verifier for security scheme 2 (SRP6a)', action='store_true')
+
+    parser.add_argument('--sec2_salt_len', dest='sec2_salt_len', type=int, default=16,
+                        help=desc_format(
+                            'Salt length for security scheme 2 (SRP6a)'))
+
     parser.add_argument('--dont-check-hostname', action='store_true',
                         # If enabled, the certificate won't be rejected for hostname mismatch.
                         # This option is hidden because it should be used only for testing purposes.
@@ -304,6 +319,14 @@ async def main():
 
     args = parser.parse_args()
 
+    if args.secver == 2 and args.sec2_gen_cred:
+        if not args.sec2_usr or not args.sec2_pwd:
+            raise ValueError('Username/password cannot be empty for security scheme 2 (SRP6a)')
+
+        print('==== Salt-verifier for security scheme 2 (SRP6a) ====')
+        security.sec2_gen_salt_verifier(args.sec2_usr, args.sec2_pwd, args.sec2_salt_len)
+        sys.exit()
+
     if args.version != '':
         print(f'==== Esp_Ctrl Version: {args.version} ====')
 
@@ -327,7 +350,8 @@ async def main():
         args.secver = int(not await has_capability(obj_transport, 'no_sec'))
         print(f'==== Security Scheme: {args.secver} ====')
 
-        if (args.secver != 0) and not await has_capability(obj_transport, 'no_pop'):
+    if (args.secver == 1):
+        if not await has_capability(obj_transport, 'no_pop'):
             if len(args.pop) == 0:
                 print('---- Proof of Possession argument not provided ----')
                 exit(2)
@@ -335,7 +359,14 @@ async def main():
             print('---- Proof of Possession will be ignored ----')
             args.pop = ''
 
-    obj_security = get_security(args.secver, args.pop, args.verbose)
+    if (args.secver == 2):
+        if len(args.sec2_usr) == 0:
+            args.sec2_usr = input('Security Scheme 2 - SRP6a Username required: ')
+        if len(args.sec2_pwd) == 0:
+            prompt_str = 'Security Scheme 2 - SRP6a Password required: '
+            args.sec2_pwd = getpass(prompt_str)
+
+    obj_security = get_security(args.secver, args.sec2_usr, args.sec2_pwd, args.pop, args.verbose)
     if obj_security is None:
         raise ValueError('Invalid Security Version')