Merge branch 'feature/unified_provisioning' into 'master'

Feature/unified provisioning

See merge request sdk/ESP8266_RTOS_SDK!789

Author: donghengqaz

components/log/include/esp_log_internal.h

@@ -16,9 +16,13 @@
 #define __ESP_LOG_INTERNAL_H__
 
 //these functions do not check level versus ESP_LOCAL_LEVEL, this should be done in esp_log.h
-void esp_log_buffer_hex_internal(const char *tag, const void *buffer, uint16_t buff_len, esp_log_level_t level);
-void esp_log_buffer_char_internal(const char *tag, const void *buffer, uint16_t buff_len, esp_log_level_t level);
-void esp_log_buffer_hexdump_internal( const char *tag, const void *buffer, uint16_t buff_len, esp_log_level_t log_level);
+#define esp_log_buffer_hex_internal(...)
+#define esp_log_buffer_char_internal(...)
+#define esp_log_buffer_hexdump_internal(...)
+/* TODO: Add the implementation of the below API's */
+// void esp_log_buffer_hex_internal(const char *tag, const void *buffer, uint16_t buff_len, esp_log_level_t level);
+// void esp_log_buffer_char_internal(const char *tag, const void *buffer, uint16_t buff_len, esp_log_level_t level);
+// void esp_log_buffer_hexdump_internal( const char *tag, const void *buffer, uint16_t buff_len, esp_log_level_t log_level);
 
 #endif
 

components/protocomm/CMakeLists.txt

@@ -0,0 +1,16 @@
+set(COMPONENT_ADD_INCLUDEDIRS include/common
+                              include/security
+                              include/transports)
+set(COMPONENT_PRIV_INCLUDEDIRS proto-c src/common)
+set(COMPONENT_SRCS  "src/common/protocomm.c"
+                    "src/security/security0.c"
+                    "src/security/security1.c"
+                    "proto-c/constants.pb-c.c"
+                    "proto-c/sec0.pb-c.c"
+                    "proto-c/sec1.pb-c.c"
+                    "proto-c/session.pb-c.c"
+                    "src/transports/protocomm_httpd.c")
+
+set(COMPONENT_PRIV_REQUIRES protobuf-c mbedtls wifi_provisioning)
+
+register_component()

components/protocomm/component.mk

@@ -0,0 +1,8 @@
+COMPONENT_ADD_INCLUDEDIRS :=
+COMPONENT_SRCDIRS :=
+
+ifdef CONFIG_ENABLE_UNIFIED_PROVISIONING
+COMPONENT_ADD_INCLUDEDIRS := include/common include/security include/transports
+COMPONENT_PRIV_INCLUDEDIRS := proto-c src/common
+COMPONENT_SRCDIRS := src/common src/security proto-c src/transports
+endif

components/protocomm/include/common/protocomm.h

