Merge pull request #7068 from SparkiDev/srtp_kdf_label

SRTP/SRTCP KDF: add APIs that derives one key from a label

Author: cconlon

doc/dox_comments/header_files/kdf.h

@@ -4,7 +4,7 @@
 
     \brief This function derives keys using SRTP KDF algorithm.
 
-    \return 0 Returned upon successful key derviation.
+    \return 0 Returned upon successful key derivation.
     \return BAD_FUNC_ARG Returned when key or salt is NULL
     \return BAD_FUNC_ARG Returned when key length is not 16, 24 or 32.
     \return BAD_FUNC_ARG Returned when saltSz is larger than 14.
@@ -44,6 +44,8 @@
     \endcode
 
     \sa wc_SRTCP_KDF
+    \sa wc_SRTP_KDF_label
+    \sa wc_SRTCP_KDF_label
     \sa wc_SRTP_KDF_kdr_to_idx
 */
 int wc_SRTP_KDF(const byte* key, word32 keySz, const byte* salt, word32 saltSz,
@@ -55,7 +57,7 @@ int wc_SRTP_KDF(const byte* key, word32 keySz, const byte* salt, word32 saltSz,
 
     \brief This function derives keys using SRTCP KDF algorithm.
 
-    \return 0 Returned upon successful key derviation.
+    \return 0 Returned upon successful key derivation.
     \return BAD_FUNC_ARG Returned when key or salt is NULL
     \return BAD_FUNC_ARG Returned when key length is not 16, 24 or 32.
     \return BAD_FUNC_ARG Returned when saltSz is larger than 14.
@@ -95,12 +97,107 @@ int wc_SRTP_KDF(const byte* key, word32 keySz, const byte* salt, word32 saltSz,
     \endcode
 
     \sa wc_SRTP_KDF
+    \sa wc_SRTP_KDF_label
+    \sa wc_SRTCP_KDF_label
     \sa wc_SRTP_KDF_kdr_to_idx
 */
 int wc_SRTCP_KDF(const byte* key, word32 keySz, const byte* salt, word32 saltSz,
         int kdrIdx, const byte* index, byte* key1, word32 key1Sz, byte* key2,
         word32 key2Sz, byte* key3, word32 key3Sz);
+/*!
+    \ingroup SrtpKdf
+
+    \brief This function derives a key with label using SRTP KDF algorithm.
+
+    \return 0 Returned upon successful key derivation.
+    \return BAD_FUNC_ARG Returned when key, salt or outKey is NULL
+    \return BAD_FUNC_ARG Returned when key length is not 16, 24 or 32.
+    \return BAD_FUNC_ARG Returned when saltSz is larger than 14.
+    \return BAD_FUNC_ARG Returned when kdrIdx is less than -1 or larger than 24.
+    \return MEMORY_E on dynamic memory allocation failure.
+
+    \param [in] key Key to use with encryption.
+    \param [in] keySz Size of key in bytes.
+    \param [in] salt Random non-secret value.
+    \param [in] saltSz Size of random in bytes.
+    \param [in] kdrIdx Key derivation rate. kdr = 0 when -1, otherwise kdr = 2^kdrIdx.
+    \param [in] index Index value to XOR in.
+    \param [in] label Label to use when deriving key.
+    \param [out] outKey Derived key.
+    \param [in] outKeySz Size of derived key in bytes.
+
 
+    _Example_
+    \code
+    unsigned char key[16] = { ... };
+    unsigned char salt[14] = { ... };
+    unsigned char index[6] = { ... };
+    unsigned char keyE[16];
+    int kdrIdx = 0; // Use all of index
+    int ret;
+
+    ret = wc_SRTP_KDF_label(key, sizeof(key), salt, sizeof(salt), kdrIdx, index,
+        WC_SRTP_LABEL_ENCRYPTION, keyE, sizeof(keyE));
+    if (ret != 0) {
+        WOLFSSL_MSG("wc_SRTP_KDF failed");
+    }
+    \endcode
+
+    \sa wc_SRTP_KDF
+    \sa wc_SRTCP_KDF
+    \sa wc_SRTCP_KDF_label
+    \sa wc_SRTP_KDF_kdr_to_idx
+*/
+int wc_SRTP_KDF_label(const byte* key, word32 keySz, const byte* salt,
+        word32 saltSz, int kdrIdx, const byte* index, byte label, byte* outKey,
+        word32 outKeySz);
+/*!
+    \ingroup SrtpKdf
+
+    \brief This function derives key with label using SRTCP KDF algorithm.
+
+    \return 0 Returned upon successful key derivation.
+    \return BAD_FUNC_ARG Returned when key, salt or outKey is NULL
+    \return BAD_FUNC_ARG Returned when key length is not 16, 24 or 32.
+    \return BAD_FUNC_ARG Returned when saltSz is larger than 14.
+    \return BAD_FUNC_ARG Returned when kdrIdx is less than -1 or larger than 24.
+    \return MEMORY_E on dynamic memory allocation failure.
+
+    \param [in] key Key to use with encryption.
+    \param [in] keySz Size of key in bytes.
+    \param [in] salt Random non-secret value.
+    \param [in] saltSz Size of random in bytes.
+    \param [in] kdrIdx Key derivation rate. kdr = 0 when -1, otherwise kdr = 2^kdrIdx.
+    \param [in] index Index value to XOR in.
+    \param [in] label Label to use when deriving key.
+    \param [out] outKey Derived key.
+    \param [in] outKeySz Size of derived key in bytes.
+
+
+    _Example_
+    \code
+    unsigned char key[16] = { ... };
+    unsigned char salt[14] = { ... };
+    unsigned char index[4] = { ... };
+    unsigned char keyE[16];
+    int kdrIdx = 0; // Use all of index
+    int ret;
+
+    ret = wc_SRTCP_KDF_label(key, sizeof(key), salt, sizeof(salt), kdrIdx,
+        index, WC_SRTCP_LABEL_ENCRYPTION, keyE, sizeof(keyE));
+    if (ret != 0) {
+        WOLFSSL_MSG("wc_SRTP_KDF failed");
+    }
+    \endcode
+
+    \sa wc_SRTP_KDF
+    \sa wc_SRTCP_KDF
+    \sa wc_SRTP_KDF_label
+    \sa wc_SRTP_KDF_kdr_to_idx
+*/
+int wc_SRTP_KDF_label(const byte* key, word32 keySz, const byte* salt,
+        word32 saltSz, int kdrIdx, const byte* index, byte label, byte* outKey,
+        word32 outKeySz);
 /*!
     \ingroup SrtpKdf
 
@@ -121,6 +218,8 @@ int wc_SRTCP_KDF(const byte* key, word32 keySz, const byte* salt, word32 saltSz,
 
     \sa wc_SRTP_KDF
     \sa wc_SRTCP_KDF
+    \sa wc_SRTP_KDF_label
+    \sa wc_SRTCP_KDF_label
 */
 int wc_SRTP_KDF_kdr_to_idx(word32 kdr);