shalib.h

00001 /*
00002  * Copyright (c) 2014-2017, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 /**
00018  * \file shalib.h
00019  * \brief SHA256 Library API.
00020  *
00021  *  \section hmac256-inctuction HMAC256 process sequence:
00022  *  1. SHALIB_init_HMAC(), Init HMAC IN process by given security signature material
00023  *  2. SHALIB_push_data_HMAC(), Give data sectors(s) one by one
00024  *  3. SHALIB_finish_HMAC(), Finish HMAC and save SHA256 hash to given buffer
00025  *
00026  *  \section prf256-inctuction PRF256 process sequence:
00027  *  1. shalib_prf_param_get(), Init PRF and get configure structure
00028  *  2. Set the following parameters to configure structure:
00029  *      - HMAC security signature pointer and length
00030  *      - Label text
00031  *      - Seed data and length
00032  *  3. shalib_prf_calc(), Calc PRF256 HASH
00033  *
00034  */
00035 
00036 #ifndef SHALIB_H_
00037 #define SHALIB_H_
00038 
00039 #include "ns_types.h"
00040 
00041 
00042 #ifdef __cplusplus
00043 extern "C" {
00044 #endif
00045 
00046 /*!
00047  * \struct prf_sec_param_t
00048  * \brief PRF 256 stucture
00049  * This structure is used to configure PRF calc operation: secret, label, seed and buffer before call shalib_prf_calc().
00050  */
00051 typedef struct {
00052     const uint8_t *secret;  /**< HMAC security signature pointer. */
00053     uint8_t sec_len;        /**< HMAC security signature length. */
00054     const char *label;      /**< PRF label text. */
00055     const uint8_t *seed;    /**< PRF Seed data. */
00056     uint8_t seedlen;        /**< PRF Seed data length. */
00057 } prf_sec_param_t;
00058 
00059 
00060 // Use these for cumulative HMAC
00061 /**
00062  * \brief Init HMAC256 operation by given security material.
00063  *
00064  * \param secret A pointer to security material.
00065  * \param sec_len Length of security material.
00066  */
00067 void SHALIB_init_HMAC(const uint8_t *secret, uint8_t sec_len);        // Call this first...
00068 /**
00069  * \brief Push data for HMAC
00070  *
00071  * \param data A pointer to data.
00072  * \param len Length of data.
00073  */
00074 void SHALIB_push_data_HMAC(const void *data, uint16_t len);           // ... add data ...
00075 /**
00076  * \brief Finish HMAC256 operation and save result in given buffer.
00077  *
00078  * \param buffer A pointer to result buffer.
00079  * \param nwords Length of 32-bit register to save to buffer (8= 256 bit and 4= 128-bit).
00080  */
00081 void SHALIB_finish_HMAC(void *buffer, uint8_t nwords);                // ... get the HMAC digest.
00082 
00083 
00084 /** PRF API */
00085 /**
00086  * \brief Init PRF library and SHA registers.
00087  * This function returns configure structure where the user needs to set the following items:
00088  *  -Security material and length
00089  *  -Label text and length
00090  *  -Seed data and length
00091  *
00092  * \return A pointer to PRF configure structure.
00093 
00094  */
00095 prf_sec_param_t *shalib_prf_param_get(void);  // GET PRF structure
00096 /* SET secret, label, seed & buffer to 256 PRF  */
00097 /**
00098  * \brief Finish PRF256 operation and save result in given buffer.
00099  */
00100 void shalib_prf_calc(void *output, uint_fast16_t nwords);// GET 256 PRF
00101 #ifdef __cplusplus
00102 }
00103 #endif
00104 #endif /* SHALIB_H_ */