@@ -0,0 +1,235 @@
+// Copyright 2018 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include <protocomm_security.h>
+#include <esp_err.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Function prototype for protocomm endpoint handler
+ */
+typedef esp_err_t (*protocomm_req_handler_t)(
+    uint32_t        session_id, /*!< Session ID for identifying protocomm client */
+    const uint8_t  *inbuf,      /*!< Pointer to user provided input data buffer */
+    ssize_t         inlen,      /*!< Length o the input buffer */
+    uint8_t       **outbuf,     /*!< Pointer to output buffer allocated by handler */
+    ssize_t        *outlen,     /*!< Length of the allocated output buffer */
+    void           *priv_data   /*!< Private data passed to the handler (NULL if not used) */
+);
+
+/**
+ * @brief   This structure corresponds to a unique instance of protocomm
+ *          returned when the API `protocomm_new()` is called. The remaining
+ *          Protocomm APIs require this object as the first parameter.
+ *
+ * @note    Structure of the protocomm object is kept private
+ */
+typedef struct protocomm protocomm_t;
+
+/**
+ * @brief   Create a new protocomm instance
+ *
+ * This API will return a new dynamically allocated protocomm instance
+ * with all elements of the protocomm_t structure initialized to NULL.
+ *
+ * @return
+ *  - protocomm_t* : On success
+ *  - NULL : No memory for allocating new instance
+ */
+protocomm_t *protocomm_new();
+
+/**
+ * @brief   Delete a protocomm instance
+ *
+ * This API will deallocate a protocomm instance that was created
+ * using `protocomm_new()`.
+ *
+ * @param[in] pc    Pointer to the protocomm instance to be deleted
+ */
+void protocomm_delete(protocomm_t *pc);
+
+/**
+ * @brief   Add endpoint request handler for a protocomm instance
+ *
+ * This API will bind an endpoint handler function to the specified
+ * endpoint name, along with any private data that needs to be pass to
+ * the handler at the time of call.
+ *
+ * @note
+ *  - An endpoint must be bound to a valid protocomm instance,
+ *    created using `protocomm_new()`.
+ *  - This function internally calls the registered `add_endpoint()`
+ *    function of the selected transport which is a member of the
+ *    protocomm_t instance structure.
+ *
+ * @param[in] pc        Pointer to the protocomm instance
+ * @param[in] ep_name   Endpoint identifier(name) string
+ * @param[in] h         Endpoint handler function
+ * @param[in] priv_data Pointer to private data to be passed as a
+ *                      parameter to the handler function on call.
+ *                      Pass NULL if not needed.
+ *
+ * @return
+ *  - ESP_OK : Success
+ *  - ESP_FAIL : Error adding endpoint / Endpoint with this name already exists
+ *  - ESP_ERR_NO_MEM : Error allocating endpoint resource
+ *  - ESP_ERR_INVALID_ARG : Null instance/name/handler arguments
+ */
+esp_err_t protocomm_add_endpoint(protocomm_t *pc, const char *ep_name,
+                                 protocomm_req_handler_t h, void *priv_data);
+
+/**
+ * @brief   Remove endpoint request handler for a protocomm instance
+ *
+ * This API will remove a registered endpoint handler identified by
+ * an endpoint name.
+ *
+ * @note
+ *  - This function internally calls the registered `remove_endpoint()`
+ *    function which is a member of the protocomm_t instance structure.
+ *
+ * @param[in] pc        Pointer to the protocomm instance
+ * @param[in] ep_name   Endpoint identifier(name) string
+ *
+ * @return
+ *  - ESP_OK : Success
+ *  - ESP_ERR_NOT_FOUND : Endpoint with specified name doesn't exist
+ *  - ESP_ERR_INVALID_ARG : Null instance/name arguments
+ */
+esp_err_t protocomm_remove_endpoint(protocomm_t *pc, const char *ep_name);
+
+/**
+ * @brief   Calls the registered handler of an endpoint session
+ *          for processing incoming data and generating the response
+ *
+ * @note
+ *  - An endpoint must be bound to a valid protocomm instance,
+ *    created using `protocomm_new()`.
+ *  - Resulting output buffer must be deallocated by the caller.
+ *
+ * @param[in]  pc         Pointer to the protocomm instance
+ * @param[in]  ep_name    Endpoint identifier(name) string
+ * @param[in]  session_id Unique ID for a communication session
+ * @param[in]  inbuf      Input buffer contains input request data which is to be
+ *                        processed by the registered handler
+ * @param[in]  inlen      Length of the input buffer
+ * @param[out] outbuf     Pointer to internally allocated output buffer,
+ *                        where the resulting response data output from
+ *                        the registered handler is to be stored
+ * @param[out] outlen     Buffer length of the allocated output buffer
+ *
+ * @return
+ *  - ESP_OK : Request handled successfully
+ *  - ESP_FAIL : Internal error in execution of registered handler
+ *  - ESP_ERR_NO_MEM : Error allocating internal resource
+ *  - ESP_ERR_NOT_FOUND : Endpoint with specified name doesn't exist
+ *  - ESP_ERR_INVALID_ARG : Null instance/name arguments
+ */
+esp_err_t protocomm_req_handle(protocomm_t *pc, const char *ep_name, uint32_t session_id,
+                               const uint8_t *inbuf, ssize_t inlen,
+                               uint8_t **outbuf, ssize_t *outlen);
+
+/**
+ * @brief   Add endpoint security for a protocomm instance
+ *
+ * This API will bind a security session establisher to the specified
+ * endpoint name, along with any proof of possession that may be required
+ * for authenticating a session client.
+ *
+ * @note
+ *  - An endpoint must be bound to a valid protocomm instance,
+ *    created using `protocomm_new()`.
+ *  - The choice of security can be any `protocomm_security_t` instance.
+ *    Choices `protocomm_security0` and `protocomm_security1` are readily available.
+ *
+ * @param[in] pc        Pointer to the protocomm instance
+ * @param[in] ep_name   Endpoint identifier(name) string
+ * @param[in] sec       Pointer to endpoint security instance
+ * @param[in] pop       Pointer to proof of possession for authenticating a client
+ *
+ * @return
+ *  - ESP_OK : Success
+ *  - ESP_FAIL : Error adding endpoint / Endpoint with this name already exists
+ *  - ESP_ERR_INVALID_STATE : Security endpoint already set
+ *  - ESP_ERR_NO_MEM : Error allocating endpoint resource
+ *  - ESP_ERR_INVALID_ARG : Null instance/name/handler arguments
+ */
+esp_err_t protocomm_set_security(protocomm_t *pc, const char *ep_name,
+                                 const protocomm_security_t *sec,
+                                 const protocomm_security_pop_t *pop);
+
+/**
+ * @brief   Remove endpoint security for a protocomm instance
+ *
+ * This API will remove a registered security endpoint identified by
+ * an endpoint name.
+ *
+ * @param[in] pc        Pointer to the protocomm instance
+ * @param[in] ep_name   Endpoint identifier(name) string
+ *
+ * @return
+ *  - ESP_OK : Success
+ *  - ESP_ERR_NOT_FOUND : Endpoint with specified name doesn't exist
+ *  - ESP_ERR_INVALID_ARG : Null instance/name arguments
+ */
+esp_err_t protocomm_unset_security(protocomm_t *pc, const char *ep_name);
+
+/**
+ * @brief   Set endpoint for version verification
+ *
+ * This API can be used for setting an application specific protocol
+ * version which can be verified by clients through the endpoint.
+ *
+ * @note
+ *  - An endpoint must be bound to a valid protocomm instance,
+ *    created using `protocomm_new()`.
+
+ * @param[in] pc        Pointer to the protocomm instance
+ * @param[in] ep_name   Endpoint identifier(name) string
+ * @param[in] version   Version identifier(name) string
+ *
+ * @return
+ *  - ESP_OK : Success
+ *  - ESP_FAIL : Error adding endpoint / Endpoint with this name already exists
+ *  - ESP_ERR_INVALID_STATE : Version endpoint already set
+ *  - ESP_ERR_NO_MEM : Error allocating endpoint resource
+ *  - ESP_ERR_INVALID_ARG : Null instance/name/handler arguments
+ */
+esp_err_t protocomm_set_version(protocomm_t *pc, const char *ep_name,
+                                const char *version);
+
+/**
+ * @brief   Remove version verification endpoint from a protocomm instance
+ *
+ * This API will remove a registered version endpoint identified by
+ * an endpoint name.
+ *
+ * @param[in] pc        Pointer to the protocomm instance
+ * @param[in] ep_name   Endpoint identifier(name) string
+ *
+ * @return
+ *  - ESP_OK : Success
+ *  - ESP_ERR_NOT_FOUND : Endpoint with specified name doesn't exist
+ *  - ESP_ERR_INVALID_ARG : Null instance/name arguments
+ */
+esp_err_t protocomm_unset_version(protocomm_t *pc, const char *ep_name);
+
+#ifdef __cplusplus
+}
+#endif

