BPSecLib_Private.h

Go to the documentation of this file.

/*
 * Copyright (c) 2025 The Johns Hopkins University Applied Physics
 * Laboratory LLC.
 *
 * This file is part of the Bundle Protocol Security Library (BSL).
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *     http://www.apache.org/licenses/LICENSE-2.0
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * This work was performed for the Jet Propulsion Laboratory, California
 * Institute of Technology, sponsored by the United States Government under
 * the prime contract 80NM0018D0004 between the Caltech and NASA under
 * subcontract 1700763.
 */
#ifndef BSL_BPSECLIB_PRIVATE_H_
#define BSL_BPSECLIB_PRIVATE_H_
 
#include <assert.h>
#include <inttypes.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include <syslog.h>
#include <time.h>
 
#include "BPSecLib_Public.h"
 
typedef enum
{
    BSL_SUCCESS                       = 0,   
    BSL_ERR_FAILURE                   = -1,  
    BSL_ERR_ARG_NULL                  = -2,  
    BSL_ERR_ARG_INVALID               = -3,  
    BSL_ERR_PROPERTY_CHECK_FAILED     = -4,  
    BSL_ERR_INSUFFICIENT_SPACE        = -5,  
    BSL_ERR_NOT_IMPLEMENTED           = -6,  
    BSL_ERR_ENCODING                  = -7,  
    BSL_ERR_DECODING                  = -8,  
    BSL_ERR_NOT_FOUND                 = -9,  
    BSL_ERR_BUNDLE_OPERATION_FAILED   = -10, 
    BSL_ERR_SECURITY_OPERATION_FAILED = -11, 
    BSL_ERR_HOST_CALLBACK_FAILED      = -12, 
 
    BSL_ERR_POLICY_FAILED = -100, 
 
    BSL_ERR_SECURITY_CONTEXT_FAILED       = -200, 
    BSL_ERR_SECURITY_CONTEXT_PARTIAL_FAIL = -201, 
    BSL_ERR_SECURITY_CONTEXT_VALIDATION_FAILED = -202 
} BSL_ErrCodes_e;
 
#if defined(__GNUC__) || defined(__clang__)
#define _U_ __attribute__((unused)) // NOLINT
#elif defined(_MSC_VER)
#define _U_ __pragma(warning(suppress : 4100 4189))
#else
#define _U_
#endif
 
#ifndef UNLIKELY
#if defined(__GNUC__)
#define UNLIKELY(expr) __builtin_expect(!!(expr), 0)
#define LIKELY(expr)   __builtin_expect(!!(expr), 1)
#else
#define UNLIKELY(expr) (expr)
#define LIKELY(expr)   (expr)
#endif
#endif /* UNLIKELY */
 
// Note, the following CHK macros are deprecated.
#define CHKRET(cond, val) \
    if (!LIKELY(cond))    \
    {                     \
        return val;       \
    }
#define CHKVOID(cond) CHKRET(cond, )
#define CHKNULL(cond) CHKRET(cond, NULL)
#define CHKFALSE(cond) CHKRET(cond, false)
#define CHKERR1(cond) CHKRET(cond, 1)
#define CHKERRVAL(value) CHKRET(!(value), (value))
 
typedef enum
{
    BSL_POLICYACTION_UNDEFINED = 0, 
    BSL_POLICYACTION_NOTHING,       
    BSL_POLICYACTION_DROP_BLOCK,    
    BSL_POLICYACTION_DROP_BUNDLE    
} BSL_PolicyAction_e;
 
uint8_t *BSL_Log_DumpAsHexString(uint8_t *dstbuf, size_t dstlen, const uint8_t *srcbuf, size_t srclen);
 
void BSL_openlog(void);
 
void BSL_closelog(void);
 
void BSL_LogEvent(int severity, const char *filename, int lineno, const char *funcname, const char *format, ...);
 
