hzl.h

Go to the documentation of this file.

/*
 * Copyright © 2020-2022, Matjaž Guštin <dev@matjaz.it>
 * <https://matjaz.it>. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 * 3. Neither the name of nor the names of its contributors may be used to
 *    endorse or promote products derived from this software without specific
 *    prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS “AS IS”
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
#ifndef HZL_H_
#define HZL_H_
 
#ifdef __cplusplus
extern "C"
{
#endif
 
#define HZL_VERSION "v3.0.0"
 
#define HZL_CBS_PROTOCOL_VERSION_SUPPORTED "v1.3"
 
// Dependencies (partial list: more includes in the if-elif-endif checking the OS below)
#include <stdint.h>  /* For uint8_t, uint16_t etc. */
#include <stdbool.h> /* For bool, true, false */
#include <stddef.h>  /* For NULL, size_t */
#include <string.h>  /* For memcpy(), if available also memset_s() */
 
#if defined(WIN32) || defined(_WIN32) || defined(__WIN32__) \
 || defined(_WIN64) || defined(__NT__)
 
#define HZL_OS_AVAILABLE 1
#define HZL_OS_AVAILABLE_WIN 1
#define HZL_OS_AVAILABLE_NIX 0
 
#include <Windows.h> /* To avoid compilation errors for other Windows headers. */
#include <sysinfoapi.h> /* For GetSystemTimeAsFileTime(), FILETIME, ULARGE_INTEGER */
#include <bcrypt.h>  /* For BCryptGenRandom() - requires explicit linking to `bcrypt` lib. */
#include <stdio.h>   /* For config file IO */
#include <stdlib.h>  /* For calloc(), free() */
 
#if defined(_MSC_VER) && _MSC_VER <= 1916
// Fix for compilation with Visual Studio 2017 not supporting C11 yet.
#define _Static_assert static_assert
#endif
 
#elif defined(__linux__) \
 || defined(__APPLE__) || defined(__MACH__) \
 || defined(__unix__) || defined(__unix) || defined(unix)
 
#define HZL_OS_AVAILABLE 1
#define HZL_OS_AVAILABLE_WIN 0
#define HZL_OS_AVAILABLE_NIX 1
 
#include <sys/time.h> /* For gettimeofday() */
#include <stdio.h>    /* For config file IO and TRNG with /dev/urandom */
#include <stdlib.h>   /* For calloc(), free() */
 
#else
 
#define HZL_OS_AVAILABLE 0
#define HZL_OS_AVAILABLE_WIN 0
#define HZL_OS_AVAILABLE_NIX 0
 
#endif
 
#if HZL_OS_AVAILABLE_WIN
#define HZL_API __declspec(dllexport)
#else
#define HZL_API
#endif
 
#define HZL_SET_BY_USER
 
#define HZL_SERVER_SID 0U
 
#define HZL_BROADCAST_GID 0U
 
#define HZL_LTK_LEN 16U
 
#define HZL_STK_LEN 16U
 
#define HZL_IS_SECURITY_WARNING(err) ((err) >= 1 && (err) <= 15)
 
#define HZL_MAX_CAN_FD_DATA_LEN 64U
 
#define HZL_MAX_TRNG_TRIES_FOR_NONZERO_VALUE 20U
 
#define HZL_LARGEST_MAX_COUNTER_NONCE_DELAY (1U << 22U)
 