components/protocomm/include/security/protocomm_security.h

@@ -0,0 +1,101 @@
+// Copyright 2018 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include <esp_err.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief   Proof Of Possession for authenticating a secure session
+ */
+typedef struct protocomm_security_pop {
+    /**
+     * Pointer to buffer containing the proof of possession data
+     */
+    const uint8_t *data;
+
+    /**
+     * Length (in bytes) of the proof of possession data
+     */
+    uint16_t len;
+} protocomm_security_pop_t;
+
+/**
+ * @brief   Protocomm security object structure.
+ *
+ * The member functions are used for implementing secure
+ * protocomm sessions.
+ *
+ * @note    This structure should not have any dynamic
+ *          members to allow re-entrancy
+ */
+typedef struct protocomm_security {
+    /**
+     * Unique version number of security implementation
+     */
+    int ver;
+
+    /**
+     * Function for initializing/allocating security
+     * infrastructure
+     */
+    esp_err_t (*init)();
+
+    /**
+     * Function for deallocating security infrastructure
+     */
+    esp_err_t (*cleanup)();
+
+    /**
+     * Starts new secure transport session with specified ID
+     */
+    esp_err_t (*new_transport_session)(uint32_t session_id);
+
+    /**
+     * Closes a secure transport session with specified ID
+     */
+    esp_err_t (*close_transport_session)(uint32_t session_id);
+
+    /**
+     * Handler function for authenticating connection
+     * request and establishing secure session
+     */
+    esp_err_t (*security_req_handler)(const protocomm_security_pop_t *pop,
+                                      uint32_t session_id,
+                                      const uint8_t *inbuf, ssize_t inlen,
+                                      uint8_t **outbuf, ssize_t *outlen,
+                                      void *priv_data);
+
+    /**
+     * Function which implements the encryption algorithm
+     */
+    esp_err_t (*encrypt)(uint32_t session_id,
+                         const uint8_t *inbuf, ssize_t inlen,
+                         uint8_t *outbuf, ssize_t *outlen);
+
+    /**
+     * Function which implements the decryption algorithm
+     */
+    esp_err_t (*decrypt)(uint32_t session_id,
+                         const uint8_t *inbuf, ssize_t inlen,
+                         uint8_t *outbuf, ssize_t *outlen);
+} protocomm_security_t;
+
+#ifdef __cplusplus
+}
+#endif