/* * netutil.h - CC31xx/CC32xx Host Driver Implementation * * Copyright (C) 2017 Texas Instruments Incorporated - http://www.ti.com/ * * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the * distribution. * * Neither the name of Texas Instruments Incorporated nor the names of * its contributors may be used to endorse or promote products derived * from this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * */ #ifndef __NETUTIL_H__ #define __NETUTIL_H__ /*****************************************************************************/ /* Include files */ /*****************************************************************************/ #include #ifdef __cplusplus extern "C" { #endif /*! \defgroup NetUtil \short Networking related commands and configuration */ /*! \addtogroup NetUtil @{ */ /*****************************************************************************/ /* Macro declarations */ /*****************************************************************************/ /* Set/get options */ #define SL_NETUTIL_CRYPTO_PUBLIC_KEY (1) #define SL_NETUTIL_CRYPTO_PUBLIC_KEY_INFO (2) #define SL_NETUTIL_TRUE_RANDOM (3) /* Commands */ #define SL_NETUTIL_CRYPTO_CMD_CREATE_CERT (1) #define SL_NETUTIL_CRYPTO_CMD_SIGN_MSG (2) #define SL_NETUTIL_CRYPTO_CMD_VERIFY_MSG (3) #define SL_NETUTIL_CRYPTO_CMD_TEMP_KEYS (4) #define SL_NETUTIL_CRYPTO_CMD_INSTALL_OP (5) #define SL_NETUTIL_CMD_ARP_LOOKUP (6) /*****************************************************************************/ /* Errors returned from the general error async event */ /*****************************************************************************/ /*****************************************************************************/ /* Structure/Enum declarations */ /*****************************************************************************/ typedef struct { _u8 *pOutputValues; _u16 *pOutputLen; _i16 Status; }_SlNetUtilCmdData_t; /* Defines the size of the buffer that will be allocated */ /* (on the stack) by the sl_UtilsCmd API. */ #define SL_NETUTIL_CMD_BUFFER_SIZE (256) /* Enumeration of Signature types */ #define SL_NETUTIL_CRYPTO_SIG_SHAwDSA (0) #define SL_NETUTIL_CRYPTO_SIG_MD2wRSA (1) #define SL_NETUTIL_CRYPTO_SIG_MD5wRSA (2) #define SL_NETUTIL_CRYPTO_SIG_SHAwRSA (3) #define SL_NETUTIL_CRYPTO_SIG_SHAwECDSA (4) #define SL_NETUTIL_CRYPTO_SIG_SHA256wRSA (5) #define SL_NETUTIL_CRYPTO_SIG_SHA256wECDSA (6) #define SL_NETUTIL_CRYPTO_SIG_SHA384wRSA (7) #define SL_NETUTIL_CRYPTO_SIG_SHA384wECDSA (8) #define SL_NETUTIL_CRYPTO_SIG_SHA512wRSA (9) #define SL_NETUTIL_CRYPTO_SIG_SHA512wECDSA (10) #define SL_NETUTIL_CRYPTO_SIG_DIGESTwECDSA (11) /* Add more signature-Types here */ /* Digest length definitions */ #define SL_NETUTIL_CRYPTO_DGST_MD2_LEN_BYTES (16) #define SL_NETUTIL_CRYPTO_DGST_MD5_LEN_BYTES (16) #define SL_NETUTIL_CRYPTO_DGST_SHA_LEN_BYTES (20) #define SL_NETUTIL_CRYPTO_DGST_SHA256_LEN_BYTES (32) #define SL_NETUTIL_CRYPTO_DGST_SHA384_LEN_BYTES (48) #define SL_NETUTIL_CRYPTO_DGST_SHA512_LEN_BYTES (64) /* Enumeration of Create-Certificate sub-commands */ #define SL_NETUTIL_CRYPTO_CERT_INIT (1) #define SL_NETUTIL_CRYPTO_CERT_SIGN_AND_SAVE (2) #define SL_NETUTIL_CRYPTO_CERT_VER (3) #define SL_NETUTIL_CRYPTO_CERT_SERIAL (4) #define SL_NETUTIL_CRYPTO_CERT_SIG_TYPE (5) #define SL_NETUTIL_CRYPTO_CSR_SIGN_AND_SAVE (6) #if 0 /* reserved for Issuer information - currently not supported */ #define SL_NETUTIL_CRYPTO_CERT_ISSUER_COUNTRY (6) #define SL_NETUTIL_CRYPTO_CERT_ISSUER_STATE (7) #define SL_NETUTIL_CRYPTO_CERT_ISSUER_LOCALITY (8) #define SL_NETUTIL_CRYPTO_CERT_ISSUER_SUR (9) #define SL_NETUTIL_CRYPTO_CERT_ISSUER_ORG (10) #define SL_NETUTIL_CRYPTO_CERT_ISSUER_ORG_UNIT (11) #define SL_NETUTIL_CRYPTO_CERT_ISSUER_COMMON_NAME (12) #define SL_NETUTIL_CRYPTO_CERT_ISSUER_EMAIL (13) #endif /* End - issuer information */ #define SL_NETUTIL_CRYPTO_CERT_DAYS_VALID (14) #define SL_NETUTIL_CRYPTO_CERT_SUBJECT_COUNTRY (15) #define SL_NETUTIL_CRYPTO_CERT_SUBJECT_STATE (16) #define SL_NETUTIL_CRYPTO_CERT_SUBJECT_LOCALITY (17) #define SL_NETUTIL_CRYPTO_CERT_SUBJECT_SUR (18) #define SL_NETUTIL_CRYPTO_CERT_SUBJECT_ORG (19) #define SL_NETUTIL_CRYPTO_CERT_SUBJECT_ORG_UNIT (20) #define SL_NETUTIL_CRYPTO_CERT_SUBJECT_COMMON_NAME (21) #define SL_NETUTIL_CRYPTO_CERT_SUBJECT_EMAIL (22) #define SL_NETUTIL_CRYPTO_CERT_IS_CA (23) /* Enumeration of "Temp-Keys" commands */ #define SL_NETUTIL_CRYPTO_TEMP_KEYS_CREATE (1) #define SL_NETUTIL_CRYPTO_TEMP_KEYS_REMOVE (2) /* Enumeration of "Install/Uninstall" sub-commands */ #define SL_NETUTIL_CRYPTO_INSTALL_SUB_CMD (1) #define SL_NETUTIL_CRYPTO_UNINSTALL_SUB_CMD (2) /* The reserved key for IOT Usage */ #define SL_NETUTIL_CRYPTO_SERVICES_IOT_RESERVED_INDEX (0) /* The Temporary key for FS Usage */ #define SL_NETUTIL_CRYPTO_FS_TEMP_KEYS_OBJ_ID (1) /**********************************************/ /* Public Key Info Structures and Definitions */ /**********************************************/ /* Enumeration of Elliptic Curve "named" curves */ #define SL_NETUTIL_CRYPTO_EC_NAMED_CURVE_NONE (0) #define SL_NETUTIL_CRYPTO_EC_NAMED_CURVE_SECP256R1 (1) /* PLACE HOLDER for future definitions of custom-curve parameters */ typedef struct { _u8 Padding[4]; } SlNetUtilCryptoEcCustomCurveParam_t; /* Union holding the Elliptic Curve parameters. */ typedef union { _u8 NamedCurveParams; /* parameters for named-curve (the curve identifier) */ SlNetUtilCryptoEcCustomCurveParam_t CustomCurveParams; /* parameters for custom curves */ } SlNetUtilCryptoEcCurveParams_u; /* ?curve-type? definitions */ #define SL_NETUTIL_CRYPTO_EC_CURVE_TYPE_NAMED (1) /* ECC Named Curve type */ #define SL_NETUTIL_CRYPTO_EC_CURVE_TYPE_CUSTOM (2) /* ECC Custom curve type */ /* Enumeration of the supported public-key algorithms */ #define SL_NETUTIL_CRYPTO_PUB_KEY_ALGO_NONE (0) #define SL_NETUTIL_CRYPTO_PUB_KEY_ALGO_EC (1) /* Structure for holding the Elliptic Curve Key parameters */ typedef struct { _u8 CurveType; /* defines curve type - custom or named */ SlNetUtilCryptoEcCurveParams_u CurveParams; /* specific parameters of the curve (depends on curve_type) */ } SlNetUtilCryptoEcKeyParams_t; /* Union for holding the Public Key parameters, depends on key algorithm */ typedef union { SlNetUtilCryptoEcKeyParams_t EcParams; /* parameters for Elliptic Curve key */ /* add containers for other key types and algos here*/ } SlNetUtilCryptoPubKeyParams_u; /* structure for holding all the meta-data about a key-pair */ typedef struct { _u8 KeyAlgo; SlNetUtilCryptoPubKeyParams_u KeyParams; _u8 KeyFileNameLen; _u8 CertFileNameLen; }SlNetUtilCryptoPubKeyInfo_t; /********************************************/ /* NetUtil-Crypto Cmd "Attributes" structures */ /********************************************/ /* structure for holding all the attributes for a "Sign" Command */ typedef struct { _u32 ObjId; _u32 SigType; _u32 Flags; } SlNetUtilCryptoCmdSignAttrib_t; /* structure for holding all the attributes for a "Verify" Command */ typedef struct { _u32 ObjId; _u32 SigType; _u32 Flags; _u16 MsgLen; _u16 SigLen; } SlNetUtilCryptoCmdVerifyAttrib_t; /* structure for holding all the attributes for a "Create Certificate" Command */ typedef struct { _u32 ObjId; _u32 Flags; _u16 SubCmd; } SlNetUtilCryptoCmdCreateCertAttrib_t; /* structure for holding all the attributes for "Key management" Commands: */ /* Temp-Key (create and delete), Install and un-Install. */ typedef struct { _u32 ObjId; _u32 Flags; _u16 SubCmd; } SlNetUtilCryptoCmdKeyMgnt_t; /* structure for holding all the attributes for a "SL_NETUTIL_CMD_ARP_LOOKUP" Command */ typedef struct { _u16 NumOfRetries; /* number of retires for ARP request, range 1-20 */ _u16 Timeout; /* timeout between ARP requests, range 10-500 mSec , 10 mSec resolution*/ }NetUtilCmdArpLookupAttrib_t; /******************************************************************************/ /* Type declarations */ /******************************************************************************/ /*****************************************************************************/ /* Function prototypes */ /*****************************************************************************/ /*! \brief Function for setting configurations of utilities \param[in] Option Identifier of the specific "set" operation to perform \param[in] ObjID ID of the relevant object that this set operation will be performed on \param[in] ValueLen Length of the value parameter \param[in] pValues Pointer to the buffer holding the configurations values \return Zero on success, or negative error code on failure \sa sl_NetUtilGet sl_NetUtilCmd \note \warning */ #if _SL_INCLUDE_FUNC(sl_NetUtilSet) _i32 sl_NetUtilSet(const _u16 Option, const _u32 ObjID, const _u8 *pValues, const _u16 ValueLen); #endif /*! \brief Function for getting configurations of utilities \param[in] Option Identifier of the specific "get" operation to perform - SL_NETUTIL_CRYPTO_PUBLIC_KEY \n Used to retrieve the public key from an installed key-pair. \n Saved in a certain index. - SL_NETUTIL_TRUE_RANDOM \n Generates a random number using the internal TRNG of the NWP. \n \param[in] ObjID ID of the relevant object that this set operation will be performed on \param[in,out] pValueLen Pointer to the length of the value parameter\n On input - provides the length of the buffer that the application allocates, and will hold the output\n On output - provides the actual length of the received data \param[out] pValues Pointer to the buffer that the application allocates, and will hold the received data. \return Zero on success, or negative error code on failure. \sa sl_NetUtilSet sl_NetUtilCmd \note \warning \par Examples - SL_NETUTIL_CRYPTO_PUBLIC_KEY: \code int16_t Status; uint8_t configOpt = 0; uint32_t objId = 0; uint16_t configLen = 0; uint8_t key_buf[256]; configOpt = SL_NETUTIL_CRYPTO_PUBLIC_KEY; objId = 1; configLen = 255; //get the Public key Status = sl_NetUtilGet(configOpt, objId, key_buf, &configLen); \endcode - SL_NETUTIL_TRUE_RANDOM: \code uint32_t randNum; int32_t len = sizeof(uint32_t); sl_NetUtilGet(SL_NETUTIL_TRUE_RANDOM, 0, (uint8_t *)&randNum, &len); \endcode
*/ #if _SL_INCLUDE_FUNC(sl_NetUtilGet) _i16 sl_NetUtilGet(const _u16 Option, const _u32 ObjID, _u8 *pValues, _u16 *pValueLen); #endif /*! \brief Function for performing utilities-related commands \param[in] Cmd Identifier of the specific Command to perform - SL_NETUTIL_CRYPTO_CMD_INSTALL_OP \n Install / Uninstall key pairs in one or more of the crypto utils key-pair management mechanism. \n Key Must be an ECC key-pair using SECP256R1 curve and already programmed to file system, in DER format.\n Key installation is persistent. - SL_NETUTIL_CRYPTO_CMD_TEMP_KEYS \n Creates or removes a temporary key pair. \n Key pair is created internally by the NWP. Key pair is not persistent over power cycle. - SL_NETUTIL_CRYPTO_CMD_SIGN_MSG \n Signs with a digital signature a data buffer using ECDSA algorithm. \n - SL_NETUTIL_CRYPTO_CMD_VERIFY_MSG \n Verify a digital signature given with a data buffer using ECDSA algorithm. \n - SL_NETUTIL_CMD_ARP_LOOKUP \n Mapping MAC address to IPv4 or IPv6 address. \n \param[in] pAttrib Pointer to the buffer holding the Attribute values \param[in] AttribLen Length of the Attribute-values \param[in] pInputValues Pointer to the buffer holding the input-value \param[in] InputLen Length of the input-value \param[out] pOutputValues Pointer to the buffer that the application allocates, and will hold the received data. \param[in,out] pOutputLen Length of the output-value \n On input - provides the length of the buffer that the application allocates, and will hold the output\n On output - provides the actual length of the received output-values \return Zero on success, or negative error code on failure \sa sl_NetUtilGet sl_NetUtilSet \note The host driver API sl_NetUtilCmd is not valid for use with the CC3220R device. \n The SL_NETUTIL_CMD_ARP_LOOKUP cmd is only valid for the CC3235S/SF devices. \warning \par Examples - SL_NETUTIL_CRYPTO_CMD_INSTALL_OP (install / uninstall crypto keys): \code // Install a key SlNetUtilCryptoCmdKeyMgnt_t keyAttrib; SlNetUtilCryptoPubKeyInfo_t *pInfoKey; uint8_t name[FILE_NAME_SIZE]; int32_t Status; int16_t resultLen; keyAttrib.ObjId = 5; // Key would be stored at index 5 keyAttrib.SubCmd = SL_NETUTIL_CRYPTO_INSTALL_SUB_CMD; pInfoKey->KeyAlgo = SL_NETUTIL_CRYPTO_PUB_KEY_ALGO_EC; pInfoKey->KeyParams.EcParams.CurveType = SL_NETUTIL_CRYPTO_EC_CURVE_TYPE_NAMED; //ECC curve pInfoKey->KeyParams.EcParams.CurveParams.NamedCurveParams = SL_NETUTIL_CRYPTO_EC_NAMED_CURVE_SECP256R1; // SECP256R1 curve only. pInfoKey->CertFileNameLen = 0; name = ((uint8_t *)pInfoKey) + sizeof(SlNetUtilCryptoPubKeyInfo_t); name += pInfoKey->CertFileNameLen; strcpy((char *)name, "extkey.der"); // Private key name in file system. pInfoKey->KeyFileNameLen = strlen("extkey.der")+1; Status = sl_NetUtilCmd(SL_NETUTIL_CRYPTO_CMD_INSTALL_OP, (uint8_t *)&keyAttrib, sizeof(SlNetUtilCryptoCmdKeyMgnt_t), (uint8_t *)pInfo, sizeof(SlNetUtilCryptoPubKeyInfo_t) + pInfoKey->KeyFileNameLen, NULL, &resultLen); // Uninstall the Key: resultLen = 0; keyAttrib.ObjId = 5; keyAttrib.SubCmd = SL_NETUTIL_CRYPTO_UNINSTALL_SUB_CMD; Status = sl_NetUtilCmd(SL_NETUTIL_CRYPTO_CMD_INSTALL_OP, (uint8_t *)&keyAttrib, sizeof(SlNetUtilCryptoCmdKeyMgnt_t), NULL, 0 , NULL, &resultLen); \endcode - SL_NETUTIL_CRYPTO_CMD_TEMP_KEYS, (Create a temporary key ): \code SlNetUtilCryptoCmdKeyMgnt_t keyAttrib; int32_t Status; uint16_t resultLen; keyAttrib.ObjId = 1; // key index is 1 keyAttrib.SubCmd = SL_NETUTIL_CRYPTO_TEMP_KEYS_CREATE; Status = sl_NetUtilCmd(SL_NETUTIL_CRYPTO_CMD_TEMP_KEYS, (uint8_t *)&keyAttrib, sizeof(SlNetUtilCryptoCmdKeyMgnt_t), NULL, 0 , NULL, &resultLen); \endcode - SL_NETUTIL_CRYPTO_CMD_TEMP_KEYS, (Create a temporary key ): \code SlNetUtilCryptoCmdKeyMgnt_t keyAttrib; int32_t Status; uint16_t resultLen; keyAttrib.ObjId = 1; // key index is 1 keyAttrib.SubCmd = SL_NETUTIL_CRYPTO_TEMP_KEYS_CREATE; Status = sl_NetUtilCmd(SL_NETUTIL_CRYPTO_CMD_TEMP_KEYS, (uint8_t *)&keyAttrib, sizeof(SlNetUtilCryptoCmdKeyMgnt_t), NULL, 0 , NULL, &resultLen); \endcode - SL_NETUTIL_CRYPTO_CMD_SIGN_MSG, (Sign a data buffer): \code int32_t Status; int32_t configLen; uint8_t messageBuff[1500]; uint8_t sig_buf[256]; // This buffer shall contain the digital signature. SlNetUtilCryptoCmdSignAttrib_t signAttrib; signAttrib.Flags = 0; signAttrib.ObjId = 3; signAttrib.SigType = SL_NETUTIL_CRYPTO_SIG_SHAwECDSA; // this is the only type supported configLen = 255; Status = sl_NetUtilCmd(SL_NETUTIL_CRYPTO_CMD_SIGN_MSG, (uint8_t *)&signAttrib, sizeof(SlNetUtilCryptoCmdSignAttrib_t), messageBuff, sizeof(messageBuf), sig_buf, &configLen); \endcode - SL_NETUTIL_CRYPTO_CMD_VERIFY_MSG, (Verify a data buffer): \code int32_t Status; int32_t configLen; uint8_t verifyBuf[2048]; uint8_t messageBuff[1500]; uint8_t sig_buf[256]; // This buffer contains the digital signature. int32_t verifyResult; SlNetUtilCryptoCmdVerifyAttrib_t verAttrib; memcpy(verifyBuf, messageBuf, sizeof(messageBuf)); // copy the message to verify buffer. memcpy(verifyBuf + sizeof(messageBuff), sig_buf, configLen); // Append the signature to message buffer. verAttrib.Flags = 0; verAttrib.ObjId = 3; verAttrib.SigType = SL_NETUTIL_CRYPTO_SIG_SHAwECDSA; // this is the only type supported, if other hash algorithm // is wanted, SL_NETUTIL_CRYPTO_SIG_DIGESTwECDSA is used and // the verifyBuf should be the digest and MsgLen should be // the digest size verAttrib.MsgLen = sizeof(messageBuff); verAttrib.SigLen = configLen; configLen = 255; resultLen = 4; Status = sl_NetUtilCmd(SL_NETUTIL_CRYPTO_CMD_VERIFY_MSG, (uint8_t *)&verAttrib, sizeof(SlNetUtilCryptoCmdVerifyAttrib_t), verifyBuf, sizeof(messageBuf) + configLen, (uint8_t *)&verifyResult , &resultLen); \endcode
\endcode - SL_NETUTIL_CMD_ARP_LOOKUP, (Mapping MAC address to IPv4 or IPv6 address), CC3235S/SF devices only: \code NetUtilCmdArpLookupAttrib_t arpAttr; _u32 ipv4; _u8 macAddr[6]; _u16 outLen = sizeof(macAddr); _i16 status; ipv4 = SL_IPV4_VAL(192,168,178,43); arpAttr.NumOfRetries = 3; arpAttr.Timeout = 50; status = sl_NetUtilCmd(SL_NETUTIL_CMD_ARP_LOOKUP, (uint8_t *)&arpAttr, sizeof(arpAttr), (_u8*)&ipv4 , sizeof(ipv4), macAddr,&outLen); if(status != 0) { // MAC was not found } else { // IP address mapped to MAC } \endcode
*/ #if _SL_INCLUDE_FUNC(sl_NetUtilCmd) _i16 sl_NetUtilCmd(const _u16 Cmd, const _u8 *pAttrib, const _u16 AttribLen, const _u8 *pInputValues, const _u16 InputLen, _u8 *pOutputValues,_u16 *pOutputLen ); #endif /*! Close the Doxygen group. @} */ #ifdef __cplusplus } #endif /* __cplusplus */ #endif /* __NETUTIL_H__ */