/src/freeradius-server/src/freeradius-devel/util/dict.h

Source (jump to first uncovered line)
#pragma once
/*
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
 */

/** Multi-protocol AVP dictionary API
 *
 * @file src/lib/util/dict.h
 *
 * @copyright 2015 The FreeRADIUS server project
 */
RCSIDH(dict_h, "$Id: 0ad1bda348c50556e9d12359321a6485794c017c $")

#ifdef __cplusplus
extern "C" {
#endif

#include <freeradius-devel/build.h>
#include <freeradius-devel/missing.h>
#include <freeradius-devel/util/dl.h>
#include <freeradius-devel/util/ext.h>
#include <freeradius-devel/util/rb.h>
#include <freeradius-devel/util/sbuff.h>
#include <freeradius-devel/util/table.h>
#include <freeradius-devel/util/talloc.h>
#include <freeradius-devel/util/types.h>

#include <stdbool.h>
#include <stdint.h>

/*
 *  Avoid circular type references.
 */
typedef struct dict_attr_s fr_dict_attr_t;
typedef struct fr_dict fr_dict_t;

typedef struct value_box_s fr_value_box_t;

/*
 *  Allow public and private versions of the same structures
 */
#ifdef _CONST
#  error _CONST can only be defined in the local header
#endif
#ifndef _DICT_PRIVATE
#  define _CONST const
#else
#  define _CONST
#endif

#ifdef WITH_VERIFY_PTR
#  define DA_VERIFY(_x)   fr_dict_attr_verify(__FILE__, __LINE__, _x)
#else
#  define DA_VERIFY(_x)   fr_cond_assert(_x)
#endif

typedef struct fr_dict_autoload_talloc_s fr_dict_autoload_talloc_t;

/** Values of the encryption flags
 */
typedef struct {
  unsigned int    is_root : 1;      //!< Is root of a dictionary.

  unsigned int    is_unknown : 1;     //!< This dictionary attribute is ephemeral
                ///< and not part of the main dictionary.

  unsigned int    is_raw : 1;     //!< This dictionary attribute was constructed
                ///< from a known attribute to allow the user
                ///< to assign octets values directly.
                ///< See .is_unknown to determine if it is
                ///< ephemeral.
  unsigned int    is_alias : 1;     //!< This isn't a real attribute, it's a reference to
                ///< to one.
  unsigned int    internal : 1;     //!< Internal attribute, should not be received
                ///< in protocol packets, should not be encoded.
  unsigned int    array : 1;      //!< Pack multiples into 1 attr.

  unsigned int    is_known_width : 1;   //!< is treated as if it has a known width for structs

  unsigned int    has_value : 1;      //!< Has a value.

  unsigned int    is_unsigned : 1;          //!< hackity hack for dates and time deltas

  unsigned int    counter : 1;          //!< integer attribute is actually an impulse / counter

  unsigned int    name_only : 1;      //!< this attribute should always be referred to by name, not by number

  unsigned int    secret : 1;     //!< this attribute should be omitted in debug mode

  /*
   *  @todo - if we want to clean these fields up, make
   *  "subtype" and "type_size" both 4-bit bitfields.  That
   *  gives us an extra 8 bits for adding new flags, and we
   *  can likely get rid of "extra", in order to save one
   *  more bit.
   */
  unsigned int    extra : 1;      //!< really "subtype is used by dict, not by protocol"

  unsigned int    local : 1;          //!< is a local variable

  /*
   *  main: extra is set, then this field is is key, bit, or a uint16 length field.
   *  radius: is one of 9 options for flags
   *  dhcp v4/v6: DNS label, or partial DNS label
   */
  uint8_t     subtype;      //!< protocol-specific values, OR key fields

  /*
   *  Length in bytes for most attributes.
   *  Length in bits for da_is_bit_field(da)
   */
  uint8_t     length;       //!< length of the attribute

  /*
   *  TLVs: 1, 2, or 4.
   *  date / time types: fr_time_res_t, which has 4 possible values.
   *  bit fields: offset in the byte where this bit field ends, which is only
   *    used as a caching mechanism during parsing of the dictionaries.
   */
  uint8_t     type_size;      //!< For TLV2 and root attributes.
} fr_dict_attr_flags_t;

#define flag_time_res type_size
#define flag_byte_offset type_size

/** subtype values for the dictionary when extra=1
 *
 */
enum {
  FLAG_EXTRA_NONE = 0,        //!< no extra meaning, should be invalid
  FLAG_KEY_FIELD,         //!< this is a key field for a subsequent struct
  FLAG_BIT_FIELD,               //!< bit field inside of a struct
  FLAG_LENGTH_UINT8,        //!< string / octets type is prefixed by uint8 of length
  FLAG_LENGTH_UINT16,       //!< string / octets type is prefixed by uint16 of length
};

#define fr_dict_attr_is_key_field(_da) ((_da)->flags.extra && ((_da)->flags.subtype == FLAG_KEY_FIELD))
#define da_is_bit_field(_da) ((_da)->flags.extra && ((_da)->flags.subtype == FLAG_BIT_FIELD))
#define da_is_length_field(_da) ((_da)->flags.extra && (((_da)->flags.subtype == FLAG_LENGTH_UINT8) || ((_da)->flags.subtype == FLAG_LENGTH_UINT16)))
#define da_length_offset(_da) ((_da)->flags.type_size)


/** Extension identifier
 *
 * @note New extension structures should also be added to the to the appropriate table in dict_ext.c
 */
typedef enum {
  FR_DICT_ATTR_EXT_NAME = 0,        //!< Name of the attribute.
  FR_DICT_ATTR_EXT_CHILDREN,        //!< Attribute has children.
  FR_DICT_ATTR_EXT_REF,         //!< Attribute references another
                ///< attribute and/or dictionary.
  FR_DICT_ATTR_EXT_VENDOR,        //!< Cached vendor pointer.
  FR_DICT_ATTR_EXT_DA_STACK,        //!< Cached da stack.
  FR_DICT_ATTR_EXT_ENUMV,         //!< Enumeration values.
  FR_DICT_ATTR_EXT_NAMESPACE,       //!< Attribute has its own namespace.
  FR_DICT_ATTR_EXT_PROTOCOL_SPECIFIC,     //!< Protocol specific extensions
  FR_DICT_ATTR_EXT_MAX
} fr_dict_attr_ext_t;

/** Dictionary attribute
 */
struct dict_attr_s {
  fr_dict_t _CONST* _CONST dict;        //!< Dict attribute belongs to.

  char const    *name;        //!< Attribute name.
  size_t      name_len;     //!< Length of the name.

  unsigned int    attr;       //!< Attribute number.
  unsigned int    depth;        //!< Depth of nesting for this attribute.

  unsigned int    last_child_attr;    //!< highest value of last child attribute.

  fr_type_t   type;       //!< Value type.

  fr_dict_attr_t const  *parent;      //!< Immediate parent of this attribute.
  fr_dict_attr_t const  *next;        //!< Next child in bin.
  fr_dict_attr_t    *fixup;       //!< Attribute has been marked up for fixups.

  fr_dict_attr_flags_t  flags;        //!< Flags.

  uint8_t     ext[FR_DICT_ATTR_EXT_MAX];  //!< Extensions to the dictionary attribute.
} CC_HINT(aligned(FR_EXT_ALIGNMENT));

/** Extension identifier
 *
 * @note New extension structures should also be added to the appropriate table in dict_ext.c
 */
typedef enum {
  FR_DICT_ENUM_EXT_UNION_REF = 0,       //!< Reference to a union/subs-struct.
  FR_DICT_ENUM_EXT_MAX
} fr_dict_enum_ext_t;

/** Value of an enumerated attribute
 *
 * Maps one of more string values to integers and vice versa.
 */
typedef struct {
  char const    *name;        //!< Enum name.
  size_t      name_len;     //!< Allows for efficient name lookups when operating
                ///< on partial buffers.
  fr_value_box_t const  *value;       //!< Enum value (what name maps to).

  uint8_t     ext[FR_DICT_ENUM_EXT_MAX];  //!< Extensions to the dictionary attribute.

  fr_dict_attr_t const  *child_struct[];    //!< for key fields
} fr_dict_enum_value_t CC_HINT(aligned(FR_EXT_ALIGNMENT));

/** Private enterprise
 *
 * Represents an IANA private enterprise allocation.
 *
 * The width of the private enterprise number must be the same for all protocols
 * so we can represent a vendor with a single struct.
 */
typedef struct {
  uint32_t    pen;        //!< Private enterprise number.
  bool      continuation;     //!< we only have one flag for now, for WiMAX
  size_t      type;         //!< Length of type data
  size_t      length;       //!< Length of length data
  char const    *name;        //!< Vendor name.
} fr_dict_vendor_t;

/** Specifies a value which must be present for the module to function
 *
 */
typedef struct {
  fr_value_box_t const  **out;        //!< Enumeration value.
  fr_dict_attr_t const  **attr;       //!< The protocol dictionary the attribute should
                ///< be resolved in. ** so it's a compile time
                ///< constant.
  char const    *name;        //!< of the attribute.
} fr_dict_enum_autoload_t;

/** Specifies an attribute which must be present for the module to function
 *
 */
typedef struct {
  fr_dict_attr_t const  **out;        //!< Where to write a pointer to the resolved
                //!< #fr_dict_attr_t.
  fr_dict_t const   **dict;       //!< The protocol dictionary the attribute should
                ///< be resolved in. ** so it's a compile time
                ///< constant.
  char const    *name;        //!< of the attribute.
  fr_type_t   type;       //!< of the attribute.  Mismatch is a fatal error.
} fr_dict_attr_autoload_t;

/** Specifies a dictionary which must be loaded/loadable for the module to function
 *
 */
typedef struct {
  fr_dict_t const   **out;        //!< Where to write a pointer to the loaded/resolved
                //!< #fr_dict_t.
  char const    *base_dir;      //!< Directory structure beneath share.
  char const    *proto;       //!< The protocol dictionary name.
} fr_dict_autoload_t;

/** Errors returned by attribute lookup functions
 *
 */
typedef enum {
  FR_DICT_ATTR_OK     = 0,      //!< No error.
  FR_DICT_ATTR_NOTFOUND   = -1,     //!< Attribute couldn't be found.
  FR_DICT_ATTR_PROTOCOL_NOTFOUND  = -2,     //!< Protocol couldn't be found.
  FR_DICT_ATTR_PARSE_ERROR  = -3,     //!< Attribute string couldn't be parsed
  FR_DICT_ATTR_INTERNAL_ERROR = -4,     //!< Internal error occurred.
  FR_DICT_ATTR_OOM    = -5,     //!< Memory allocation error.
  FR_DICT_ATTR_NOT_DESCENDENT = -6,     //!< Attribute is not a descendent of the parent
                ///< attribute.
  FR_DICT_ATTR_NOT_ANCESTOR = -7,     //!< Attribute is not an ancestor of the child
                ///< attribute.
  FR_DICT_ATTR_NO_CHILDREN  = -8,     //!< Child lookup in attribute with no children.
  FR_DICT_ATTR_EINVAL   = -9      //!< Invalid arguments.

} fr_dict_attr_err_t;

typedef bool (*fr_dict_attr_valid_func_t)(fr_dict_t *dict, fr_dict_attr_t const *parent,
            char const *name, int attr, fr_type_t type, fr_dict_attr_flags_t *flags);

/*
 *  Forward declarations to avoid circular references.
 */
typedef struct pair_list_s fr_pair_list_t;
typedef struct fr_dbuff_s fr_dbuff_t;

/** A generic interface for decoding packets to fr_pair_ts
 *
 * A decoding function should decode a single top level packet from wire format.
 *
 * Note that unlike #fr_tp_proto_decode_t, this function is NOT passed an encode_ctx.  That is because when we
 * do cross-protocol encoding, the "outer" protocol has no information it can share with the "inner" protocol.
 *
 * @param[in] ctx   to allocate new pairs in.
 * @param[in] vps   where new VPs will be added
 * @param[in] data    to decode.
 * @param[in] data_len    The length of the incoming data.
 * @return
 *  - <= 0 on error.  May be the offset (as a negative value) where the error occurred.
 *  - > 0 on success.  How many bytes were decoded.
 */
typedef ssize_t (*fr_dict_attr_decode_func_t)(TALLOC_CTX *ctx, fr_pair_list_t *vps,
                uint8_t const *data, size_t data_len);

/** A generic interface for encoding fr_pair_ts to packets
 *
 * An encoding function should encode multiple VPs to a wire format packet
 *
 * Note that unlike #fr_tp_proto_encode_t, this function is NOT passed an encode_ctx.  That is because when we
 * do cross-protocol encoding, the "outer" protocol has no information it can share with the "inner" protocol.
 *
 * @param[in] vps   vps to encode
 * @param[in] dbuff   buffer where data can be written
 * @return
 *  - <= 0 on error.  May be the offset (as a negative value) where the error occurred.
 *  - > 0 on success.  How many bytes were encoded
 */
typedef ssize_t(*fr_dict_attr_encode_func_t)(fr_dbuff_t *dbuff, fr_pair_list_t const *vps);

/** Init / free callbacks
 *
 *  Only for "autoref" usage.
 */
typedef int (*fr_dict_protocol_init_t)(void);
typedef void (*fr_dict_protocol_free_t)(void);


/** Protocol-specific callbacks in libfreeradius-PROTOCOL
 *
 */
typedef struct {
  char const    *name;        //!< name of this protocol
  int     default_type_size;    //!< how many octets are in "type" field
  int     default_type_length;    //!< how many octets are in "length" field
  fr_table_num_ordered_t  const *subtype_table;   //!< for "encrypt=1", etc.
  size_t      subtype_table_len;    //!< length of subtype_table
  fr_dict_attr_valid_func_t attr_valid;     //!< validation function for new attributes

  fr_dict_protocol_init_t init;       //!< initialize the library
  fr_dict_protocol_free_t free;       //!< free the library

  fr_dict_attr_decode_func_t decode;      //!< for decoding attributes
  fr_dict_attr_encode_func_t encode;      //!< for encoding attributes
} fr_dict_protocol_t;

typedef struct fr_dict_gctx_s fr_dict_gctx_t;

/*
 *  Dictionary constants
 */
#define FR_DICT_PROTO_MAX_NAME_LEN  (128)     //!< Maximum length of a protocol name.
#define FR_DICT_ENUM_MAX_NAME_LEN (128)      //!< Maximum length of a enum value.
#define FR_DICT_VENDOR_MAX_NAME_LEN (128)      //!< Maximum length of a vendor name.
#define FR_DICT_ATTR_MAX_NAME_LEN (128)      //!< Maximum length of a attribute name.

/** Maximum level of TLV nesting allowed
 */
#define FR_DICT_TLV_NEST_MAX    (24)

/** Maximum level of da stack caching
 */
#define FR_DICT_DA_STACK_CACHE_MAX  (5)

/** Maximum TLV stack size
 *
 * The additional attributes are to account for
 *
 * Root + Vendor + NULL (top frame).
 * Root + Embedded protocol + Root + Vendor + NULL.
 *
 * Code should ensure that it doesn't run off the end of the stack,
 * as this could be remotely exploitable, using odd nesting.
 */
#define FR_DICT_MAX_TLV_STACK   (FR_DICT_TLV_NEST_MAX + 5)

/** Characters that are allowed in dictionary attribute names
 *
 */
extern bool const fr_dict_attr_allowed_chars[UINT8_MAX + 1];

/** Characters that are allowed in dictionary enumeration value names
 *
 */
extern bool const fr_dict_enum_allowed_chars[UINT8_MAX + 1];

/** @name Dictionary structure extensions
 *
 * @{
 */
#include <freeradius-devel/util/dict_ext.h>
/** @} */

/** @name Programmatically create dictionary attributes and values
 *
 * @{
 */
int     fr_dict_attr_add(fr_dict_t *dict, fr_dict_attr_t const *parent, char const *name, int attr,
           fr_type_t type, fr_dict_attr_flags_t const *flags) CC_HINT(nonnull(1,2,3));

int     fr_dict_enum_add_name(fr_dict_attr_t *da, char const *name,
                fr_value_box_t const *value, bool coerce, bool replace);

int     fr_dict_enum_add_name_next(fr_dict_attr_t *da, char const *name) CC_HINT(nonnull);

int     fr_dict_str_to_argv(char *str, char **argv, int max_argc);
/** @} */

/** @name Unknown ephemeral attributes
 *
 * @{
 */
fr_dict_attr_t const  *fr_dict_unknown_add(fr_dict_t *dict, fr_dict_attr_t const *old) CC_HINT(nonnull);

void      fr_dict_unknown_free(fr_dict_attr_t const **da);

fr_dict_attr_t    *fr_dict_unknown_afrom_da(TALLOC_CTX *ctx, fr_dict_attr_t const *da);

static inline fr_dict_attr_t *fr_dict_unknown_copy(TALLOC_CTX *ctx, fr_dict_attr_t const *da)
{
  fr_assert(da->flags.is_unknown);

  return fr_dict_unknown_afrom_da(ctx, da);
}

fr_dict_attr_t    *fr_dict_unknown_vendor_afrom_num(TALLOC_CTX *ctx,
                fr_dict_attr_t const *parent, unsigned int vendor)
                CC_HINT(nonnull(2));

fr_dict_attr_t    *fr_dict_unknown_tlv_afrom_num(TALLOC_CTX *ctx,
                   fr_dict_attr_t const *parent, unsigned int num)
                   CC_HINT(nonnull(2));

fr_dict_attr_t    *fr_dict_unknown_attr_afrom_num(TALLOC_CTX *ctx,
              fr_dict_attr_t const *parent, unsigned int num)
              CC_HINT(nonnull(2));

fr_dict_attr_t    *fr_dict_unknown_attr_afrom_da(TALLOC_CTX *ctx, fr_dict_attr_t const *da)
                   CC_HINT(nonnull(2));


fr_slen_t   fr_dict_unknown_afrom_oid_substr(TALLOC_CTX *ctx,
               fr_dict_attr_t const **out,
               fr_dict_attr_t const *parent,
               fr_sbuff_t *in)
               CC_HINT(nonnull(2,3,4));

int     fr_dict_attr_unknown_parent_to_known(fr_dict_attr_t *da, fr_dict_attr_t const *parent);

fr_dict_attr_t const  *fr_dict_attr_unknown_resolve(fr_dict_t const *dict, fr_dict_attr_t const *da);
/** @} */

/** @name Attribute comparisons
 *
 * @{
 */
static inline  CC_HINT(nonnull) int8_t fr_dict_attr_cmp(fr_dict_attr_t const *a, fr_dict_attr_t const *b)
{
  int8_t ret;

  /*
   *  Comparing unknowns or raws is expensive
   *  because we need to check the lineage.
   */
  if (a->flags.is_unknown | a->flags.is_raw | b->flags.is_unknown | b->flags.is_raw) {
    ret = CMP(a->depth, b->depth);
    if (ret != 0) return ret;

    ret = CMP(a->attr, b->attr);
    if (ret != 0) return ret;

    ret = (a->parent == NULL) - (b->parent == NULL);
    if ((ret != 0) || !a->parent) return ret;

    return fr_dict_attr_cmp(a->parent, b->parent);
  }

  /*
   *  Comparing knowns is cheap because the
   *  DAs are unique.
   */
  return CMP(a, b);
}
/** @} */

/** @name Debugging functions
 *
 * @{
 */
void      fr_dict_namespace_debug(fr_dict_attr_t const *da);

void      fr_dict_attr_debug(fr_dict_attr_t const *da);

void      fr_dict_debug(fr_dict_t const *dict);

void      fr_dict_export(fr_dict_t const *dict);
/** @} */

/** @name Attribute lineage
 *
 * @{
 */
fr_dict_attr_t const  *fr_dict_attr_common_parent(fr_dict_attr_t const *a, fr_dict_attr_t const *b, bool is_ancestor);

int     fr_dict_oid_component_legacy(unsigned int *out, char const **oid);

fr_slen_t   fr_dict_attr_flags_print(fr_sbuff_t *out, fr_dict_t const *dict,
             fr_type_t type, fr_dict_attr_flags_t const *flags);

fr_slen_t   fr_dict_attr_oid_print(fr_sbuff_t *out,
                 fr_dict_attr_t const *ancestor, fr_dict_attr_t const *da, bool numeric);
#define     FR_DICT_ATTR_OID_PRINT_RETURN(...) FR_SBUFF_RETURN(fr_dict_attr_oid_print, ##__VA_ARGS__)

fr_slen_t   fr_dict_attr_by_oid_legacy(fr_dict_t const *dict, fr_dict_attr_t const **parent,
                     unsigned int *attr, char const *oid) CC_HINT(nonnull);

fr_slen_t   fr_dict_oid_component(fr_dict_attr_err_t *err,
                fr_dict_attr_t const **out, fr_dict_attr_t const *parent,
                fr_sbuff_t *in, fr_sbuff_term_t const *tt)
                CC_HINT(nonnull(2,3,4));

fr_slen_t   fr_dict_attr_by_oid_substr(fr_dict_attr_err_t *err,
               fr_dict_attr_t const **out, fr_dict_attr_t const *parent,
               fr_sbuff_t *in, fr_sbuff_term_t const *tt)
               CC_HINT(nonnull(2,3,4));

fr_dict_attr_t const  *fr_dict_attr_by_oid(fr_dict_attr_err_t *err,
               fr_dict_attr_t const *parent, char const *oid)
               CC_HINT(nonnull(2,3));

bool      fr_dict_attr_can_contain(fr_dict_attr_t const *parent, fr_dict_attr_t const *child) CC_HINT(nonnull);

/** @} */

/** @name Attribute, vendor and dictionary lookup
 *
 * @{
 */

/** @hidecallergraph */
fr_dict_attr_t const  *fr_dict_root(fr_dict_t const *dict) CC_HINT(nonnull);

bool      fr_dict_is_read_only(fr_dict_t const *dict);

dl_t      *fr_dict_dl(fr_dict_t const *dict);

fr_slen_t   fr_dict_by_protocol_substr(fr_dict_attr_err_t *err,
               fr_dict_t const **out, fr_sbuff_t *name, fr_dict_t const *dict_def);

fr_dict_t const   *fr_dict_by_protocol_name(char const *name);

fr_dict_t const   *fr_dict_by_protocol_num(unsigned int num);

fr_dict_protocol_t const *fr_dict_protocol(fr_dict_t const *dict);

fr_dict_t const   *fr_dict_by_da(fr_dict_attr_t const *da) CC_HINT(nonnull);

fr_dict_t const   *fr_dict_by_attr_name(fr_dict_attr_t const **found, char const *name);

bool      fr_dict_compatible(fr_dict_t const *dict1, fr_dict_t const *dict2) CC_HINT(nonnull);

/** Return true if this attribute is parented directly off the dictionary root
 *
 * @param[in] da    to check.
 * @return
 *  - true if attribute is top level.
 *  - false if attribute is not top level.
 */
static inline bool fr_dict_attr_is_top_level(fr_dict_attr_t const *da)
{
  if (unlikely(!da) || unlikely(!da->parent)) return false;
  return da->parent->flags.is_root;
}

fr_dict_vendor_t const  *fr_dict_vendor_by_da(fr_dict_attr_t const *da);

fr_dict_vendor_t const  *fr_dict_vendor_by_name(fr_dict_t const *dict, char const *name);

fr_dict_vendor_t const  *fr_dict_vendor_by_num(fr_dict_t const *dict, uint32_t vendor_pen);

fr_dict_attr_t const  *fr_dict_vendor_da_by_num(fr_dict_attr_t const *vendor_root, uint32_t vendor_pen);

fr_slen_t   fr_dict_attr_search_by_qualified_name_substr(fr_dict_attr_err_t *err, fr_dict_attr_t const **out,
                     fr_dict_t const *dict_def,
                     fr_sbuff_t *name, fr_sbuff_term_t const *tt,
                     bool internal, bool foreign)
                     CC_HINT(nonnull(2, 4));

fr_slen_t   fr_dict_attr_search_by_name_substr(fr_dict_attr_err_t *err, fr_dict_attr_t const **out,
                   fr_dict_t const *dict_def,
                 fr_sbuff_t *name, fr_sbuff_term_t const *tt,
                 bool internal, bool foreign)
                 CC_HINT(nonnull(2, 4));

fr_slen_t   fr_dict_attr_search_by_qualified_oid_substr(fr_dict_attr_err_t *err, fr_dict_attr_t const **out,
                        fr_dict_t const *dict_def,
                    fr_sbuff_t *in, fr_sbuff_term_t const *tt,
                    bool internal, bool foreign)
                    CC_HINT(nonnull(2, 4));

fr_dict_attr_t const  *fr_dict_attr_search_by_qualified_oid(fr_dict_attr_err_t *err,
                          fr_dict_t const *dict_def, char const *attr,
                          bool internal, bool foreign)
                    CC_HINT(nonnull(3));

fr_slen_t   fr_dict_attr_search_by_oid_substr(fr_dict_attr_err_t *err, fr_dict_attr_t const **out,
                fr_dict_t const *dict_def,
                fr_sbuff_t *in, fr_sbuff_term_t const *tt,
                bool internal, bool foreign)
                CC_HINT(nonnull(2, 4));

fr_slen_t   fr_dict_attr_by_name_substr(fr_dict_attr_err_t *err, fr_dict_attr_t const **out,
                fr_dict_attr_t const *parent,
                fr_sbuff_t *name, fr_sbuff_term_t const *tt)
                CC_HINT(nonnull(2,3,4));

fr_dict_attr_t const  *fr_dict_attr_by_name(fr_dict_attr_err_t *err, fr_dict_attr_t const *parent,
                char const *attr)
                CC_HINT(nonnull(2,3));

fr_dict_attr_t const  *fr_dict_attr_child_by_num(fr_dict_attr_t const *parent, unsigned int attr);

fr_dict_enum_value_t    *fr_dict_enum_by_value(fr_dict_attr_t const *da, fr_value_box_t const *value);

char const    *fr_dict_enum_name_by_value(fr_dict_attr_t const *da, fr_value_box_t const *value);

fr_dict_enum_value_t    *fr_dict_enum_by_name(fr_dict_attr_t const *da, char const *name, ssize_t len);

fr_slen_t   fr_dict_enum_by_name_substr(fr_dict_enum_value_t **out, fr_dict_attr_t const *da, fr_sbuff_t *in);

fr_slen_t   fr_dict_enum_name_from_substr(fr_sbuff_t *out, fr_sbuff_parse_error_t *err,
                  fr_sbuff_t *in, fr_sbuff_term_t const *tt);

static inline fr_slen_t fr_dict_enum_name_afrom_substr(TALLOC_CTX *ctx, char **out, fr_sbuff_parse_error_t *err,
                   fr_sbuff_t *in, fr_sbuff_term_t const *tt)
      SBUFF_OUT_TALLOC_FUNC_NO_LEN_DEF(fr_dict_enum_name_from_substr, err, in, tt)
/** @} */

/** @name Dictionary and protocol loading
 *
 * @{
 */
int     fr_dict_internal_afrom_file(fr_dict_t **out, char const *internal_name,
                char const *dependent);

int     fr_dict_protocol_afrom_file(fr_dict_t **out, char const *proto_name, char const *proto_dir,
                char const *dependent);

fr_dict_t   *fr_dict_protocol_alloc(fr_dict_t const *parent);

int     fr_dict_read(fr_dict_t *dict, char const *dict_dir, char const *filename);
/** @} */

/** @name Autoloader interface
 *
 * @{
 */
int     fr_dict_enum_autoload(fr_dict_enum_autoload_t const *to_load);

int     fr_dict_attr_autoload(fr_dict_attr_autoload_t const *to_load);

#define     fr_dict_autoload(_to_load) _fr_dict_autoload(_to_load, __FILE__)
int     _fr_dict_autoload(fr_dict_autoload_t const *to_load, char const *dependent);

#define     fr_dict_autofree(_to_free) _fr_dict_autofree(_to_free, __FILE__)
int     _fr_dict_autofree(fr_dict_autoload_t const *to_free, char const *dependent);

#define     fr_dict_autoload_talloc(_ctx, _dict_out, _proto) _fr_dict_autoload_talloc(_ctx, _dict_out, _proto, __FILE__)
fr_dict_autoload_talloc_t *_fr_dict_autoload_talloc(TALLOC_CTX *ctx, fr_dict_t const **out, char const *proto, char const *dependent);

int     fr_dl_dict_enum_autoload(dl_t const *module, void *symbol, void *user_ctx);

int     fr_dl_dict_attr_autoload(dl_t const *module, void *symbol, void *user_ctx);

int     fr_dl_dict_autoload(dl_t const *module, void *symbol, void *user_ctx);

void      fr_dl_dict_autofree(dl_t const *module, void *symbol, void *user_ctx);
/** @} */

/** @name Allocating and freeing
 *
 * @{
 */
fr_dict_t     *fr_dict_alloc(char const *proto_name, unsigned int proto_number) CC_HINT(nonnull);

int     fr_dict_dependent_add(fr_dict_t const *dict, char const *dependent) CC_HINT(nonnull);

int     fr_dict_free(fr_dict_t **dict, char const *dependent) CC_HINT(nonnull);

int     fr_dict_const_free(fr_dict_t const **dict, char const *dependent) CC_HINT(nonnull);
/** @} */

/** @name Global dictionary management
 *
 * @{
 */
fr_dict_gctx_t    *fr_dict_global_ctx_init(TALLOC_CTX *ctx, bool free_at_exit, char const *dict_dir);

void      fr_dict_global_ctx_perm_check(fr_dict_gctx_t *gctx, bool enable);

void      fr_dict_global_ctx_set(fr_dict_gctx_t const *gctx);

int     fr_dict_global_ctx_free(fr_dict_gctx_t const *gctx);

int     fr_dict_global_ctx_dir_set(char const *dict_dir);

void      fr_dict_global_ctx_read_only(void);

void      fr_dict_global_ctx_debug(fr_dict_gctx_t const *gctx);

char const    *fr_dict_global_ctx_dir(void);

typedef struct fr_hash_iter_s fr_dict_global_ctx_iter_t;

fr_dict_t   *fr_dict_global_ctx_iter_init(fr_dict_global_ctx_iter_t *iter) CC_HINT(nonnull);

fr_dict_t   *fr_dict_global_ctx_iter_next(fr_dict_global_ctx_iter_t *iter) CC_HINT(nonnull);

fr_dict_t   *fr_dict_unconst(fr_dict_t const *dict);

fr_dict_attr_t    *fr_dict_attr_unconst(fr_dict_attr_t const *da);

fr_dict_t const   *fr_dict_internal(void);

/** @} */

/** @name Dictionary testing and validation
 *
 * @{
 */
int     fr_dict_parse_str(fr_dict_t *dict, char *buf,
            fr_dict_attr_t const *parent);

ssize_t     fr_dict_valid_name(char const *name, ssize_t len);

ssize_t     fr_dict_valid_oid_str(char const *name, ssize_t len);

fr_dict_attr_t const  *fr_dict_attr_iterate_children(fr_dict_attr_t const *parent, fr_dict_attr_t const **prev);

typedef int   (*fr_dict_walk_t)(fr_dict_attr_t const *da, void *uctx);

int     fr_dict_walk(fr_dict_attr_t const *da, fr_dict_walk_t callback, void *uctx);

void      fr_dict_attr_verify(char const *file, int line, fr_dict_attr_t const *da);
/** @} */

#undef _CONST

#ifdef __cplusplus
}
#endif

Coverage Report

Created: 2024-08-28 06:17