CertificateRenewalData.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_RENEWAL_DATA_H__
00018 #define __CERTIFICATE_RENEWAL_DATA_H__
00019 
00020 #include "certificate_enrollment.h"
00021 #include "est_defs.h"
00022 
00023 /*
00024  * This file declares the CertificateRenewalDataBase base class and its derived class.
00025  * An instantiated object holds all the data necessary for a certificate renewal process.
00026  * The derived classes implement different virtual methods of the base class.
00027  */
00028 
00029 namespace CertificateEnrollmentClient {
00030 
00031     // Abstract base class for data for the renewal process of a single certificate
00032     /*
00033      * Abstract base class for data for the renewal process of a single certificate
00034      * Keeps data required for the process.
00035      * Derived class must implement the pure virtual functions of this class.
00036      */
00037     class CertificateRenewalDataBase {
00038 
00039     public:
00040         CertificateRenewalDataBase(const uint8_t *raw_data, size_t raw_data_size);
00041         virtual ~CertificateRenewalDataBase();
00042         
00043         /*
00044          * Gets a TLV (Type-Length-Value) buffer to parse, each element in the TLV buffer is being treated and executed
00045          * according to the given ce_tlv_type_e that is defined in ce_tlv.h file.
00046          * Each element Type defined as uint16_t primitive and signifies two things:
00047          * (1) the type of operation
00048          * (2) is element 'required' or 'optional'.
00049          *
00050          * We distinguish if an element is required or optional by toggling the type's field MSB (Most Significant Bit).
00051          * If the type's field MSB is set to '0' - this element marked as 'required'
00052          * If the type's field MSB is set to '1' - this element marked as 'optional'
00053          * 
00054          * The function iterates through the TLV buffer and enforces the following rules for each element:
00055          * (1) if element's type is unsupported and the type is marked as 'optional' - element is being skipped
00056          * (2) if element's type is unsupported and the type is marked as 'required' - CE_STATUS_BAD_INPUT_FROM_SERVER error will be returned
00057          * (3) if element's type is supported and the type is marked as 'optional' / 'required' - element is parsed and executed
00058          *
00059          * Currently the only supported type is CE_TLV_TYPE_CERT_NAME as presents in ce_tlv.h, it means that the certificate name
00060          * will be pointed by 'cert_name' which must be persist until this object is destroyed.
00061          *
00062          * The TLV buffer MUST be coherent in memory.
00063          * The TLV buffer is not forced to be word aligned.
00064          * 
00065          * @return CE_STATUS_SUCCESS if parsing succeeded or one of the faulty errors in ce_status.h
00066          */
00067         virtual ce_status_e  parse() = 0;
00068 
00069         /*
00070         * This function is called after the certificate renewal operation has completed (success or error).
00071         * Important: When this function is called, the application assumes that the operation had already finished and new connections are allowed to be made.
00072         *
00073         * \param status The end status of the certificate renewal.
00074         */
00075         virtual void finish(ce_status_e  status) = 0;
00076 
00077         // Certificate name - NULL terminated. Should not be freed, should point to the name inside _raw_data 
00078         const char *cert_name;
00079 
00080         // The certificate chain received from the EST service. Released in the destructor.
00081         cert_chain_context_s *est_data;
00082 
00083         // Key handle that should be initialized and then used when generating a CSR and later when storing the certificate. Released in destructor.
00084         cs_key_handle_t key_handle;
00085 
00086         // Pointer to the generated CSR. Freed in destructor.
00087         uint8_t *csr;
00088 
00089         // Size of the CSR
00090         size_t csr_size;
00091 
00092     protected:
00093         // Pointer to raw data containing the certificate name. Free in destructor
00094         uint8_t *_raw_data;
00095 
00096         // Size of _raw_data
00097         size_t _raw_data_size;
00098 
00099     };
00100 
00101     // From device API data is not a TLV but a string
00102     class CertificateRenewalDataFromDevice : public CertificateRenewalDataBase {
00103     public:
00104         CertificateRenewalDataFromDevice(const char *raw_data);
00105         virtual ~CertificateRenewalDataFromDevice();
00106 
00107         /*
00108          * Set cert_name to point to the raw_data from the user which is null terminated.
00109          * Note that the constructor already allocated and copied the string provided by the user so cert_name will just point to that.
00110          */
00111         virtual ce_status_e  parse();
00112 
00113         /*
00114          * Call the user callback with status. The initiator is CE_INITIATOR_DEVICE.
00115          *
00116          * \param status The status that will be specified when the user callback is called.
00117          */
00118         virtual void finish(ce_status_e  status);
00119     };
00120 
00121     // Class used when the request was initiated by the server. raw_data is TLV
00122     class CertificateRenewalDataFromServer : public CertificateRenewalDataBase {
00123     public:
00124         CertificateRenewalDataFromServer(const uint8_t *raw_data, size_t raw_data_size);
00125         virtual ~CertificateRenewalDataFromServer();
00126 
00127         /*
00128          *  Parse the certificate name from _raw_data which contains the TLV received from the server.
00129          */
00130         virtual ce_status_e  parse();
00131 
00132         /*
00133         * Call the user callback with status. The initiator is CE_INITIATOR_DEVICE.
00134         * Then set the resource to the status value and set a delayed response to the server. 
00135         *
00136         * \param status The status that will be specified when the user callback is called, and sent to the server.
00137         */
00138         virtual void finish(ce_status_e  status);
00139     };
00140 
00141     
00142 }
00143 
00144 #endif // __CERTIFICATE_RENEWAL_DATA_H__
00145