rtems/score/hash.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @ingroup RTEMSScoreHash
0007  *
0008  * @brief This header file provides the interfaces of the
0009  *   @ref RTEMSScoreHash.
0010  */
0011
0012 /*
0013  * Copyright (C) 2021 embedded brains GmbH & Co. KG
0014  *
0015  * Redistribution and use in source and binary forms, with or without
0016  * modification, are permitted provided that the following conditions
0017  * are met:
0018  * 1. Redistributions of source code must retain the above copyright
0019  *    notice, this list of conditions and the following disclaimer.
0020  * 2. Redistributions in binary form must reproduce the above copyright
0021  *    notice, this list of conditions and the following disclaimer in the
0022  *    documentation and/or other materials provided with the distribution.
0023  *
0024  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0025  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0026  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0027  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0028  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0029  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0030  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0031  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0032  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0033  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0034  * POSSIBILITY OF SUCH DAMAGE.
0035  */
0036
0037 #ifndef _RTEMS_SCORE_HASH_H
0038 #define _RTEMS_SCORE_HASH_H
0039
0040 #include <rtems/score/basedefs.h>
0041
0042 #include <sha256.h>
0043 #include <string.h>
0044
0045 #ifdef __cplusplus
0046 extern "C" {
0047 #endif
0048
0049 /**
0050  * @defgroup RTEMSScoreHash Hash Handler
0051  *
0052  * @ingroup RTEMSScore
0053  *
0054  * @brief This group contains the Hash Handler implementation.
0055  *
0056  * @{
0057  */
0058
0059 /**
0060  * @brief This constant represents the size of a hash string.
0061  *
0062  * Accounts for a NUL termination of the hash string.
0063  */
0064 #define HASH_CONTROL_STRING_SIZE 45
0065
0066 /**
0067  * @brief This type represents a hash value.
0068  *
0069  * The hash value is produced by _Hash_Finalize().
0070  */
0071 typedef struct {
0072   /**
0073    * @brief This member contains the hash value encoded as a base64url string.
0074    *
0075    * The string is NUL-terminated.
0076    */
0077   char chars[ HASH_CONTROL_STRING_SIZE ];
0078 } Hash_Control;
0079
0080 /**
0081  * @brief Gets the hash value as a NUL-terminated string.
0082  *
0083  * @param hash is the hash value.
0084  *
0085  * @return Returns the hash value as a NUL-terminated string.
0086  */
0087 static inline const char *_Hash_Get_string( const Hash_Control *hash )
0088 {
0089   return &hash->chars[ 0 ];
0090 }
0091
0092 /**
0093  * @brief This type represents the context to compute a hash value.
0094  */
0095 typedef struct {
0096   /**
0097    * @brief This member contains the hash algorithm context.
0098    */
0099   SHA256_CTX Context;
0100
0101   /**
0102    * @brief This member references a hash value if needed.
0103    */
0104   Hash_Control *hash;
0105
0106   /**
0107    * @brief This member contains an index into the hash value bytes if needed.
0108    */
0109   size_t index;
0110 } Hash_Context;
0111
0112 /**
0113  * @brief Initializes the hash context.
0114  *
0115  * @param[out] context is the hash context to initialize.
0116  */
0117 static inline void _Hash_Initialize( Hash_Context *context )
0118 {
0119   SHA256_Init( &context->Context );
0120 }
0121
0122 /**
0123  * @brief Adds the data to the hash value.
0124  *
0125  * @param[in, out] context is the hash context.
0126  *
0127  * @param begin is the begin address of the data to add.
0128  *
0129  * @param size is the size of the data in bytes.
0130  */
0131 static inline void _Hash_Add_data(
0132   Hash_Context *context,
0133   const void   *begin,
0134   size_t        size
0135 )
0136 {
0137   SHA256_Update( &context->Context, begin, size );
0138 }
0139
0140 /**
0141  * @brief Adds the string to the hash value.
0142  *
0143  * @param[in, out] context is the hash context.
0144  *
0145  * @param str is the string to add.
0146  */
0147 static inline void _Hash_Add_string(
0148   Hash_Context *context,
0149   const char   *str
0150 )
0151 {
0152   SHA256_Update( &context->Context, str, strlen( str ) );
0153 }
0154
0155 /**
0156  * @brief Finalizes the hash value computation and produces the hash value.
0157  *
0158  * @param[in, out] context is the hash context.
0159  *
0160  * @param[out] hash is the hash control to store the produced hash value.
0161  */
0162 void _Hash_Finalize( Hash_Context *context, Hash_Control *hash );
0163
0164 /** @} */
0165
0166 #ifdef __cplusplus
0167 }
0168 #endif
0169
0170 #endif /* _RTEMS_SCORE_HASH_H */