// NOLINTBEGIN(misc-include-cleaner)
#define BSL_LOG_CRIT(...) BSL_LogEvent(LOG_CRIT, __FILE__, __LINE__, __func__, __VA_ARGS__)
#define BSL_LOG_ERR(...) BSL_LogEvent(LOG_ERR, __FILE__, __LINE__, __func__, __VA_ARGS__)
#define BSL_LOG_WARNING(...) BSL_LogEvent(LOG_WARNING, __FILE__, __LINE__, __func__, __VA_ARGS__)
#define BSL_LOG_INFO(...) BSL_LogEvent(LOG_INFO, __FILE__, __LINE__, __func__, __VA_ARGS__)
#define BSL_LOG_DEBUG(...) BSL_LogEvent(LOG_DEBUG, __FILE__, __LINE__, __func__, __VA_ARGS__)
// NOLINTEND(misc-include-cleaner)
 
#define CHK_TEMPL(expr, msg, return_code)                                      \
    do                                                                         \
    {                                                                          \
        if (!(expr))                                                           \
        {                                                                      \
            BSL_LOG_ERR("" msg " (" #expr ") ... [errcode=" #return_code "]"); \
            assert(!(expr));                                                   \
            return return_code;                                                \
        }                                                                      \
    }                                                                          \
    while (0)
 
#define CHK_AS_BOOL(expr) CHK_TEMPL(expr, "Failed Property Check: Failed to satisfy", BSL_ERR_ARG_INVALID)
 
#define CHK_ARG_EXPR(expr) \
    CHK_TEMPL(expr, "Illegal Argument: Argument expression check failed to satisfy", BSL_ERR_ARG_INVALID)
 
#define CHK_ARG_NONNULL(var) \
    CHK_TEMPL((var) != NULL, "Illegal Argument: Argument null check failed to satisfy", BSL_ERR_ARG_NULL)
 
#define CHK_PRECONDITION(expr) CHK_TEMPL(expr, "Precondition Failed: Did not satisfy", BSL_ERR_FAILURE);
 
#define CHK_PROPERTY(expr) CHK_TEMPL(expr, "Property Failed: Did not satisfy", BSL_ERR_FAILURE);
 
#define CHK_POSTCONDITION(expr) CHK_TEMPL(expr, "Postcondition Failed: Did not satisfy", BSL_ERR_FAILURE);
 
#define ASSERT_TEMPL(expr, msg)                 \
    do                                          \
    {                                           \
        if (!(expr))                            \
        {                                       \
            BSL_LOG_ERR("" msg " (" #expr ")"); \
            assert(!(expr));                    \
        }                                       \
    }                                           \
    while (0)
 
#define ASSERT_ARG_EXPR(expr) ASSERT_TEMPL(expr, "Panic: Argument expression check failed to satisfy")
 
#define ASSERT_ARG_NONNULL(var) ASSERT_TEMPL((var) != NULL, "Panic: Null Argument check failed to satisfy")
 
#define ASSERT_PROPERTY(expr) ASSERT_TEMPL(expr, "Panic: Property check failed to satisfy")
 
#define ASSERT_PRECONDITION(expr) ASSERT_TEMPL(expr, "Panic: Precondition failed to satisfy")
 
#define ASSERT_POSTCONDITION(expr) ASSERT_TEMPL(expr, "Panic: Precondition failed to satisfy")
 
// TODO(Bvb): These can be moved to backend, or removed.
typedef uint8_t *BSL_DataPtr_t;
typedef const uint8_t *BSL_DataConstPtr_t;
 
typedef struct BSL_Data_s
{
    bool owned;
    BSL_DataPtr_t ptr;
    size_t len;
} BSL_Data_t;
 
#define BSL_DATA_INIT_NULL { .owned = false, .ptr = NULL, .len = 0 }
 
int BSL_Data_Init(BSL_Data_t *data);
 
int BSL_Data_InitBuffer(BSL_Data_t *data, size_t bytelen);
 
int BSL_Data_InitView(BSL_Data_t *data, size_t len, BSL_DataPtr_t src);
 
void BSL_Data_InitMove(BSL_Data_t *data, BSL_Data_t *src);
 
int BSL_Data_Deinit(BSL_Data_t *data);
 
int BSL_Data_Resize(BSL_Data_t *data, size_t len);
 
int BSL_Data_CopyFrom(BSL_Data_t *data, size_t len, BSL_DataConstPtr_t src);
 
int BSL_Data_AppendFrom(BSL_Data_t *data, size_t len, BSL_DataConstPtr_t src);
 
typedef struct BSL_SeqReader BSL_SeqReader_t;
 
int BSL_SeqReader_Deinit(BSL_SeqReader_t *obj);
 
int BSL_SeqReader_Get(BSL_SeqReader_t *obj, uint8_t *buf, size_t *bufsize);
 
typedef struct BSL_SeqWriter BSL_SeqWriter_t;
 
int BSL_SeqWriter_Deinit(BSL_SeqWriter_t *obj);
 
int BSL_SeqWriter_Put(BSL_SeqWriter_t *obj, const uint8_t *buf, size_t *bufsize);
 
#define BSL_HOSTEID_INIT_INVALID { .handle = NULL }
 
int BSL_HostEID_Init(BSL_HostEID_t *eid);
 
void BSL_HostEID_Deinit(BSL_HostEID_t *eid);
 
int BSL_Host_GetSecSrcEID(BSL_HostEID_t *eid);
 
int BSL_HostEID_DecodeFromText(BSL_HostEID_t *eid, const char *text);
 
int BSL_HostEID_DecodeFromCBOR(BSL_HostEID_t *eid, void *decoder);
 
#define BSL_HOSTEID_INIT_INVALID { .handle = NULL }
 
int BSL_HostEIDPattern_Init(BSL_HostEIDPattern_t *pat);
 
void BSL_HostEIDPattern_Deinit(BSL_HostEIDPattern_t *pat);
 
int BSL_HostEID_EncodeToCBOR(const BSL_HostEID_t *eid, void *user_data);
 
int BSL_HostEIDPattern_DecodeFromText(BSL_HostEIDPattern_t *pat, const char *text);
 
bool BSL_HostEIDPattern_IsMatch(const BSL_HostEIDPattern_t *pat, const BSL_HostEID_t *eid);
 
typedef enum
{
    BSL_BLOCK_TYPE_PRIMARY = 0,
    BSL_BLOCK_TYPE_PAYLOAD = 1,
    BSL_BLOCK_TYPE_BIB = 11,
    BSL_BLOCK_TYPE_BCB = 12,
} BSL_BundleBlockTypeCode_e;
 
typedef enum
{
    BSL_ASB_FLAG_PARAMS = 1
} BSL_BundleASBFlag_e;
 
typedef struct BSL_BundleTimestamp_s
{
    uint64_t bundle_creation_time;
    uint64_t seq_num;
} BSL_BundleTimestamp_t;
 
typedef enum
{
    BSL_BUNDLE_IS_FRAGMENT = 0x0001,
    // Others TBD
} BSL_BundleCtrlFlag_e;
 
int BSL_BundleCtx_GetBundleMetadata(const BSL_BundleRef_t *bundle, BSL_PrimaryBlock_t *result_primary_block);
 
int BSL_BundleCtx_GetBlockIds(const BSL_BundleRef_t *bundle, size_t array_count,
                              uint64_t block_ids_array[array_count], size_t *result_count);
 
int BSL_BundleCtx_GetBlockMetadata(const BSL_BundleRef_t *bundle, uint64_t block_num,
                                   BSL_CanonicalBlock_t *result_block);
 
int BSL_BundleCtx_CreateBlock(BSL_BundleRef_t *bundle, uint64_t block_type_code, uint64_t *block_num);
 
int BSL_BundleCtx_RemoveBlock(BSL_BundleRef_t *bundle, uint64_t block_num);
 
int BSL_BundleCtx_ReallocBTSD(BSL_BundleRef_t *bundle, uint64_t block_num, size_t bytesize);
 
#define BSL_DEFAULT_BYTESTR_LEN (128)
 
typedef enum
{
    BSL_SECROLE_SOURCE = 1000, 
    BSL_SECROLE_VERIFIER,      
    BSL_SECROLE_ACCEPTOR       
} BSL_SecRole_e;
 
#define BSL_SECROLE_ISVALID(role_value) (((role_value) >= BSL_SECROLE_SOURCE) && ((role_value) <= BSL_SECROLE_ACCEPTOR))
 
typedef enum
{
    BSL_SECBLOCKTYPE_BIB = 11, 
    BSL_SECBLOCKTYPE_BCB = 12  
} BSL_SecBlockType_e;
 
#define BSL_SecBlockType_IsSecBlock(block_id) \
    (((block_id) >= BSL_SECBLOCKTYPE_BIB) && ((block_id) <= BSL_SECBLOCKTYPE_BCB))
 
typedef struct BSL_SecResult_s BSL_SecResult_t;
 
int BSL_SecResult_Init(BSL_SecResult_t *self, uint64_t result_id, uint64_t context_id, uint64_t target_block_num,
                       BSL_Data_t content);
 
bool BSL_SecResult_IsConsistent(const BSL_SecResult_t *self);
 
size_t BSL_SecResult_Sizeof(void);
 
enum BSL_SecParam_Types_e
{
    BSL_SECPARAM_TYPE_UNKNOWN = 0, 
    BSL_SECPARAM_TYPE_INT64,       
    BSL_SECPARAM_TYPE_BYTESTR,     
};
 
typedef enum
{
    BSL_SECPARAM_TYPE_INT_STARTINDEX = 1000,
 
    BSL_SECPARAM_TYPE_INT_KEY_ID,
 
    BSL_SECPARAM_TYPE_INT_FIXED_KEY,
 
    BSL_SECPARAM_TYPE_INT_USE_WRAPPED_KEY,
 
    BSL_SECPARAM_TYPE_AUTH_TAG,
 
    BSL_SECPARAM_TYPE_IV,
 
    BSL_SECPARAM_TYPE_INT_ENDINDEX
} BSL_SecParam_InternalIds;
 
typedef struct BSL_SecParam_s BSL_SecParam_t;
 
uint64_t BSL_SecParam_GetId(const BSL_SecParam_t *self);
 
bool BSL_SecParam_IsConsistent(const BSL_SecParam_t *self);
 
bool BSL_SecParam_IsParamIDOutput(uint64_t param_id);
 
size_t BSL_SecParam_Sizeof(void);
 
int BSL_SecParam_InitBytestr(BSL_SecParam_t *self, uint64_t param_id, BSL_Data_t value);
 
int BSL_SecParam_InitInt64(BSL_SecParam_t *self, uint64_t param_id, uint64_t value);
 
int BSL_SecParam_IsInt64(const BSL_SecParam_t *self);
 
uint64_t BSL_SecParam_GetAsUInt64(const BSL_SecParam_t *self);
 
int BSL_SecParam_GetAsBytestr(const BSL_SecParam_t *self, BSL_Data_t *result);
 
typedef struct BSL_SecOper_s BSL_SecOper_t;
 
size_t BSL_SecOper_Sizeof(void);
 
void BSL_SecOper_Init(BSL_SecOper_t *self, uint64_t context_id, uint64_t target_block_num, uint64_t sec_block_num,
                      BSL_SecBlockType_e sec_type, BSL_SecRole_e sec_role, BSL_PolicyAction_e failure_code);
 
void BSL_SecOper_Deinit(BSL_SecOper_t *self);
 
bool BSL_SecOper_IsConsistent(const BSL_SecOper_t *self);
 
const BSL_SecParam_t *BSL_SecOper_GetParamAt(const BSL_SecOper_t *self, size_t index);
 
uint64_t BSL_SecOper_GetSecurityBlockNum(const BSL_SecOper_t *self);
 
uint64_t BSL_SecOper_GetTargetBlockNum(const BSL_SecOper_t *self);
 
size_t BSL_SecOper_CountParams(const BSL_SecOper_t *self);
 
void BSL_SecOper_AppendParam(BSL_SecOper_t *self, const BSL_SecParam_t *param);
 
bool BSL_SecOper_IsRoleSource(const BSL_SecOper_t *self);
 
bool BSL_SecOper_IsRoleVerifier(const BSL_SecOper_t *self);
 
bool BSL_SecOper_IsRoleAccepter(const BSL_SecOper_t *self);
 
bool BSL_SecOper_IsBIB(const BSL_SecOper_t *self);
 
typedef struct BSL_AbsSecBlock_s BSL_AbsSecBlock_t;
 
size_t BSL_AbsSecBlock_Sizeof(void);
 
void BSL_AbsSecBlock_Init(BSL_AbsSecBlock_t *self, uint64_t sec_context_id, BSL_HostEID_t source_eid);
 
bool BSL_AbsSecBlock_IsConsistent(const BSL_AbsSecBlock_t *self);
 
void BSL_AbsSecBlock_InitEmpty(BSL_AbsSecBlock_t *self);
 
void BSL_AbsSecBlock_Deinit(BSL_AbsSecBlock_t *self);
 
void BSL_AbsSecBlock_Print(const BSL_AbsSecBlock_t *self);
 
bool BSL_AbsSecBlock_IsEmpty(const BSL_AbsSecBlock_t *self);
 
bool BSL_AbsSecBlock_ContainsTarget(const BSL_AbsSecBlock_t *self, uint64_t target_block_num);
 
void BSL_AbsSecBlock_AddTarget(BSL_AbsSecBlock_t *self, uint64_t target_block_id);
 
void BSL_AbsSecBlock_AddParam(BSL_AbsSecBlock_t *self, const BSL_SecParam_t *param);
 
void BSL_AbsSecBlock_AddResult(BSL_AbsSecBlock_t *self, const BSL_SecResult_t *result);
 
int BSL_AbsSecBlock_StripResults(BSL_AbsSecBlock_t *self, uint64_t target_block_num);
 
int BSL_AbsSecBlock_EncodeToCBOR(const BSL_AbsSecBlock_t *self, BSL_Data_t allocated_target);
 
int BSL_AbsSecBlock_DecodeFromCBOR(BSL_AbsSecBlock_t *self, BSL_Data_t encoded_cbor);
 
typedef struct BSL_SecOutcome_s BSL_SecOutcome_t;
 
size_t BSL_SecOutcome_Sizeof(void);
 
void BSL_SecOutcome_Init(BSL_SecOutcome_t *self, const BSL_SecOper_t *sec_oper, size_t allocation_size);
 
void BSL_SecOutcome_Deinit(BSL_SecOutcome_t *self);
 
bool BSL_SecOutcome_IsConsistent(const BSL_SecOutcome_t *self);
 
void BSL_SecOutcome_AppendResult(BSL_SecOutcome_t *self, const BSL_SecResult_t *sec_result);
 
const BSL_SecResult_t *BSL_SecOutcome_GetResultAtIndex(const BSL_SecOutcome_t *self, size_t index);
 
size_t BSL_SecOutcome_CountResults(const BSL_SecOutcome_t *self);
 
void BSL_SecOutcome_AppendParam(BSL_SecOutcome_t *self, const BSL_SecParam_t *param);
 
size_t BSL_SecOutcome_CountParams(const BSL_SecOutcome_t *self);
 
const BSL_SecParam_t *BSL_SecOutcome_GetParamAt(const BSL_SecOutcome_t *self, size_t index);
 
bool BSL_SecOutcome_IsInAbsSecBlock(const BSL_SecOutcome_t *self, const BSL_AbsSecBlock_t *abs_sec_block);
 
size_t BSL_SecurityActionSet_Sizeof(void);
 
void BSL_SecurityActionSet_Init(BSL_SecurityActionSet_t *self);
 
void BSL_SecurityActionSet_IncrError(BSL_SecurityActionSet_t *self);
 
size_t BSL_SecurityActionSet_CountErrors(const BSL_SecurityActionSet_t *self);
 
void BSL_SecurityActionSet_Deinit(BSL_SecurityActionSet_t *self);
 
int BSL_SecurityActionSet_AppendSecOper(BSL_SecurityActionSet_t *self, const BSL_SecOper_t *sec_oper);
 
bool BSL_SecurityActionSet_IsConsistent(const BSL_SecurityActionSet_t *self);
 
size_t BSL_SecurityActionSet_CountSecOpers(const BSL_SecurityActionSet_t *self);
 
const BSL_SecOper_t *BSL_SecurityActionSet_GetSecOperAtIndex(const BSL_SecurityActionSet_t *self, size_t index);
 
int BSL_SecurityActionSet_GetErrCode(const BSL_SecurityActionSet_t *self);
 
size_t BSL_SecurityResponseSet_Sizeof(void);
 
void BSL_SecurityResponseSet_Init(BSL_SecurityResponseSet_t *self, size_t noperations, size_t nfailed);
 
void BSL_SecurityResponseSet_Deinit(BSL_SecurityResponseSet_t *self);
 
bool BSL_SecurityResponseSet_IsConsistent(const BSL_SecurityResponseSet_t *self);
 
size_t BSL_SecurityResponseSet_CountResponses(const BSL_SecurityResponseSet_t *self);
 
int BSL_PolicyRegistry_InspectActions(const BSL_LibCtx_t *bsl, BSL_SecurityActionSet_t *output_action_set,
                                      const BSL_BundleRef_t *bundle, BSL_PolicyLocation_e location);
 
typedef int (*BSL_PolicyInspect_f)(const void *user_data, BSL_SecurityActionSet_t *output_action_set,
                                   const BSL_BundleRef_t *bundle, BSL_PolicyLocation_e location);
 
typedef void (*BSL_PolicyDeinit_f)(void *user_data);
 
struct BSL_PolicyDesc_s
{
    void               *user_data;
    BSL_PolicyInspect_f query_fn;  
    BSL_PolicyDeinit_f  deinit_fn; 
};
 
int BSL_SecCtx_ExecutePolicyActionSet(BSL_LibCtx_t *lib, BSL_SecurityResponseSet_t *output_response,
                                      BSL_BundleRef_t *bundle, const BSL_SecurityActionSet_t *action_set);
 
bool BSL_SecCtx_ValidatePolicyActionSet(BSL_LibCtx_t *lib, const BSL_BundleRef_t *bundle,
                                        const BSL_SecurityActionSet_t *action_set);
 
typedef bool (*BSL_SecCtx_Validate_f)(BSL_LibCtx_t *lib, const BSL_BundleRef_t *bundle, const BSL_SecOper_t *sec_oper);
 
typedef int (*BSL_SecCtx_Execute_f)(BSL_LibCtx_t *lib, const BSL_BundleRef_t *bundle, const BSL_SecOper_t *sec_oper,
                                    BSL_SecOutcome_t *sec_outcome);
 
struct BSL_SecCtxDesc_s
{
    void *user_data;
    BSL_SecCtx_Validate_f validate;
    BSL_SecCtx_Execute_f execute;
};
 
#endif /* BSL_BPSECLIB_PRIVATE_H_ */