typedef enum hzl_Err
{
    // Success
    HZL_OK = 0U,  
 
    // CBS standard security warnings
    HZL_ERR_SECWARN_INVALID_TAG = 1U,
    HZL_ERR_SECWARN_MESSAGE_FROM_MYSELF = 2U,
    HZL_ERR_SECWARN_NOT_EXPECTING_A_RESPONSE = 3U,
    HZL_ERR_SECWARN_SERVER_ONLY_MESSAGE = 4U,
    HZL_ERR_SECWARN_RESPONSE_TIMEOUT = 5U,
    HZL_ERR_SECWARN_OLD_MESSAGE = 6U,
    HZL_ERR_SECWARN_DENIAL_OF_SERVICE = 7U,
    HZL_ERR_SECWARN_NOT_IN_GROUP = 8U,
    HZL_ERR_SECWARN_RECEIVED_OVERFLOWN_NONCE = 9U,
    HZL_ERR_SECWARN_RECEIVED_ZERO_KEY = 10U,
    HZL_ERR_SECWARN_RFU_1 = 11U,  
    HZL_ERR_SECWARN_RFU_2 = 12U,  
    HZL_ERR_SECWARN_RFU_3 = 13U,  
    HZL_ERR_SECWARN_RFU_4 = 14U,  
    HZL_ERR_SECWARN_RFU_5 = 15U,  
 
    // Generic errors
    HZL_ERR_PROGRAMMING = 16U,
 
    // ClientInit, ServerInit
    HZL_ERR_NULL_CTX = 17U,
    HZL_ERR_NULL_CONFIG_CLIENT = 18U,
    HZL_ERR_NULL_CONFIG_SERVER = 19U,
    HZL_ERR_ZERO_GROUPS = 20U,
    HZL_ERR_LTK_IS_ALL_ZEROS = 21U,
    HZL_ERR_INVALID_HEADER_TYPE = 22U,
    HZL_ERR_SERVER_SID_ASSIGNED_TO_CLIENT = 23U,
    HZL_ERR_SIDS_ARE_NOT_PRESORTED_STRICTLY_ASCENDING = 24U,
    HZL_ERR_GAP_IN_SIDS = 25U,
    HZL_ERR_SID_TOO_LARGE_FOR_CONFIGURED_HEADER_TYPE = 26U,
    HZL_ERR_TOO_MANY_GROUPS_FOR_CONFIGURED_HEADER_TYPE = 27U,
    HZL_ERR_ZERO_CLIENTS = 28U,
    HZL_ERR_TOO_MANY_CLIENTS = 29U,
    HZL_ERR_TOO_MANY_CLIENTS_FOR_CONFIGURED_HEADER_TYPE = 30U,
    HZL_ERR_NULL_CONFIG_CLIENTS = 31U,
    HZL_ERR_NULL_CONFIG_GROUPS = 32U,
    HZL_ERR_GIDS_ARE_NOT_PRESORTED_STRICTLY_ASCENDING = 33U,
    HZL_ERR_GAP_IN_GIDS = 34U,
    HZL_ERR_MISSING_GID_0 = 35U,
    HZL_ERR_INVALID_MAX_CTRNONCE_DELAY = 36U,
    HZL_ERR_GID_TOO_LARGE_FOR_CONFIGURED_HEADER_TYPE = 37U,
    HZL_ERR_TOO_LARGE_CTRNONCE_UPPER_LIMIT = 38U,
    HZL_ERR_INVALID_DELAY_BETWEEN_REN_NOTIFICATIONS = 39U,
    HZL_ERR_CLIENTS_BITMAP_ZERO_CLIENTS = 40U,
    HZL_ERR_CLIENTS_BITMAP_UNKNOWN_SID = 41U,
    HZL_ERR_CLIENTS_BITMAP_INVALID_BROADCAST_GROUP = 42U,
    HZL_ERR_NULL_STATES_GROUPS = 43U,
    HZL_ERR_NULL_CURRENT_TIME_FUNC = 44U,
    HZL_ERR_NULL_TRNG_FUNC = 45U,
 
    // TX and RX function functions
    HZL_ERR_NULL_PDU = 60U,
    HZL_ERR_NULL_SDU = 61U,
    HZL_ERR_UNKNOWN_GROUP = 62U,
    HZL_ERR_UNKNOWN_SOURCE = 63U,
    HZL_ERR_SESSION_NOT_ESTABLISHED = 64U,
 
    // TX functions
    HZL_ERR_TOO_LONG_SDU = 70U,
    HZL_ERR_HANDSHAKE_ONGOING = 71U,
    HZL_ERR_NO_POTENTIAL_RECEIVER = 72U,
    HZL_ERR_RENEWAL_ONGOING = 73U,
 
    // RX functions
    HZL_ERR_INVALID_PAYLOAD_TYPE = 80U,
    HZL_ERR_TOO_SHORT_PDU_TO_CONTAIN_HEADER = 81U,
    HZL_ERR_TOO_SHORT_PDU_TO_CONTAIN_SADFD = 82U,
    HZL_ERR_TOO_SHORT_PDU_TO_CONTAIN_REQ = 83U,
    HZL_ERR_TOO_SHORT_PDU_TO_CONTAIN_RES = 84U,
    HZL_ERR_TOO_SHORT_PDU_TO_CONTAIN_REN = 85U,
    HZL_ERR_TOO_LONG_CIPHERTEXT = 86U,
    HZL_ERR_MSG_IGNORED = 87U,
    HZL_ERR_SECWARN_RECEIVED_ZERO_REQNONCE = 88U,
 
    // Failed IO operation
    HZL_ERR_CANNOT_GET_CURRENT_TIME = 100U,
    HZL_ERR_CANNOT_GENERATE_RANDOM = 101U,
    HZL_ERR_CANNOT_GENERATE_NON_ZERO_RANDOM = 102U,
 
    // OS interaction functions
    HZL_ERR_NULL_FILENAME = 120U,
    HZL_ERR_CANNOT_OPEN_CONFIG_FILE = 121U,
    HZL_ERR_UNEXPECTED_EOF = 122U,
    HZL_ERR_INVALID_FILE_MAGIC_NUMBER = 123U,
    HZL_ERR_MALLOC_FAILED = 124U,
} hzl_Err_t;
 
