CertificateEnrollmentClient.h

00001 // ----------------------------------------------------------------------------
00002 // Copyright 2018 ARM Ltd.
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 // You may obtain a copy of the License at
00007 //  
00008 //     http://www.apache.org/licenses/LICENSE-2.0
00009 //  
00010 // Unless required by applicable law or agreed to in writing, software
00011 // distributed under the License is distributed on an "AS IS" BASIS,
00012 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013 // See the License for the specific language governing permissions and
00014 // limitations under the License.
00015 // ----------------------------------------------------------------------------
00016 
00017 #ifndef __CERTIFICATE_ENROLLMENT_CLIENT_H__
00018 #define __CERTIFICATE_ENROLLMENT_CLIENT_H__
00019 
00020 #include "mbed-client/m2minterface.h"
00021 #include "ce_defs.h"
00022 
00023 class EstClient;
00024 
00025 namespace CertificateEnrollmentClient {
00026     
00027     /**
00028     * \brief Create the Certificate renewal LWM2M object, instance and resource and push the object to the list
00029     * Also save the pointers to the object and resource, register the event handler, and create the renewal_mutex
00030     * Should be called by ServiceClient::initialize_and_register()
00031     * \param list MbedCloudClient object list
00032     */
00033     ce_status_e  init(M2MBaseList& list, const EstClient *est_client);
00034 
00035     /**
00036     * \brief Release all the resources owned by the CertificateEnrollmentClient
00037     * Should be called by the ServiceClient destructor.
00038     * Does not free the LWM2M resources as the pointers are owned by the ServiceClient. They are freed by the ServiceClient object when device unregisters.
00039     */
00040     void finalize();
00041 
00042     /**
00043     * \brief Initiate a renewal for a specific certificate.
00044     * The process will generate new keys in order to create a CSR. The CSR is then sent to the EST service to retrieve the renewed certificate.
00045     * The new certificate is then atomically stored in the device, along with its corresponding private key.
00046     * Note: The certificate to be removed *must* already exist in the device.
00047     * \param cert_name A null terminated C string indicating the name of the certificate to be renewed.
00048     * \return CE_STATUS_SUCCESS if asynchronous operations has started successfully - In this case, user callback will be executed at the end of the operation, indicating completion status.
00049     *         If any other ce_status_e:: status is returned - operation encountered some error prior to start of the asynchronous stage and user callback will NOT be executed.
00050     */
00051     ce_status_e  certificate_renew(const char *cert_name);
00052 
00053     /**
00054     * \brief Sets the callback function that is called when a certificate renewal process finishes.
00055     * Should be called prior to any certificate renewal operation.
00056     * If a certificate renewal is initiated (either by the certificate_renew() API or by the server) - operation will run normal but the device application will not be notified when done.
00057     * \param user_cb A function pointer to the user callback. If user_cb is NULL - no callback will be called when process finishes.
00058     */
00059     void on_certificate_renewal(cert_renewal_cb_f user_cb);
00060 
00061 }
00062 
00063 
00064 #endif //__CERTIFICATE_ENROLLMENT_CLIENT_H__