Pierre-Marie Ancèle / Mbed OS AWS-test

test

aws-iot/include/network_interface.h@1:3f75eb8d46f4, 2017-04-12 (annotated)

Committer:
peyo
Date:
Wed Apr 12 14:09:46 2017 +0200
Revision:
1:3f75eb8d46f4
Parent:
0:cd5404401c2f 
add main

Who changed what in which revision?

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