qt6-migration-pipeline/external/rti_connext_dds-7.7.0/include/ndds/osapi/osapi_hash.h

/*
 * (c) Copyright, Real-Time Innovations, 2016-2024.
 * All rights reserved.
 *
 * No duplications, whole or partial, manual or electronic, may be made
 * without express written permission.  Any such copies, or
 * revisions thereof, must display this notice unaltered.
 * This code contains trade secrets of Real-Time Innovations, Inc.
 */

#ifndef osapi_hash_h
#define osapi_hash_h

#include <errno.h>

#include "osapi/osapi_type.h"
#include "osapi/osapi_dll.h"

#include <stdio.h>
#include <stdarg.h>

#ifdef __cplusplus
extern "C" {
#endif

/** @internal
 * \file hash.ifc
 * @brief Hash utility functions
 */
/** @internal \defgroup RTIOsapiHashClass RTIOsapiHash
 * \ingroup RTIOsapiModule
 * \brief Namespace for hashing functions
 */
#define RTI_OSAPI_HASH_MAX_LENGTH (32)
#define RTI_OSAPI_HASH_VALUE_NIL \
    { \
        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, \
                0, 0, 0, 0, 0, 0, 0, 0, 0 \
    }

#define RTI_OSAPI_HASH_FLAG_VALID (0x01 << 0)

typedef struct RTIOsapiHash {
    RTI_UINT8 value[RTI_OSAPI_HASH_MAX_LENGTH];
    RTI_UINT8 length;
    RTI_UINT8 flags;
} RTIOsapiHash;

#define RTI_OSAPI_HASH_NIL \
  { \
    RTI_OSAPI_HASH_VALUE_NIL, 0, 0 \
  }

/** @internal \ingroup RTIOsapiHashClass
 * @brief initialize a RTIOsapiHash
 *
 * @param self \b In. The hash to initialize
 */
extern RTIOsapiDllExport void RTIOsapiHash_initialize(RTIOsapiHash *self);

/** @internal \ingroup RTIOsapiHashClass
 * @brief Checks if two RTIOsapiHash are equal
 *
 * @param a \b In. The first hash to compare
 * @param b \b In. The second hash to compare
 * @return RTI_TRUE if they are equal. RTI_FALSE otherwise
 */
extern RTIOsapiDllExport RTIBool
RTIOsapiHash_equals(const RTIOsapiHash *a, const RTIOsapiHash *b);

/** @internal \ingroup RTIOsapiHashClass
 * @brief Compare two hashes
 *
 * @param a \b In. The first RTIOsapiHash to compare
 * @param a \b In. The first RTIOsapiHash to compare
 * @return Return 0 if they are equal.
 */
extern RTIOsapiDllExport int RTIOsapiHash_compare(
        const RTIOsapiHash *a,
        const RTIOsapiHash *b);

/** @internal \ingroup RTIOsapiHashClass
  @brief Copy a hash

  @param out \b Out. The RTIOsapiHash where to copy
  @param in \b In. The source RTIOsapiHash
*/
extern RTIOsapiDllExport void RTIOsapiHash_copy(
        struct RTIOsapiHash *out,
        const struct RTIOsapiHash *in);

/** @internal \ingroup RTIOsapiHashClass
  @brief Check if a RTIOsapiHash is valid

  @param self \b In. The RTIOsapiHash to check
*/
extern RTIOsapiDllExport RTIBool RTIOsapiHash_isValid(const RTIOsapiHash *self);

/** @internal \ingroup RTIOsapiHashClass
  @brief Returns the length in bytes of the RTIOsapiHash

  @param self \b In. The RTIOsapiHash to get the length
  @return the length in bytes of the hash
*/
extern RTIOsapiDllExport RTI_UINT8
RTIOsapiHash_length(const RTIOsapiHash *self);

/** @internal \ingroup RTIOsapiHashClass
  @brief Returns a array containing the RTIOsapiHash value

  @param self \b In. The RTIOsapiHash to get the length
  @return A pointer to the octet buffer containing the hash
*/
extern RTIOsapiDllExport RTI_UINT8 *RTIOsapiHash_value(
        const RTIOsapiHash *self);

/** @internal \ingroup RTIOsapiHashClass
  @brief Marks a hash as invalid

  @param self \b In. The RTIOsapiHash to reset
*/
extern RTIOsapiDllExport void RTIOsapiHash_reset(struct RTIOsapiHash *self);

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief Converts an RTISampleHash to string.
 *
 * @param self \b In. The RTIOsapiHash to convert to string.
 * @param buffer \b Out. Buffer to store the output string. If NULL, this
 * function returns RTI_TRUE and bufferSize will be updated with the size needed
 * to hold the resulting string.
 * @param bufferSize \b InOut. Size of the buffer available to store the string
 * (this size shall account for the NUL terminator). If passing a NULL buffer
 * or if the passed bufferSize is not big enough to hold the resulting string,
 * bufferSize will be updated with the size needed to hold the resulting string.
 * @param lowerCase \b In. If RTI_TRUE, the output string will be in lower case.
 *
 * @return RTI_TRUE on success (either generating the string or generating
 * the required bufferSize if buffer was NULL), RTI_FALSE on failure.
 */
extern RTIOsapiDllExport RTIBool RTIOsapiHash_toString(
        const struct RTIOsapiHash *self,
        char *buffer,
        size_t *bufferSize,
        RTIBool lowerCase);

/** @internal \ingroup RTIOsapiHashClass
  @brief Print a RTISampleHash

  @param self \b In. The RTIOsapiHash to print
*/
extern RTIOsapiDllExport void RTIOsapiHash_print(
        const struct RTIOsapiHash *self);

/** @internal \ingroup RTIOsapiHashClass
  @brief Computes the MD5 of a buffer

  @param self \b Out. The output RTIOsapiHash
  @param in \b In. The buffer to calculate the hash value
  @param size \b In. The length of the buffer
*/
extern RTIOsapiDllExport void RTIOsapiHash_computeMd5(
        RTIOsapiHash *self,
        const char *in,
        size_t size);

/** @internal \ingroup RTIOsapiHashClass
  @brief Computes the MD5 of a set of buffers and store the result in
  the output RTIOsapiHash

  @param self \b Out. The output RTIOsapiHash
  @param in \b In. Array of buffers that will be used to calculate the hash
  value
  @param size \b In. The number of elements in the array of buffers
  @param elementSize \b In. An array containing the size of the buffers in the
  in parameter
*/
extern RTIOsapiDllExport void RTIOsapiHash_computeScatterMd5(
        RTIOsapiHash *self,
        const char **in,
        size_t size,
        const size_t *elementSize);

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief Computes the SHA1 of a buffer.
 *
 * This function computes the SHA1 hash for a given buffer.
 *
 * @param self \b Out. The output RTIOsapiHash.
 * @param in \b In. The buffer to calculate the hash value.
 * @param size \b In. The length of the buffer in bytes.
 */
extern RTIOsapiDllExport void RTIOsapiHash_computeSHA1(
        RTIOsapiHash *self,
        const char *in,
        size_t size);

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief Computes the SHA256 of a buffer.
 *
 * This function computes the SHA256 hash for a given buffer.
 *
 * @param self \b Out. The output RTIOsapiHash.
 * @param in \b In. The buffer to calculate the hash value.
 * @param size \b In. The length of the buffer in bytes.
 */
extern RTIOsapiDllExport void RTIOsapiHash_computeSHA256(
        RTIOsapiHash *self,
        const char *in,
        size_t size);

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief Computes the HMAC-SHA1 of a given message.
 *
 * This function computes the HMAC (Hash-based Message Authentication Code)
 * using the SHA-1 hash function for a given message and key.
 *
 * @attention This HMAC implementation is not intended for use in any
 * security-related features and MUST NOT BE USED for such purposes.
 *
 * @param self \b Out. The output RTIOsapiHash
 * @param key \b In. The key to use for the HMAC computation.
 * @param keySize \b In. The size of the key in bytes.
 * @param msg \b In. The message to be hashed.
 * @param msgSize \b In. The size of the message in bytes.
 */
extern RTIOsapiDllExport void RTIOsapiHash_computeHmacSha1(
        RTIOsapiHash *self,
        const RTI_UINT8 *key,
        const RTI_UINT32 keySize,
        const RTI_UINT8 *msg,
        const RTI_UINT32 msgSize);

/* The size of the HMAC-SHA1 digest in bytes (20 bytes) */
#define RTI_OSAPI_HASH_HMAC_SHA1_DIGEST_SIZE 20

/* The size of the HMAC-SHA1 block in bytes (64 bytes) */
#define RTI_OSAPI_HASH_HMAC_SHA1_BLOCK_SIZE 64

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief Computes the HMAC-SHA256 of a given message.
 *
 * This function computes the HMAC (Hash-based Message Authentication Code)
 * using the SHA-256 hash function for a given message and key.
 *
 * @attention This HMAC implementation is not intended for use in any
 * security-related features and MUST NOT BE USED for such purposes.
 *
 * @param self \b Out. The output RTIOsapiHash
 * @param key \b In. The key to use for the HMAC computation.
 * @param keySize \b In. The size of the key in bytes.
 * @param msg \b In. The message to be hashed.
 * @param msgSize \b In. The size of the message in bytes.
 */
extern RTIOsapiDllExport void RTIOsapiHash_computeHmacSha256(
        RTIOsapiHash *self,
        const RTI_UINT8 *key,
        const RTI_UINT32 keySize,
        const RTI_UINT8 *msg,
        const RTI_UINT32 msgSize);

/* The size of the HMAC-SHA256 digest in bytes (32 bytes) */
#define RTI_OSAPI_HASH_HMAC_SHA256_DIGEST_SIZE 32

/* The size of the HMAC-SHA256 block in bytes (64 bytes) */
#define RTI_OSAPI_HASH_HMAC_SHA256_BLOCK_SIZE 64

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief Type to store the selected hashing algorithm.
 */
typedef RTI_UINT8 RTIOsapiHashAlgorithmKind;

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief INVALID hashing algorithm RTIOsapiHashAlgorithmKind.
 */
#define RTI_OSAPI_HASH_ALGORITHM_KIND_INVALID ((RTIOsapiHashAlgorithmKind) 0)

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief CRC32C (Castagnoli) hashing algorithm RTIOsapiHashAlgorithmKind.
 */
#define RTI_OSAPI_HASH_ALGORITHM_KIND_CRC32C ((RTIOsapiHashAlgorithmKind) 1)

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief CRC64XZ hashing algorithm RTIOsapiHashAlgorithmKind.
 */
#define RTI_OSAPI_HASH_ALGORITHM_KIND_XZ ((RTIOsapiHashAlgorithmKind) 2)

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief MD5 hashing algorithm RTIOsapiHashAlgorithmKind.
 */
#define RTI_OSAPI_HASH_ALGORITHM_KIND_MD5 ((RTIOsapiHashAlgorithmKind) 3)

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief Type to store the RTIOsapiHashStream state.
 */
typedef RTI_UINT8 RTIOsapiHashStreamState;

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief INVALID RTIOsapiHashStreamState.
 */
#define RTI_OSAPI_HASH_STREAM_STATE_INVALID ((RTIOsapiHashStreamState) 0)

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief INITIALIZED RTIOsapiHashStreamState.
 */
#define RTI_OSAPI_HASH_STREAM_STATE_INITIALIZED ((RTIOsapiHashStreamState) 1)

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief STARTED RTIOsapiHashStreamState.
 */
#define RTI_OSAPI_HASH_STREAM_STATE_STARTED ((RTIOsapiHashStreamState) 2)

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief FINISHED RTIOsapiHashStreamState.
 */
#define RTI_OSAPI_HASH_STREAM_STATE_FINISHED ((RTIOsapiHashStreamState) 3)

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief RTIOsapiHashStream class enables computing hashes in stream mode
 * (bytes to hash can be provided in multiple steps).
 *
 * The way HashStream works is the following:
 * - It must be initialized to a valid algorithm (e.g., MD5).
 * - Then one or multiple consecutive hashing sessions using the same algorithm
 *   can be performed.
 * - Finally, HashStream must be finalized to release any allocated resources.
 *
 * Each hashing session consists of the following steps:
 * - One call to hashStart to setup the session.
 * - One or more calls to hashUpdate to incrementally add the bytes to hash.
 * - One call to hashFinish, which computes the resulting hash.
 */
typedef struct RTIOsapiHashStream {
    void *_internalState;
    RTIOsapiHashAlgorithmKind kind;
    RTIOsapiHashStreamState state;
    RTIOsapiHash hash;
} RTIOsapiHashStream;

#define RTIOsapiHashStream_INITIALIZER \
  { \
    NULL, /* _internalState */ \
    RTI_OSAPI_HASH_ALGORITHM_KIND_INVALID, /* kind */ \
    RTI_OSAPI_HASH_STREAM_STATE_INVALID, /* state */ \
    RTI_OSAPI_HASH_NIL /* hash */ \
  }

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief Initializes a RTIOsapiHashStream object so it is ready to compute
 * hashes in stream mode using a given algorithm.
 *
 * @param self \b Out. The RTIOsapiHashStream object to initialize.
 * @param kind \b In. Algorithm to setup in the RTIOsapiHashStream object.
 *
 * @return RTI_TRUE on success, RTI_FALSE on failure.
 */
extern RTIOsapiDllExport RTIBool RTIOsapiHashStream_initialize(
        RTIOsapiHashStream *self,
        RTIOsapiHashAlgorithmKind kind);

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief Finalizes a RTIOsapiHashStream object.
 *
 * @param self \b Out. The RTIOsapiHashStream object to finalize.
 */
extern RTIOsapiDllExport void RTIOsapiHashStream_finalize(
        RTIOsapiHashStream *self);

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief Starts a stream hashing session.
 *
 * @param self \b Out. The RTIOsapiHashStream object that is doing the hashing.
 *
 * @return RTI_TRUE on success, RTI_FALSE on failure.
 */
extern RTIOsapiDllExport RTIBool
RTIOsapiHashStream_hashStart(RTIOsapiHashStream *self);

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief Adds bytes to hash to an already started stream hashing session.
 *
 * @param self \b Out. The RTIOsapiHashStream object that is doing the hashing.
 *
 * @return RTI_TRUE on success, RTI_FALSE on failure.
 */
extern RTIOsapiDllExport RTIBool RTIOsapiHashStream_hashUpdate(
        RTIOsapiHashStream *self,
        const RTI_UINT8 *data,
        size_t size);

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief Finish a stream hashing session and computes the resulting hash.
 *
 * @param self \b Out. The RTIOsapiHashStream object that is doing the hashing.
 */
extern RTIOsapiDllExport RTIBool
RTIOsapiHashStream_hashFinish(RTIOsapiHashStream *self);

/** @internal
 * \ingroup RTIOsapiHashClass
 * @brief Computes the hash for a file using a HashStream object.
 *
 * @param self \b Out. The RTIOsapiHashStream object that is doing the hashing.
 * @param fileName \b In. The name of the file to hash.
 *
 * @return RTI_TRUE on success, RTI_FALSE on failure.
 */
extern RTIOsapiDllExport RTIBool
RTIOsapiHashStream_hashFile(RTIOsapiHashStream *self, const char *fileName);

#ifdef __cplusplus
} /* extern "C" */
#endif

#include "osapi/osapi_hash_impl.h"

#endif /* osapi_hash_h */