network_interface.h

00001 /*
00002  * Copyright 2010-2015 Amazon.com, Inc. or its affiliates. All Rights Reserved.
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License").
00005  * You may not use this file except in compliance with the License.
00006  * A copy of the License is located at
00007  *
00008  *  http://aws.amazon.com/apache2.0
00009  *
00010  * or in the "license" file accompanying this file. This file is distributed
00011  * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
00012  * express or implied. See the License for the specific language governing
00013  * permissions and limitations under the License.
00014  */
00015 
00016 /**
00017  * @file network_interface.h
00018  * @brief Network interface definition for MQTT client.
00019  *
00020  * Defines an interface to the TLS layer to be used by the MQTT client.
00021  * Starting point for porting the SDK to the networking layer of a new platform.
00022  */
00023 
00024 #ifndef __NETWORK_INTERFACE_H_
00025 #define __NETWORK_INTERFACE_H_
00026 
00027 #ifdef __cplusplus
00028 extern "C" {
00029 #endif
00030 
00031 #include <stdint.h>
00032 #include <stdbool.h>
00033 #include <aws_iot_error.h>
00034 #include "timer_interface.h"
00035 #include "network_platform.h"
00036 
00037 /**
00038  * @brief Network Type
00039  *
00040  * Defines a type for the network struct.  See structure definition below.
00041  */
00042 typedef struct Network Network;
00043 
00044 /**
00045  * @brief TLS Connection Parameters
00046  *
00047  * Defines a type containing TLS specific parameters to be passed down to the
00048  * TLS networking layer to create a TLS secured socket.
00049  */
00050 typedef struct {
00051     char *pRootCALocation;                ///< Pointer to string containing the filename (including path) of the root CA file.
00052     char *pDeviceCertLocation;            ///< Pointer to string containing the filename (including path) of the device certificate.
00053     char *pDevicePrivateKeyLocation;    ///< Pointer to string containing the filename (including path) of the device private key file.
00054     char *pDestinationURL;                ///< Pointer to string containing the endpoint of the MQTT service.
00055     uint16_t DestinationPort;            ///< Integer defining the connection port of the MQTT service.
00056     uint32_t timeout_ms;                ///< Unsigned integer defining the TLS handshake timeout value in milliseconds.
00057     bool ServerVerificationFlag;        ///< Boolean.  True = perform server certificate hostname validation.  False = skip validation \b NOT recommended.
00058 } TLSConnectParams;
00059 
00060 /**
00061  * @brief Network Structure
00062  *
00063  * Structure for defining a network connection.
00064  */
00065 struct Network {
00066     IoT_Error_t (*connect)(Network *, TLSConnectParams *);
00067 
00068     IoT_Error_t (*read)(Network *, unsigned char *, size_t, TimerAWS *, size_t *);    ///< Function pointer pointing to the network function to read from the network
00069     IoT_Error_t (*write)(Network *, unsigned char *, size_t, TimerAWS *, size_t *);    ///< Function pointer pointing to the network function to write to the network
00070     IoT_Error_t (*disconnect)(Network *);    ///< Function pointer pointing to the network function to disconnect from the network
00071     IoT_Error_t (*isConnected)(Network *);    ///< Function pointer pointing to the network function to check if TLS is connected
00072     IoT_Error_t (*destroy)(Network *);        ///< Function pointer pointing to the network function to destroy the network object
00073 
00074     TLSConnectParams tlsConnectParams;        ///< TLSConnect params structure containing the common connection parameters
00075     TLSDataParams tlsDataParams;            ///< TLSData params structure containing the connection data parameters that are specific to the library being used
00076 };
00077 
00078 /**
00079  * @brief Initialize the TLS implementation
00080  *
00081  * Perform any initialization required by the TLS layer.
00082  * Connects the interface to implementation by setting up
00083  * the network layer function pointers to platform implementations.
00084  *
00085  * @param pNetwork - Pointer to a Network struct defining the network interface.
00086  * @param pRootCALocation - Path of the location of the Root CA
00087  * @param pDeviceCertLocation - Path to the location of the Device Cert
00088  * @param pDevicyPrivateKeyLocation - Path to the location of the device private key file
00089  * @param pDestinationURL - The target endpoint to connect to
00090  * @param DestinationPort - The port on the target to connect to
00091  * @param timeout_ms - The value to use for timeout of operation
00092  * @param ServerVerificationFlag - used to decide whether server verification is needed or not
00093  *
00094  * @return IoT_Error_t - successful initialization or TLS error
00095  */
00096 IoT_Error_t iot_tls_init(Network *pNetwork, char *pRootCALocation, char *pDeviceCertLocation,
00097                          char *pDevicePrivateKeyLocation, char *pDestinationURL,
00098                          uint16_t DestinationPort, uint32_t timeout_ms, bool ServerVerificationFlag);
00099 
00100 /**
00101  * @brief Create a TLS socket and open the connection
00102  *
00103  * Creates an open socket connection including TLS handshake.
00104  *
00105  * @param pNetwork - Pointer to a Network struct defining the network interface.
00106  * @param TLSParams - TLSConnectParams defines the properties of the TLS connection.
00107  * @return IoT_Error_t - successful connection or TLS error
00108  */
00109 IoT_Error_t iot_tls_connect(Network *pNetwork, TLSConnectParams *TLSParams);
00110 
00111 /**
00112  * @brief Write bytes to the network socket
00113  *
00114  * @param Network - Pointer to a Network struct defining the network interface.
00115  * @param unsigned char pointer - buffer to write to socket
00116  * @param integer - number of bytes to write
00117  * @param Timer * - operation timer
00118  * @return integer - number of bytes written or TLS error
00119  * @return IoT_Error_t - successful write or TLS error code
00120  */
00121 IoT_Error_t iot_tls_write(Network *, unsigned char *, size_t, TimerAWS *, size_t *);
00122 
00123 /**
00124  * @brief Read bytes from the network socket
00125  *
00126  * @param Network - Pointer to a Network struct defining the network interface.
00127  * @param unsigned char pointer - pointer to buffer where read bytes should be copied
00128  * @param size_t - number of bytes to read
00129  * @param Timer * - operation timer
00130  * @param size_t - pointer to store number of bytes read
00131  * @return IoT_Error_t - successful read or TLS error code
00132  */
00133 IoT_Error_t iot_tls_read(Network *, unsigned char *, size_t, TimerAWS *, size_t *);
00134 
00135 /**
00136  * @brief Disconnect from network socket
00137  *
00138  * @param Network - Pointer to a Network struct defining the network interface.
00139  * @return IoT_Error_t - successful read or TLS error code
00140  */
00141 IoT_Error_t iot_tls_disconnect(Network *pNetwork);
00142 
00143 /**
00144  * @brief Perform any tear-down or cleanup of TLS layer
00145  *
00146  * Called to cleanup any resources required for the TLS layer.
00147  *
00148  * @param Network - Pointer to a Network struct defining the network interface
00149  * @return IoT_Error_t - successful cleanup or TLS error code
00150  */
00151 IoT_Error_t iot_tls_destroy(Network *pNetwork);
00152 
00153 /**
00154  * @brief Check if TLS layer is still connected
00155  *
00156  * Called to check if the TLS layer is still connected or not.
00157  *
00158  * @param Network - Pointer to a Network struct defining the network interface
00159  * @return IoT_Error_t - TLS error code indicating status of network physical layer connection
00160  */
00161 IoT_Error_t iot_tls_is_connected(Network *pNetwork);
00162 
00163 #ifdef __cplusplus
00164 }
00165 #endif
00166 
00167 #endif //__NETWORK_INTERFACE_H_