m2m_ssl.h

00001 /**
00002  *
00003  * \file
00004  *
00005  * \brief WINC Application Interface Internal Types.
00006  *
00007  * Copyright (c) 2017 Atmel Corporation. All rights reserved.
00008  *
00009  * \asf_license_start
00010  *
00011  * \page License
00012  *
00013  * Redistribution and use in source and binary forms, with or without
00014  * modification, are permitted provided that the following conditions are met:
00015  *
00016  * 1. Redistributions of source code must retain the above copyright notice,
00017  *    this list of conditions and the following disclaimer.
00018  *
00019  * 2. Redistributions in binary form must reproduce the above copyright notice,
00020  *    this list of conditions and the following disclaimer in the documentation
00021  *    and/or other materials provided with the distribution.
00022  *
00023  * 3. The name of Atmel may not be used to endorse or promote products derived
00024  *    from this software without specific prior written permission.
00025  *
00026  * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
00027  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
00028  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
00029  * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
00030  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00031  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
00032  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00033  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
00034  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00035  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00036  * POSSIBILITY OF SUCH DAMAGE.
00037  *
00038  * \asf_license_stop
00039  *
00040  */
00041 
00042 /**@defgroup SSLAPI SSL
00043 */
00044 
00045 #ifndef __M2M_SSL_H__
00046 #define __M2M_SSL_H__
00047 
00048 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
00049 INCLUDES
00050 *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
00051 
00052 #include "common/include/nm_common.h"
00053 #include "driver/include/m2m_types.h"
00054 #include "driver/source/nmdrv.h"
00055 #include "ecc_types.h"
00056 #include "socket/include/socket.h"
00057 
00058 /**@defgroup  SSLEnums Enumeration/Typedefs
00059  * @ingroup SSLAPI
00060  * @{*/
00061 
00062 /*!
00063 @typedef \
00064     void (*tpfAppSslCb) (uint8 u8MsgType, void * pvMsg);
00065 
00066 @brief A callback to get SSL notifications.
00067 
00068 @param[in] u8MsgType
00069 @param[in] pvMsg A structure to provide notification payload.
00070 */
00071 typedef void (*tpfAppSSLCb) (uint8 u8MsgType, void * pvMsg);
00072 
00073 /**@}
00074 */
00075 
00076 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
00077 FUNCTION PROTOTYPES
00078 *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
00079 /** \defgroup SSLFUNCTIONS Functions
00080 *  @ingroup SSLAPI
00081 */
00082 
00083 /**@{*/
00084 /*!
00085     @fn \   m2m_ssl_init(tpfAppSslCb pfAppSslCb);
00086     @brief  Initializes the SSL layer.
00087     @param [in] pfAppSslCb
00088                 Application SSL callback function.
00089     @return     The function SHALL return 0 for success and a negative value otherwise.
00090 */
00091 NMI_API sint8 m2m_ssl_init(tpfAppSSLCb pfAppSSLCb);
00092 
00093 /*!
00094     @fn \    NMI_API sint8 m2m_ssl_handshake_rsp(tstrEccReqInfo* strECCResp, uint8* pu8RspDataBuff, uint16 u16RspDataSz)
00095     @brief   Sends ECC responses to the WINC
00096     @param [in] strECCResp
00097                 ECC Response struct.
00098     @param [in] pu8RspDataBuffe
00099                 Pointer of the response data to be sent.
00100     @param [in] u16RspDataSz
00101                 Response data size.
00102     @return     The function SHALL return 0 for success and a negative value otherwise.
00103 */
00104 NMI_API sint8 m2m_ssl_handshake_rsp(tstrEccReqInfo* strECCResp, uint8* pu8RspDataBuff, uint16 u16RspDataSz);
00105 
00106 /*!
00107     @fn \   NMI_API sint8 m2m_ssl_send_certs_to_winc(uint8* pu8Buffer, uint32 u32BufferSz)
00108     @brief  Sends certificates to the WINC
00109     @param [in] pu8Buffer
00110                 Pointer to the certificates.
00111     @param [in] u32BufferSz
00112                 Size of the certificates.
00113     @return     The function SHALL return 0 for success and a negative value otherwise.
00114 */
00115 NMI_API sint8 m2m_ssl_send_certs_to_winc(uint8* pu8Buffer, uint32 u32BufferSz);
00116 
00117 /*!
00118     @fn \   NMI_API sint8 m2m_ssl_retrieve_cert(uint16* pu16CurveType, uint8* pu8Hash, uint8* pu8Sig, tstrECPoint* pu8Key)
00119     @brief  Retrieve the certificate to be verified from the WINC
00120     @param [in] pu16CurveType
00121                 Pointer to the certificate curve type.
00122     @param [in] pu8Hash
00123                 Pointer to the certificate hash.
00124     @param [in] pu8Sig
00125                 Pointer to the certificate signature.
00126     @param [in] pu8Key
00127                 Pointer to the certificate Key.
00128     @return     The function SHALL return 0 for success and a negative value otherwise.
00129 */
00130 NMI_API sint8 m2m_ssl_retrieve_cert(uint16* pu16CurveType, uint8* pu8Hash, uint8* pu8Sig, tstrECPoint* pu8Key);
00131 
00132 /*!
00133     @fn \   NMI_API sint8 m2m_ssl_retrieve_hash(uint8* pu8Hash, uint16 u16HashSz)
00134     @brief  Retrieve the certificate hash
00135     @param [in] pu8Hash
00136                 Pointer to the certificate hash.
00137     @param [in] u16HashSz
00138                 Hash size.
00139     @return     The function SHALL return 0 for success and a negative value otherwise.
00140 */
00141 NMI_API sint8 m2m_ssl_retrieve_hash(uint8* pu8Hash, uint16 u16HashSz);
00142 
00143 /*!
00144     @fn \   NMI_API void m2m_ssl_stop_processing_certs(void)
00145     @brief  Allow ssl driver to tidy up in case application does not read all available certificates.
00146     @warning    This API must only be called if some certificates are left unread.
00147     @return     None.
00148 */
00149 NMI_API void m2m_ssl_stop_processing_certs(void);
00150 
00151 /*!
00152     @fn \   NMI_API void m2m_ssl_ecc_process_done(void)
00153     @brief  Allow ssl driver to tidy up after application has finished processing ecc message.
00154     @warning    This API must be called after receiving a SSL callback with type @ref M2M_SSL_REQ_ECC
00155     @return     None.
00156 */
00157 NMI_API void m2m_ssl_ecc_process_done(void);
00158 
00159 /*!
00160 @fn \
00161     NMI_API sint8 m2m_ssl_set_active_ciphersuites(uint32 u32SslCsBMP);
00162     Override the default Active SSL ciphers in the SSL module with a certain combination selected by the caller in the form of
00163     a bitmap containing the required ciphers to be on.
00164     There is no need to call this function if the application will not change the default ciphersuites.
00165 
00166 @param [in] u32SslCsBMP
00167                 Bitmap containing the desired ciphers to be enabled for the SSL module. The ciphersuites are defined in
00168                 @ref SSLCipherSuiteID.
00169                 The default ciphersuites are all ciphersuites supported by the firmware with the exception of ECC ciphersuites.
00170                 The caller can override the default with any desired combination, except for combinations involving both RSA
00171                 and ECC; if any RSA ciphersuite is enabled, then firmware will disable all ECC ciphersuites.
00172                 If u32SslCsBMP does not contain any ciphersuites supported by firmware, then the current active list will not
00173                 be changed.
00174 
00175 @return     
00176     - [SOCK_ERR_NO_ERROR](@ref SOCK_ERR_NO_ERROR)
00177     - [SOCK_ERR_INVALID_ARG](@ref SOCK_ERR_INVALID_ARG)
00178 */
00179 sint8 m2m_ssl_set_active_ciphersuites (uint32 u32SslCsBMP);
00180 
00181  /**@}*/
00182 #endif /* __M2M_SSL_H__ */