ConnectorClient.h

00001 // ----------------------------------------------------------------------------
00002 // Copyright 2016-2017 ARM Ltd.
00003 //
00004 // SPDX-License-Identifier: Apache-2.0
00005 //
00006 // Licensed under the Apache License, Version 2.0 (the "License");
00007 // you may not use this file except in compliance with the License.
00008 // You may obtain a copy of the License at
00009 //
00010 //     http://www.apache.org/licenses/LICENSE-2.0
00011 //
00012 // Unless required by applicable law or agreed to in writing, software
00013 // distributed under the License is distributed on an "AS IS" BASIS,
00014 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00015 // See the License for the specific language governing permissions and
00016 // limitations under the License.
00017 // ----------------------------------------------------------------------------
00018 
00019 #ifndef __CONNECTOR_CLIENT_H__
00020 #define __CONNECTOR_CLIENT_H__
00021 
00022 #include "mbed-client/functionpointer.h"
00023 #include "mbed-client/m2minterfacefactory.h"
00024 #include "mbed-client/m2mdevice.h"
00025 #include "mbed-client/m2minterfaceobserver.h"
00026 #include "mbed-client/m2minterface.h"
00027 #include "mbed-client/m2mobjectinstance.h"
00028 #include "mbed-client/m2mresource.h"
00029 #include "mbed-client/m2mtimerobserver.h"
00030 #include "mbed-client/m2mtimer.h"
00031 #include "include/CloudClientStorage.h"
00032 
00033 #ifndef MBED_CLIENT_DISABLE_EST_FEATURE
00034 #include "include/EstClient.h"
00035 #endif // !MBED_CLIENT_DISABLE_EST_FEATURE
00036 
00037 class ConnectorClientCallback;
00038 
00039 #if MBED_CLOUD_CLIENT_STD_NAMESPACE_POLLUTION
00040 // We should not really pollute application's namespace with std by having this in
00041 // a public header file.
00042 // But as as removal of the next line may break existing applications, which build due to this
00043 // leakage, we need to maintain the old behavior for a while and just allow one to remove it.
00044 using namespace std;
00045 #endif
00046 
00047 
00048 /**
00049  * \brief ConnectorClientEndpointInfo
00050  * A structure that contains the needed endpoint information to register with the Cloud service.
00051  * Note: this should be changed to a class instead of struct and/or members changed to "const char*".
00052  */
00053 struct ConnectorClientEndpointInfo {
00054 
00055 public:
00056     ConnectorClientEndpointInfo(M2MSecurity::SecurityModeType m) : mode(m) {};
00057     ~ConnectorClientEndpointInfo() {};
00058 
00059 public:
00060 
00061     String                          endpoint_name;
00062     String                          account_id;
00063     String                          internal_endpoint_name;
00064     M2MSecurity::SecurityModeType   mode;
00065 #ifdef MBED_CLOUD_CLIENT_EDGE_EXTENSION
00066     String                          lwm2m_server_uri;
00067 #endif
00068 };
00069 
00070 /**
00071  * \brief ConnectorClient
00072  * This class is an interface towards the M2MInterface client to handle all
00073  * data flow towards Connector through this client.
00074  * This class is intended to be used via ServiceClient, not directly.
00075  * This class contains also the bootstrap functionality.
00076  */
00077 class ConnectorClient : public M2MInterfaceObserver, public M2MTimerObserver {
00078 
00079 public:
00080     /**
00081      * \brief An enum defining the different states of
00082      * ConnectorClient during the client flow.
00083      */
00084     enum StartupSubStateRegistration {
00085         State_Bootstrap_Start,
00086         State_Bootstrap_Started,
00087         State_Bootstrap_Success,
00088         State_Bootstrap_Failure,
00089 #ifndef MBED_CLIENT_DISABLE_EST_FEATURE
00090         State_EST_Start,
00091         State_EST_Started,
00092         State_EST_Success,
00093         State_EST_Failure,
00094 #endif // !MBED_CLIENT_DISABLE_EST_FEATURE
00095         State_Registration_Start,
00096         State_Registration_Started,
00097         State_Registration_Success,
00098         State_Registration_Failure,
00099         State_Registration_Updated,
00100         State_Unregistered
00101     };
00102 
00103 public:
00104 
00105     /**
00106     *  \brief Constructor.
00107     *  \param callback, A callback for the status from ConnectorClient.
00108     */
00109     ConnectorClient(ConnectorClientCallback* callback);
00110 
00111     /**
00112     *  \brief Destructor.
00113     */
00114     ~ConnectorClient();
00115 
00116     /**
00117      * \brief Perform the second phase set up which is not possible from constructor.
00118      * This must be called successfully after constructor and before
00119      * continuing to state machine.
00120      * \return true, if success and instance is ready to use
00121      */
00122     bool setup();
00123 
00124     /**
00125     *  \brief Starts the bootstrap sequence from the Service Client.
00126     */
00127     void start_bootstrap();
00128 
00129     /**
00130     *  \brief Starts the registration sequence from the Service Client.
00131     *  \param client_objs, A list of objects implementing the M2MBase interface to be registered with Cloud.
00132     */
00133     void start_registration(M2MBaseList* client_objs);
00134 
00135     /**
00136     *  \brief Sends an update registration message to the LWM2M server.
00137     */
00138     void update_registration();
00139 
00140     /**
00141      * \brief Returns the M2MInterface handler.
00142      * \return M2MInterface, Handled for M2MInterface.
00143     */
00144     M2MInterface * m2m_interface();
00145 
00146     /**
00147      * \brief Checks whether to use Bootstrap or direct Connector mode.
00148      * \return True if bootstrap mode, False if direct Connector flow
00149     */
00150     bool use_bootstrap();
00151 
00152     /**
00153      * \brief Checks whether to go connector registration flow
00154      * \return True if connector credentials available otherwise false.
00155     */
00156     bool connector_credentials_available();
00157 
00158     /**
00159      * \brief A utility function to generate the key name.
00160      * \param key, The key to get the value for.
00161      * \param endpoint, The name of the endpoint to be appended
00162      * to the key.
00163      * \param key_name, The [OUT] final key name.
00164      * \return True if available, else false.
00165     */
00166     bool get_key(const char *key, const char *endpoint, char *&key_name);
00167 
00168     /**
00169      * \brief Returns pointer to the ConnectorClientEndpointInfo object.
00170      * \return ConnectorClientEndpointInfo pointer.
00171     */
00172    const ConnectorClientEndpointInfo *endpoint_info() const;
00173 
00174    /**
00175     * \brief Returns KCM Certificate chain handle pointer.
00176     * \return KCM Certificate chain handle pointer.
00177     */
00178    void *certificate_chain_handle() const;
00179 
00180    /**
00181     * \brief Sets the KCM certificate chain handle pointer.
00182     * \param cert_handle KCM Certificate chain handle.
00183     */
00184    void set_certificate_chain_handle(void *cert_handle);
00185 
00186 #ifndef MBED_CLIENT_DISABLE_EST_FEATURE
00187    static void est_enrollment_result(est_enrollment_result_e result,
00188                                      cert_chain_context_s *cert_chain,
00189                                      void *context);
00190 
00191    /**
00192     * \brief Get reference to the EST client instance.
00193    */
00194    const EstClient &est_client();
00195 #endif /* MBED_CLIENT_DISABLE_EST_FEATURE */
00196 
00197    /**
00198    * \brief Starts bootstrap sequence again.
00199    * This will clean the old LwM2M credentials.
00200    *
00201    */
00202    void bootstrap_again();
00203 
00204 public:
00205     // implementation of M2MInterfaceObserver:
00206 
00207     /**
00208      * \brief A callback indicating that the bootstap has been performed successfully.
00209      * \param server_object, The server object that contains the information fetched
00210      * about the LWM2M server from the bootstrap server. This object can be used
00211      * to register with the LWM2M server. The object ownership is passed.
00212      */
00213     virtual void bootstrap_done(M2MSecurity *server_object);
00214 
00215     /**
00216      * \brief A callback indicating when all bootstrap data has been received.
00217      * \param security_object, The security object that contains the security information.
00218      */
00219     virtual void bootstrap_data_ready(M2MSecurity *security_object);
00220 
00221     /**
00222      * \brief A callback indicating that the device object has been registered
00223      * successfully with the LWM2M server.
00224      * \param security_object, The server object on which the device object is
00225      * registered. The object ownership is passed.
00226      * \param server_object, An object containing information about the LWM2M server.
00227      * The client maintains the object.
00228      */
00229     virtual void object_registered(M2MSecurity *security_object, const M2MServer &server_object);
00230 
00231     /**
00232      * \brief A callback indicating that the device object has been successfully unregistered
00233      * from the LWM2M server.
00234      * \param server_object, The server object from which the device object is
00235      * unregistered. The object ownership is passed.
00236      */
00237     virtual void object_unregistered(M2MSecurity *server_object);
00238 
00239     /**
00240      * \brief A callback indicating that the device object registration has been successfully
00241      * updated on the LWM2M server.
00242      * \param security_object, The server object on which the device object registration is
00243      * updated. The object ownership is passed.
00244      * \param server_object, An object containing information about the LWM2M server.
00245      * The client maintains the object.
00246      */
00247     virtual void registration_updated(M2MSecurity *security_object, const M2MServer & server_object);
00248 
00249     /**
00250      * \brief A callback indicating that there was an error during the operation.
00251      * \param error, An error code for the occurred error.
00252      */
00253     virtual void error(M2MInterface::Error error);
00254 
00255     /**
00256      * \brief A callback indicating that the value of the resource object is updated by the server.
00257      * \param base, The object whose value is updated.
00258      * \param type, The type of the object.
00259      */
00260     virtual void value_updated(M2MBase *base, M2MBase::BaseType type);
00261 
00262 protected: // from M2MTimerObserver
00263 
00264     virtual void timer_expired(M2MTimerObserver::Type type);
00265 
00266 private:
00267     /**
00268      * \brief Redirects the state machine to right function.
00269      * \param current_state, The current state to be set.
00270      * \param data, The data to be passed to the state function.
00271      */
00272     void state_function(StartupSubStateRegistration current_state);
00273 
00274     /**
00275      * \brief The state engine maintaining the state machine logic.
00276      */
00277     void state_engine(void);
00278 
00279     /**
00280     * \brief An internal event generated by the state machine.
00281     * \param new_state, The new state to which the state machine should go.
00282     * \param data, The data to be passed to the state machine.
00283     */
00284     void internal_event(StartupSubStateRegistration new_state);
00285 
00286     /**
00287     * When the bootstrap starts.
00288     */
00289     void state_bootstrap_start();
00290 
00291     /**
00292     * When the bootstrap is started.
00293     */
00294     void state_bootstrap_started();
00295 
00296     /**
00297     * When the bootstrap is successful.
00298     */
00299     void state_bootstrap_success();
00300 
00301     /**
00302     * When the bootstrap failed.
00303     */
00304     void state_bootstrap_failure();
00305 
00306 #ifndef MBED_CLIENT_DISABLE_EST_FEATURE
00307     /**
00308      * When the EST (enrollment-over-secure-transport) enrollment starts.
00309      */
00310     void state_est_start();
00311 
00312     /**
00313      * When the EST (enrollment-over-secure-transport) enrollment has been started.
00314      */
00315     void state_est_started();
00316 
00317     /**
00318      * When the EST (enrollment-over-secure-transport) enrollment is successful.
00319      */
00320     void state_est_success();
00321 
00322     /**
00323      * When the EST (enrollment-over-secure-transport) enrollment failed.
00324      */
00325     void state_est_failure();
00326 #endif // !MBED_CLIENT_DISABLE_EST_FEATURE
00327 
00328     /**
00329     * When the registration starts.
00330     */
00331     void state_registration_start();
00332 
00333     /**
00334     * When the registration started.
00335     */
00336     void state_registration_started();
00337 
00338     /**
00339     * When the registration is successful.
00340     */
00341     void state_registration_success();
00342 
00343     /**
00344      * When the registration failed.
00345     */
00346     void state_registration_failure();
00347 
00348     /**
00349     * When the client is unregistered.
00350     */
00351     void state_unregistered();
00352 
00353     /**
00354      * \brief A utility function to create an M2MSecurity object
00355      * for registration.
00356      */
00357     bool create_register_object();
00358 
00359     /**
00360      * \brief A utility function to create an M2MSecurity object
00361      * for bootstrap.
00362      */
00363     bool create_bootstrap_object();
00364 
00365     /**
00366      * \brief A utility function to set the connector credentials
00367      * in storage. This includes endpoint, domain, connector URI
00368      *  and certificates.
00369      * \param security, The Connector certificates.
00370      */
00371     ccs_status_e set_connector_credentials(M2MSecurity *security);
00372 
00373     /**
00374      * \brief A utility function to set the bootstrap credentials
00375      * in storage. This includes Bootstrap URI and certificates.
00376      * \param security, The Bootstrap certificates.
00377      */
00378     ccs_status_e set_bootstrap_credentials(M2MSecurity *security);
00379 
00380     /**
00381      * \brief A utility function to check whether bootstrap credentials are stored in KCM.
00382      */
00383     bool bootstrap_credentials_stored_in_kcm();
00384 
00385     /**
00386      * \brief A utility function to check whether first to claim feature is configured.
00387      */
00388     bool is_first_to_claim();
00389 
00390     /**
00391      * \brief A utility function to clear the first to claim parameter in storage.
00392      */
00393     ccs_status_e clear_first_to_claim();
00394 
00395     /**
00396     * \brief Returns the binding mode selected by the client
00397     * through the configuration.
00398     * \return Binding mode of the client.
00399     */
00400     static M2MInterface::BindingMode transport_mode();
00401 
00402     /**
00403     * \brief Initializes the security object and callbacks.
00404     *
00405     */
00406     void init_security_object();
00407 
00408 private:
00409     // A callback to be called after the sequence is complete.
00410     ConnectorClientCallback*            _callback;
00411     StartupSubStateRegistration         _current_state;
00412     bool                                _event_generated;
00413     bool                                _state_engine_running;
00414     bool                                _setup_complete;
00415     M2MInterface                        *_interface;
00416     M2MSecurity                         *_security;
00417     ConnectorClientEndpointInfo         _endpoint_info;
00418     M2MBaseList                         *_client_objs;
00419     M2MTimer                            _rebootstrap_timer;
00420     uint16_t                            _bootstrap_security_instance;
00421     uint16_t                            _lwm2m_security_instance;
00422     uint16_t                            _rebootstrap_time;
00423     void                                *_certificate_chain_handle;
00424 #ifndef MBED_CLIENT_DISABLE_EST_FEATURE
00425     EstClient                           _est_client;
00426 #endif // !MBED_CLIENT_DISABLE_EST_FEATURE
00427 };
00428 
00429 /**
00430  * \brief ConnectorClientCallback
00431  * A callback class for passing the client progress and error condition to the
00432  * ServiceClient class object.
00433  */
00434 class ConnectorClientCallback {
00435 public:
00436 
00437     /**
00438     * \brief Indicates that the registration or unregistration operation is complete
00439     * with success or failure.
00440     * \param status, Indicates success or failure in terms of status code.
00441     */
00442     virtual void registration_process_result(ConnectorClient::StartupSubStateRegistration status) = 0;
00443 
00444     /**
00445     * \brief Indicates the Connector error condition of an underlying M2MInterface client.
00446     * \param error, Indicates an error code translated from M2MInterface::Error.
00447     * \param reason, Indicates human readable text for error description.
00448     */
00449     virtual void connector_error(M2MInterface::Error error, const char *reason) = 0;
00450 
00451     /**
00452     * \brief A callback indicating that the value of the resource object is updated
00453     *  by the LWM2M Cloud server.
00454     * \param base, The object whose value is updated.
00455     * \param type, The type of the object.
00456     */
00457     virtual void value_updated(M2MBase *base, M2MBase::BaseType type) = 0;
00458 };
00459 
00460 #endif // !__CONNECTOR_CLIENT_H__