shalib.h

00001 /*
00002  * Copyright (c) 2014-2015 ARM Limited. All rights reserved.
00003  *
00004  * SPDX-License-Identifier: LicenseRef-PBL
00005  *
00006  * Licensed under the Permissive Binary License, Version 1.0 (the "License"); you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  * https://www.mbed.com/licenses/PBL-1.0
00010  *
00011  * See the License for the specific language governing permissions and limitations under the License.
00012  *
00013  */
00014 /**
00015  * \file shalib.h
00016  * \brief SHA256 Library API.
00017  *
00018  *  \section sha256-api SHA256 Library API:
00019  *   There are two ways to calculate SHA256:
00020  *   1. Calc by given 1 data and length pointer
00021  *      - SHALIB_SHA256_HASH(), A function to calculate SHA256 for given data.
00022  *   2. Calc by different data pointer sequence given separately
00023  *      - SHALIB_init_sha256(), Init SHA registers
00024  *      - SHALIB_push_data_sha256(), Give data sectors(s) one by one
00025  *      - **** Give data
00026  *      - SHALIB_push_data_sha256(), Give last data sequence
00027  *      - SHALIB_finish_sha256(), Finish SHA256 by given data to given buffer
00028  *
00029  *   \section sha256res-api SHA256 register resume and save library API:
00030  *   SHA256 Operation dataflow can come in many different timeslots or packets and between them, the application needs
00031  *   to calculated more SHA256 then SAVE and Resume operation SHA registers is usefully.
00032  *   -sha_resume_regs(), Load SHA registers from old HASH sessions
00033  *   -sha_save_regs(), Save SHA registers from current HASH sessions
00034  *
00035  *  \section hmac256-inctuction HMAC256 process sequence:
00036  *  1. SHALIB_init_HMAC(), Init HMAC IN process by given security signature material
00037  *  2. SHALIB_push_data_sha256(), Give data sectors(s) one by one
00038  *  3. SHALIB_finish_HMAC(), Finish HMAC and save SHA256 hash to given buffer
00039  *
00040  *  \section prf256-inctuction PRF256 process sequence:
00041  *  1. shalib_prf_param_get(), Init PRF and get configure structure
00042  *  2. Set the following parameters to configure structure:
00043  *      - HMAC security signature pointer and length
00044  *      - Label text and length
00045  *      - Seed data and length
00046  *      - PRF result pointer
00047  *  3. shalib_prf_calc(), Calc PRF256 HASH
00048  *
00049  */
00050 
00051 #ifndef SHALIB_H_
00052 #define SHALIB_H_
00053 
00054 #include "ns_types.h"
00055 
00056 
00057 #ifdef __cplusplus
00058 extern "C" {
00059 #endif
00060 
00061 /** Do Not change. */
00062 #define SHALIB_RING_BUFFER_SIZE 64
00063 
00064 /*!
00065  * \struct prf_sec_param_t
00066  * \brief PRF 256 stucture
00067  * This structure is used to configure PRF calc operation: secret, label, seed and buffer before call shalib_prf_calc().
00068  */
00069 typedef struct {
00070     const uint8_t *secret;  /**< HMAC security signature pointer. */
00071     uint8_t sec_len;        /**< HMAC security signature length. */
00072     uint8_t label[25];      /**< Label text. */
00073     uint8_t lablen;         /**< Label text length. */
00074     const uint8_t *seed;    /**< Seed data. */
00075     uint8_t seedlen;        /**< Seed data length. */
00076     uint8_t *buffer;        /**< Buffer for saving 256-BIT hash. */
00077 } prf_sec_param_t;
00078 
00079 /*!
00080  * \struct sha256_temp_t
00081  * \brief SHA temporary buffer database for saving current hash operation or resume saved.
00082  */
00083 typedef struct {
00084     uint8_t  m_Data[SHALIB_RING_BUFFER_SIZE];   /**< 64-bytes ring buffer for SHA256 operation. */
00085     uint8_t  m_Read;                            /**< Read pointer to ring buffer. */
00086     uint8_t  m_Write;                           /**< Write pointer to ring buffer. */
00087     uint32_t SHALIB_pushed_bytes;           /**< Hash total byte coun. t*/
00088     uint8_t SHALIB_buffered_bytes;          /**< Ring buffer data in. */
00089     uint32_t areg_temps[8];                 /**< Shalib operation 8 HREG. */
00090 } sha256_temp_t;
00091 
00092 // Cumulative static version using a static ring buffer object
00093 //=============================================================================
00094 /**
00095  * \brief Init SHA registers.
00096  */
00097 void SHALIB_init_sha256(void);                                  // Call this first...
00098 /**
00099  * \brief Push data SHALIB.
00100  *
00101  * \param data A pointer to data.
00102  * \param len Length of data.
00103  */
00104 void SHALIB_push_data_sha256(const uint8_t *data, uint16_t len);      // ... add data ...
00105 /**
00106  * \brief Finish SHA-256 operation and get result to given buffer by given length.
00107  *
00108  * The first `len` words of the SHA-256 are output to buffer.
00109  *
00110  * \param buffer A pointer to result buffer.
00111  * \param len Length of 32-bit register to save to buffer (8= 256 bit and 4= 128-bit).
00112  */
00113 void SHALIB_finish_sha256(uint8_t *buffer, uint8_t len);        // ... get the sha256 digest.
00114 /**
00115  * \brief Calc SHA-256 by 1 function call.
00116  *
00117  * \param data_ptr A pointer to data.
00118  * \param data_len Length of data.
00119  * \param buffer A pointer to 256-bit buffer!!
00120  */
00121 void SHALIB_SHA256_HASH(const uint8_t *data_ptr, uint16_t data_len, uint8_t *buffer); // ... get the sha256 digest.
00122 
00123 /* Shalib registers resume and save API */
00124 /**
00125  * \brief Resume old SHA-256 registers.
00126  *
00127  * \param ptr A pointer to saved session.
00128  */
00129 void sha_resume_regs(const sha256_temp_t *ptr);
00130 /**
00131  * \brief Save SHA-256 registers.
00132  *
00133  * \param ptr A pointer to buffer.
00134  */
00135 void sha_save_regs(sha256_temp_t *ptr);
00136 
00137 // Use these for cumulativec HMAC
00138 /**
00139  * \brief Init HMAC256 operation by given security material.
00140  *
00141  * \param secret A pointer to security material.
00142  * \param sec_len Length of security material.
00143  */
00144 void SHALIB_init_HMAC(const uint8_t *secret, uint8_t sec_len);        // Call this first...
00145 // ... add data ... by SHALIB_push_data_sha256()
00146 /**
00147  * \brief Finish HMAC256 operation and save result in given buffer.
00148  *
00149  * \param buffer A pointer to result buffer.
00150  * \param len Length of 32-bit register to save to buffer (8= 256 bit and 4= 128-bit).
00151  */
00152 void SHALIB_finish_HMAC(uint8_t *buffer, uint8_t len); // ... get the HMAC digest.
00153 
00154 
00155 /** PRF API */
00156 /**
00157  * \brief Init PRF library and SHA registers.
00158  * This function returns configure structure where the user needs to set the following items:
00159  *  -Security material and length
00160  *  -Label text and length
00161  *  -Seed data and length
00162  *  -Buffer for 256 Result
00163  *
00164  * \return A pointer to PRF configure structure.
00165 
00166  */
00167 prf_sec_param_t *shalib_prf_param_get(void);  // GET PRF structure
00168 /* SET secret, label, seed & buffer to 256 PRF  */
00169 /**
00170  * \brief Finish PRF256 operation and save result in given buffer.
00171  *
00172  */
00173 void shalib_prf_calc(void);// GET 256 PRF
00174 #ifdef __cplusplus
00175 }
00176 #endif
00177 #endif /* SHALIB_H_ */