Jim Flynn / Mbed OS aws-iot-device-sdk-mbed-c

Changes to enabled on-line compiler

include/network_interface.h@0:082731ede69f, 2018-05-30 (annotated)

Committer:
JMF
Date:
Wed May 30 20:59:51 2018 +0000
Revision:
0:082731ede69f
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
JMF 0:082731ede69f 1 /*
JMF 0:082731ede69f 2 * Copyright 2010-2015 Amazon.com, Inc. or its affiliates. All Rights Reserved.
JMF 0:082731ede69f 3 *
JMF 0:082731ede69f 4 * Licensed under the Apache License, Version 2.0 (the "License").
JMF 0:082731ede69f 5 * You may not use this file except in compliance with the License.
JMF 0:082731ede69f 6 * A copy of the License is located at
JMF 0:082731ede69f 7 *
JMF 0:082731ede69f 8 * http://aws.amazon.com/apache2.0
JMF 0:082731ede69f 9 *
JMF 0:082731ede69f 10 * or in the "license" file accompanying this file. This file is distributed
JMF 0:082731ede69f 11 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
JMF 0:082731ede69f 12 * express or implied. See the License for the specific language governing
JMF 0:082731ede69f 13 * permissions and limitations under the License.
JMF 0:082731ede69f 14 */
JMF 0:082731ede69f 15
JMF 0:082731ede69f 16 /**
JMF 0:082731ede69f 17 * @file network_interface.h
JMF 0:082731ede69f 18 * @brief Network interface definition for MQTT client.
JMF 0:082731ede69f 19 *
JMF 0:082731ede69f 20 * Defines an interface to the TLS layer to be used by the MQTT client.
JMF 0:082731ede69f 21 * Starting point for porting the SDK to the networking layer of a new platform.
JMF 0:082731ede69f 22 */
JMF 0:082731ede69f 23
JMF 0:082731ede69f 24 #ifndef __NETWORK_INTERFACE_H_
JMF 0:082731ede69f 25 #define __NETWORK_INTERFACE_H_
JMF 0:082731ede69f 26
JMF 0:082731ede69f 27 #ifdef __cplusplus
JMF 0:082731ede69f 28 extern "C" {
JMF 0:082731ede69f 29 #endif
JMF 0:082731ede69f 30
JMF 0:082731ede69f 31 #include <stdint.h>
JMF 0:082731ede69f 32 #include <stdbool.h>
JMF 0:082731ede69f 33 #include <aws_iot_error.h>
JMF 0:082731ede69f 34 #include "timer_interface.h"
JMF 0:082731ede69f 35 #include "network_platform.h"
JMF 0:082731ede69f 36
JMF 0:082731ede69f 37 /**
JMF 0:082731ede69f 38 * @brief Network Type
JMF 0:082731ede69f 39 *
JMF 0:082731ede69f 40 * Defines a type for the network struct. See structure definition below.
JMF 0:082731ede69f 41 */
JMF 0:082731ede69f 42 typedef struct Network Network;
JMF 0:082731ede69f 43
JMF 0:082731ede69f 44 /**
JMF 0:082731ede69f 45 * @brief TLS Connection Parameters
JMF 0:082731ede69f 46 *
JMF 0:082731ede69f 47 * Defines a type containing TLS specific parameters to be passed down to the
JMF 0:082731ede69f 48 * TLS networking layer to create a TLS secured socket.
JMF 0:082731ede69f 49 */
JMF 0:082731ede69f 50 typedef struct {
JMF 0:082731ede69f 51 char *pRootCALocation; ///< Pointer to string containing the filename (including path) of the root CA file.
JMF 0:082731ede69f 52 char *pDeviceCertLocation; ///< Pointer to string containing the filename (including path) of the device certificate.
JMF 0:082731ede69f 53 char *pDevicePrivateKeyLocation; ///< Pointer to string containing the filename (including path) of the device private key file.
JMF 0:082731ede69f 54 char *pDestinationURL; ///< Pointer to string containing the endpoint of the MQTT service.
JMF 0:082731ede69f 55 uint16_t DestinationPort; ///< Integer defining the connection port of the MQTT service.
JMF 0:082731ede69f 56 uint32_t timeout_ms; ///< Unsigned integer defining the TLS handshake timeout value in milliseconds.
JMF 0:082731ede69f 57 bool ServerVerificationFlag; ///< Boolean. True = perform server certificate hostname validation. False = skip validation \b NOT recommended.
JMF 0:082731ede69f 58 } TLSConnectParams;
JMF 0:082731ede69f 59
JMF 0:082731ede69f 60 /**
JMF 0:082731ede69f 61 * @brief Network Structure
JMF 0:082731ede69f 62 *
JMF 0:082731ede69f 63 * Structure for defining a network connection.
JMF 0:082731ede69f 64 */
JMF 0:082731ede69f 65 struct Network {
JMF 0:082731ede69f 66 IoT_Error_t (*connect)(Network *, TLSConnectParams *);
JMF 0:082731ede69f 67
JMF 0:082731ede69f 68 IoT_Error_t (*read)(Network *, unsigned char *, size_t, awsTimer *, size_t *); ///< Function pointer pointing to the network function to read from the network
JMF 0:082731ede69f 69 IoT_Error_t (*write)(Network *, unsigned char *, size_t, awsTimer *, size_t *); ///< Function pointer pointing to the network function to write to the network
JMF 0:082731ede69f 70 IoT_Error_t (*disconnect)(Network *); ///< Function pointer pointing to the network function to disconnect from the network
JMF 0:082731ede69f 71 IoT_Error_t (*isConnected)(Network *); ///< Function pointer pointing to the network function to check if TLS is connected
JMF 0:082731ede69f 72 IoT_Error_t (*destroy)(Network *); ///< Function pointer pointing to the network function to destroy the network object
JMF 0:082731ede69f 73
JMF 0:082731ede69f 74 TLSConnectParams tlsConnectParams; ///< TLSConnect params structure containing the common connection parameters
JMF 0:082731ede69f 75 TLSDataParams tlsDataParams; ///< TLSData params structure containing the connection data parameters that are specific to the library being used
JMF 0:082731ede69f 76 };
JMF 0:082731ede69f 77
JMF 0:082731ede69f 78 /**
JMF 0:082731ede69f 79 * @brief Initialize the TLS implementation
JMF 0:082731ede69f 80 *
JMF 0:082731ede69f 81 * Perform any initialization required by the TLS layer.
JMF 0:082731ede69f 82 * Connects the interface to implementation by setting up
JMF 0:082731ede69f 83 * the network layer function pointers to platform implementations.
JMF 0:082731ede69f 84 *
JMF 0:082731ede69f 85 * @param pNetwork - Pointer to a Network struct defining the network interface.
JMF 0:082731ede69f 86 * @param pRootCALocation - Path of the location of the Root CA
JMF 0:082731ede69f 87 * @param pDeviceCertLocation - Path to the location of the Device Cert
JMF 0:082731ede69f 88 * @param pDevicyPrivateKeyLocation - Path to the location of the device private key file
JMF 0:082731ede69f 89 * @param pDestinationURL - The target endpoint to connect to
JMF 0:082731ede69f 90 * @param DestinationPort - The port on the target to connect to
JMF 0:082731ede69f 91 * @param timeout_ms - The value to use for timeout of operation
JMF 0:082731ede69f 92 * @param ServerVerificationFlag - used to decide whether server verification is needed or not
JMF 0:082731ede69f 93 *
JMF 0:082731ede69f 94 * @return IoT_Error_t - successful initialization or TLS error
JMF 0:082731ede69f 95 */
JMF 0:082731ede69f 96 IoT_Error_t iot_tls_init(Network *pNetwork, char *pRootCALocation, char *pDeviceCertLocation,
JMF 0:082731ede69f 97 char *pDevicePrivateKeyLocation, char *pDestinationURL,
JMF 0:082731ede69f 98 uint16_t DestinationPort, uint32_t timeout_ms, bool ServerVerificationFlag);
JMF 0:082731ede69f 99
JMF 0:082731ede69f 100 /**
JMF 0:082731ede69f 101 * @brief Create a TLS socket and open the connection
JMF 0:082731ede69f 102 *
JMF 0:082731ede69f 103 * Creates an open socket connection including TLS handshake.
JMF 0:082731ede69f 104 *
JMF 0:082731ede69f 105 * @param pNetwork - Pointer to a Network struct defining the network interface.
JMF 0:082731ede69f 106 * @param TLSParams - TLSConnectParams defines the properties of the TLS connection.
JMF 0:082731ede69f 107 * @return IoT_Error_t - successful connection or TLS error
JMF 0:082731ede69f 108 */
JMF 0:082731ede69f 109 IoT_Error_t iot_tls_connect(Network *pNetwork, TLSConnectParams *TLSParams);
JMF 0:082731ede69f 110
JMF 0:082731ede69f 111 /**
JMF 0:082731ede69f 112 * @brief Write bytes to the network socket
JMF 0:082731ede69f 113 *
JMF 0:082731ede69f 114 * @param Network - Pointer to a Network struct defining the network interface.
JMF 0:082731ede69f 115 * @param unsigned char pointer - buffer to write to socket
JMF 0:082731ede69f 116 * @param integer - number of bytes to write
JMF 0:082731ede69f 117 * @param awsTimer * - operation timer
JMF 0:082731ede69f 118 * @return integer - number of bytes written or TLS error
JMF 0:082731ede69f 119 * @return IoT_Error_t - successful write or TLS error code
JMF 0:082731ede69f 120 */
JMF 0:082731ede69f 121 IoT_Error_t iot_tls_write(Network *, unsigned char *, size_t, awsTimer *, size_t *);
JMF 0:082731ede69f 122
JMF 0:082731ede69f 123 /**
JMF 0:082731ede69f 124 * @brief Read bytes from the network socket
JMF 0:082731ede69f 125 *
JMF 0:082731ede69f 126 * @param Network - Pointer to a Network struct defining the network interface.
JMF 0:082731ede69f 127 * @param unsigned char pointer - pointer to buffer where read bytes should be copied
JMF 0:082731ede69f 128 * @param size_t - number of bytes to read
JMF 0:082731ede69f 129 * @param awsTimer * - operation timer
JMF 0:082731ede69f 130 * @param size_t - pointer to store number of bytes read
JMF 0:082731ede69f 131 * @return IoT_Error_t - successful read or TLS error code
JMF 0:082731ede69f 132 */
JMF 0:082731ede69f 133 IoT_Error_t iot_tls_read(Network *, unsigned char *, size_t, awsTimer *, size_t *);
JMF 0:082731ede69f 134
JMF 0:082731ede69f 135 /**
JMF 0:082731ede69f 136 * @brief Disconnect from network socket
JMF 0:082731ede69f 137 *
JMF 0:082731ede69f 138 * @param Network - Pointer to a Network struct defining the network interface.
JMF 0:082731ede69f 139 * @return IoT_Error_t - successful read or TLS error code
JMF 0:082731ede69f 140 */
JMF 0:082731ede69f 141 IoT_Error_t iot_tls_disconnect(Network *pNetwork);
JMF 0:082731ede69f 142
JMF 0:082731ede69f 143 /**
JMF 0:082731ede69f 144 * @brief Perform any tear-down or cleanup of TLS layer
JMF 0:082731ede69f 145 *
JMF 0:082731ede69f 146 * Called to cleanup any resources required for the TLS layer.
JMF 0:082731ede69f 147 *
JMF 0:082731ede69f 148 * @param Network - Pointer to a Network struct defining the network interface
JMF 0:082731ede69f 149 * @return IoT_Error_t - successful cleanup or TLS error code
JMF 0:082731ede69f 150 */
JMF 0:082731ede69f 151 IoT_Error_t iot_tls_destroy(Network *pNetwork);
JMF 0:082731ede69f 152
JMF 0:082731ede69f 153 /**
JMF 0:082731ede69f 154 * @brief Check if TLS layer is still connected
JMF 0:082731ede69f 155 *
JMF 0:082731ede69f 156 * Called to check if the TLS layer is still connected or not.
JMF 0:082731ede69f 157 *
JMF 0:082731ede69f 158 * @param Network - Pointer to a Network struct defining the network interface
JMF 0:082731ede69f 159 * @return IoT_Error_t - TLS error code indicating status of network physical layer connection
JMF 0:082731ede69f 160 */
JMF 0:082731ede69f 161 IoT_Error_t iot_tls_is_connected(Network *pNetwork);
JMF 0:082731ede69f 162
JMF 0:082731ede69f 163 #ifdef __cplusplus
JMF 0:082731ede69f 164 }
JMF 0:082731ede69f 165 #endif
JMF 0:082731ede69f 166
JMF 0:082731ede69f 167 #endif //__NETWORK_INTERFACE_H_