pal_time.h

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