typedef enum hzl_HeaderType
{
    HZL_HEADER_0 = 0U,
    HZL_HEADER_1 = 1U,
    HZL_HEADER_2 = 2U,
    HZL_HEADER_3 = 3U,
    HZL_HEADER_4 = 4U,
    HZL_HEADER_5 = 5U,
    HZL_HEADER_6 = 6U,
// Values [7, 32] are RFU.
} hzl_HeaderType_t;
 
typedef uint8_t hzl_Gid_t;
 
typedef uint8_t hzl_Sid_t;
 
typedef uint8_t hzl_Pty_t;
 
typedef uint32_t hzl_CanId_t;
 
typedef uint64_t hzl_ReqNonce_t;
 
typedef uint64_t hzl_ResNonce_t;
 
typedef uint32_t hzl_Timestamp_t;
 
typedef uint32_t hzl_CtrNonce_t;
 
typedef struct hzl_Header
{
    hzl_Gid_t gid;  
    hzl_Sid_t sid;  
    hzl_Pty_t pty;  
} hzl_Header_t;
 
// TODO expose CBS header to allow the user to know which CAN ID to assign
// TODO expose configuration/functions for packing the CBS header to allow the user to
// choose where to pack the header (CAN ID, CAN payload or mixed)
typedef struct hzl_CbsPduMsg
{
    size_t dataLen;  
    uint8_t data[HZL_MAX_CAN_FD_DATA_LEN];  
} hzl_CbsPduMsg_t;
 
typedef struct hzl_RxMsg
{
    size_t dataLen;  
    hzl_CanId_t canId;  
    hzl_Gid_t gid;  
    hzl_Sid_t sid;  
    bool wasSecured;  
    bool isForUser;  
    uint8_t data[HZL_MAX_CAN_FD_DATA_LEN];  
} hzl_RxSduMsg_t;
 
typedef hzl_Err_t (* hzl_TrngFunc)(uint8_t* bytes, size_t amount);
 
typedef hzl_Err_t (* hzl_TimestampFunc)(hzl_Timestamp_t* timestamp);
 
typedef struct
{
    HZL_SET_BY_USER hzl_TrngFunc trng;
 
    HZL_SET_BY_USER hzl_TimestampFunc currentTime;
} hzl_Io_t;
 
#ifdef __cplusplus
}
#endif
 
#endif  /* HZL_H_ */