pal_plat_time.h

00001 /*******************************************************************************
00002  * Copyright 2016-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 _PAL_PLAT_TIME_H
00018 #define _PAL_PLAT_TIME_H
00019 
00020 #include <stdint.h>
00021 
00022 
00023 #ifdef __cplusplus
00024 extern "C" {
00025 #endif
00026 
00027 /*! \file pal_plat_time.h
00028  *  \brief PAL time - platform.
00029  *   This file contains the real-time OS APIs that need to be implemented in the platform layer.
00030  *
00031  *   This file contains the secure time APIs and is a part of the PAL service API.
00032  *   Unlike the usual timer and tick query APIs, which are found in RTOS, this
00033  *   optional module provides access to the clock, which is used mostly by
00034  *   PAL's own Crypto module.
00035  */
00036 
00037 
00038 /*! \brief  Initialize the time module
00039  *   After boot, the time in RAM will be initialized with the higher value of RTC and SOTP `SAVED_TIME`. If no RTC is present, RTC time is zero.
00040  *   After initialization, the time module will start counting ticks.
00041  *
00042  * \return PAL_SUCCESS when initialization succeed.
00043  */
00044 palStatus_t pal_plat_initTime(void);
00045 
00046 /*! \brief Get the system time.
00047  *
00048  *   The time is calculated by the sum of the initial value + the number of ticks passed, converted into seconds.
00049  *
00050  * \return A 64-bit counter indicating the current system time in seconds on success.
00051  * \return Zero value when the time is not set in the system.
00052  * \note If the delta between the secure time value previously set in the system and the current system time is greater than `PAL_LAST_SAVED_TIME_LATENCY_SEC`,
00053  *       then the secure time value will be overwritten with the current system time.
00054  */
00055 uint64_t pal_plat_osGetTime(void);
00056 
00057 /*! \brief Set the current system time by accepting seconds since January 1st 1970 UTC+0.
00058 *
00059 * @param[in] seconds Seconds from January 1st 1970 UTC+0.
00060 *
00061 * \return PAL_SUCCESS when the time is set successfully.
00062 * \return PAL_ERR_INVALID_TIME when there is a failure in setting the system time.
00063 */
00064 palStatus_t pal_plat_osSetTime(uint64_t seconds);
00065 
00066 /*! \brief Set the weak time.
00067  *
00068  *   Time Forward (a) \n
00069  *   set the time (in RAM) unconditionally. Save the new time in SOTP if the change (between new time and current time in RAM) is greater than 24 hours.
00070  *   Set the time to RTC if the change is greater than 100 seconds. This limitation is to avoid multiple writes to the SOTP and RTC and not related to security.
00071  *
00072  *   Time Forward (b) \n
00073  *   If (a) did not happen, save the time into SOTP if new time is greater from SAVED_TIME by a week (604800 seconds).
00074  *
00075  *   Time Backwards \n
00076  *   set the device time on the device (RAM) and save the time in SOTP only if the change
00077  *   (between new time and current time in RAM) is smaller than 3 minutes for each day lapsed from the last change
00078  *   done via `pal_osSetWeakTime`. RTC is never set backwards by `pal_osSetWeakTime`.
00079  *
00080  * @param[in] setTimeInSeconds  Seconds from January 1st 1970 UTC+0.
00081  *
00082  * \return PAL_SUCCESS when set weak time is successful.
00083  *
00084  * \note To implement this, when the new time is saved in SOTP by `pal_osSetWeakTime` two different records must be saved in SOTP:
00085  * \note 1. The new time (the same record as in factory setup)
00086  * \note 2. The time this action was performed, in order to enforce the 24 hours limitation. Record `LAST_TIME_BACK`.
00087  */
00088 palStatus_t pal_plat_osSetWeakTime(uint64_t setTimeInSeconds);
00089 
00090 /*! \brief Set the strong time. This function will be called when receiving time from a server that is completely trusted.
00091  *
00092  *   Set the time in RAM unconditionally. Save the new time in SOTP or RTC under the following conditions:
00093  *
00094  *   Time forward – if time difference between current time in SOTP (not device time) and new time is greater than a day.
00095  *
00096  *   Time backward – if time difference between current time and new time is greater than one minute.
00097  *   If the time is saved in SOTP (forward or backwards), the record `LAST_TIME_BACK` must be saved.
00098  *
00099  * @param[in] setTimeInSeconds Seconds from January 1st 1970 UTC+0.
00100  *
00101  * \return PAL_SUCCESS when set strong succeed.
00102  *
00103  * \note The limitations are aimed to reduce the number of write operations to the SOTP and not related to security.
00104  */
00105 palStatus_t pal_plat_osSetStrongTime(uint64_t setTimeInSeconds);
00106 
00107 
00108 #ifdef __cplusplus
00109 }
00110 #endif
00111 #endif //_PAL_PLAT_TIME_H