Merge branch 'support/add_srp_salt_ver_gen_api_v5.1' into 'release/v5.1'

Generate Salt and verifier pair for given username and password (v5.1)

See merge request espressif/esp-idf!27351

components/protocomm/CMakeLists.txt

@@ -1,7 +1,8 @@
 set(include_dirs include/common
                  include/security
-                 include/transports)
-set(priv_include_dirs proto-c src/common src/crypto/srp6a/include)
+                 include/transports
+                 include/crypto/srp6a)
+set(priv_include_dirs proto-c src/common)
 set(srcs
     "src/common/protocomm.c"
     "proto-c/constants.pb-c.c"

components/protocomm/include/crypto/srp6a/esp_srp.h

@@ -0,0 +1,228 @@
+/*
+ * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#include <stdint.h>
+#include <esp_err.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief SRP-6a protocol implementation
+ *
+ * More information on protocol can be found: https://datatracker.ietf.org/doc/html/rfc5054
+ *
+ * This implementation is used by security2 of wifi_provisioning and local control features.
+ * Details on how these protocols use this feature can be found here: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-reference/provisioning/provisioning.html#security-2-scheme
+ *
+ * Below is the example usage of the srp6a protocol in protocomm component,
+ * which can help understand the APIs better.
+ *
+ * Variables used:
+ *
+ *    N, g: group parameters (prime and generator)
+ *    s: salt
+ *    B, b: server's public and private values
+ *    A, a: client's public and private values
+ *    I: user name (aka "identity")
+ *    P: password
+ *    v: verifier
+ *    k: SRP-6 multiplier
+ *
+ *      salt (s) is random of given length, 16 in our case, which along with username and password
+ *      is used to generate verifier.
+ *
+ *      x = SHA1(s | SHA1(I | ":" | P))
+ *      v = g^x % N
+ *
+ *  Steps involved (From protocomm component usage):
+ *      Step1. Client Hello (PhoneApp):
+ *          a. Generate Key pair:
+ *              a (cli_privkey) = 256 bit random value,
+ *              A (cli_pubkey) = g^a.
+ *              g - generator, N - large safe prime, All arithmetic operations are performed in ring of integers modulo N,
+ *                  thus all occurrences like y^z should be read as y^z modulo N.
+ *          b. SessionCmd0 (cli_pubkey, username I)
+ *
+ *      Step2. Device(ESP):
+ *          a. Obtain Salt and verifier stored on ESP
+ *              Salt s = 256 bit random value,
+ *              Verifier v = g^× where x = H(s | I | P)
+ *          b. Generate Key Pair
+ *              b (dev_privkey) = 256 bit random value
+ *              B(dev_pubkey) = k*v + g^b where k = H(N, g)
+ *          c. Shared Key K = H(S) where,
+ *              S = (A * v^u) ^ b
+ *              u = H(A, B)
+ *          d. SessionResp0(dev_pubkey B, dev_random)
+ *
+ *      Step3. Client (PhoneApp)
+ *          a. shared_key(K) = H(S) where,
+ *              S = (B - k*v) ^ (a + ux),
+ *              u = H(A, B),
+ *              k = H(N, g),
+ *              V = g^x,
+ *              x = H(s | I | P).
+ *          b. Verification token
+ *              client proof M = H[H(N) XOR H(g) | H(I) | S | A | B | K]
+ *          c. SessionCmd1(Client proof M1)
+ *
+ *      Step4. Device (ESP):
+ *          a. Verify client:
+ *              device generates M1 = H[H(N) XOR H(g) | H(I) | S | A | B | K]
+ *              device verifies this M1 with the M1 obtained from Client
+ *          b. Verification token: Device generate device proof M2 = H(A, M, K)
+ *          c. Initialization Vector(IV):
+ *              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
+ *          d. SessionResp1 (DeviceProofM2, dev_rand)
+ *
+ *      Step5. Client (PhoneApp)
+ *          a. Verify Device
+ *              Client calculates device proof M2 as M2 = H(A, M, K)
+ *              verifies this M2 with M2 obtained from device
+ */
+
+/**
+ * @brief Large prime+generator to be used for the algorithm
+ */
+typedef enum {
+    /* SRP specific:
+     * N = 3072 bit large safe prime,
+     * g = generator */
+    ESP_NG_3072 = 0,
+} esp_ng_type_t;
+
+typedef struct esp_srp_handle esp_srp_handle_t;
+
+/**
+ * @brief Initialize srp context for given NG type
+ *
+ * @param ng NG type given by `esp_ng_type_t`
+ * @return   esp_srp_handle_t* srp handle
+ *
+ * @note    the handle gets freed with `esp_srp_free`
+ */
+esp_srp_handle_t *esp_srp_init(esp_ng_type_t ng);
+
+/**
+ * @brief free esp_srp_context
+ *
+ * @param hd handle to be free
+ */
+void esp_srp_free(esp_srp_handle_t *hd);
+
+/**
+ * @brief   Returns B (pub key) and salt. [Step2.b]
+ *
+ * @param hd    esp_srp handle
+ * @param username  Username not expected NULL terminated
+ * @param username_len  Username length
+ * @param pass      Password not expected to be NULL terminated
+ * @param pass_len  Pasword length
+ * @param salt_len  Salt length
+ * @param bytes_B   Public Key returned
+ * @param len_B     Length of the public key
+ * @param bytes_salt    Salt bytes generated
+ * @return esp_err_t    ESP_OK on success, appropriate error otherwise
+ *
+ * @note    *bytes_B MUST NOT BE FREED BY THE CALLER
+ * @note    *bytes_salt MUST NOT BE FREE BY THE CALLER
+ */
+esp_err_t esp_srp_srv_pubkey(esp_srp_handle_t *hd, const char *username, int username_len,
+                             const char *pass, int pass_len, int salt_len,
+                             char **bytes_B, int *len_B, char **bytes_salt);
+
+/**
+ * @brief   Generate salt-verifier pair, given username, password and salt length
+ *
+ * @param[in] username      username
+ * @param[in] username_len  length of the username
+ * @param[in] pass          password
+ * @param[in] pass_len      length of the password
+ * @param[out] bytes_salt   generated salt on successful generation, or NULL
+ * @param[in] salt_len      salt length
+ * @param[out] verifier     generated verifier on successful generation, or NULL
+ * @param[out] verifier_len length of the generated verifier
+ * @return esp_err_t        ESP_OK on success, appropriate error otherwise
+ *
+ * @note if API has returned ESP_OK, salt and verifier generated need to be freed by caller
+ * @note Usually, username and password are not saved on the device. Rather salt and verifier are
+ *      generated outside the device and are embedded.
+ *      this covenience API can be used to generate salt and verifier on the fly for development use case.
+ *      OR for devices which intentionally want to generate different password each time and can send it
+ *      to the client securely. e.g., a device has a display and it shows the pin
+ */
+esp_err_t esp_srp_gen_salt_verifier(const char *username, int username_len,
+                                    const char *pass, int pass_len,
+                                    char **bytes_salt, int salt_len,
+                                    char **verifier, int *verifier_len);
+
+/**
+ * @brief       Set the Salt and Verifier pre-generated for a given password.
+ * This should be used only if the actual password is not available.
+ * The public key can then be generated using esp_srp_srv_pubkey_from_salt_verifier()
+ * and not esp_srp_srv_pubkey()
+ *
+ * @param hd            esp_srp_handle
+ * @param salt          pre-generated salt bytes
+ * @param salt_len      length of the salt bytes
+ * @param verifier      pre-generated verifier
+ * @param verifier_len  length of the verifier bytes
+ * @return esp_err_t    ESP_OK on success, appropriate error otherwise
+ */
+esp_err_t esp_srp_set_salt_verifier(esp_srp_handle_t *hd, const char *salt, int salt_len,
+                                    const char *verifier, int verifier_len);
+
+/**
+ * @brief   Returns B (pub key)[Step2.b] when the salt and verifier are set using esp_srp_set_salt_verifier()
+ *
+ * @param hd        esp_srp handle
+ * @param bytes_B   Key returned to the called
+ * @param len_B     Length of the key returned
+ * @return esp_err_t ESP_OK on success, appropriate error otherwise
+ *
+ * @note    *bytes_B MUST NOT BE FREED BY THE CALLER
+ */
+esp_err_t esp_srp_srv_pubkey_from_salt_verifier(esp_srp_handle_t *hd, char **bytes_B, int *len_B);
+
+/**
+ * @brief   Get session key in `*bytes_key` given by len in `*len_key`. [Step2.c].
+ *
+ * This calculated session key is used for further communication given the proofs are
+ * exchanged/authenticated with `esp_srp_exchange_proofs`
+ *
+ * @param hd        esp_srp handle
+ * @param bytes_A   Private Key
+ * @param len_A     Private Key length
+ * @param bytes_key Key returned to the caller
+ * @param len_key   length of the key in *bytes_key
+ * @return esp_err_t ESP_OK on success, appropriate error otherwise
+ *
+ * @note    *bytes_key MUST NOT BE FREED BY THE CALLER
+ */
+esp_err_t esp_srp_get_session_key(esp_srp_handle_t *hd, char *bytes_A, int len_A, char **bytes_key, uint16_t *len_key);
+
+/**
+ * @brief Complete the authentication. If this step fails, the session_key exchanged should not be used
+ *
+ * This is the final authentication step in SRP algorithm [Step4.1, Step4.b, Step4.c]
+ *
+ * @param hd                esp_srp handle
+ * @param username          Username not expected NULL terminated
+ * @param username_len      Username length
+ * @param bytes_user_proof  param in
+ * @param bytes_host_proof  parameter out (should be SHA512_DIGEST_LENGTH) bytes in size
+ * @return esp_err_t    ESP_OK if user's proof is ok and subsequently bytes_host_proof is populated with our own proof.
+ */
+esp_err_t esp_srp_exchange_proofs(esp_srp_handle_t *hd, char *username, uint16_t username_len,
+                                  char *bytes_user_proof, char *bytes_host_proof);
+
+#ifdef __cplusplus
+}
+#endif