lib/radius/client.h

   1 /*
   2 Copyright (c) 2011, Network RADIUS SARL
   3 All rights reserved.
   4
   5 Redistribution and use in source and binary forms, with or without
   6 modification, are permitted provided that the following conditions are met:
   7     * Redistributions of source code must retain the above copyright
   8       notice, this list of conditions and the following disclaimer.
   9     * Redistributions in binary form must reproduce the above copyright
  10       notice, this list of conditions and the following disclaimer in the
  11       documentation and/or other materials provided with the distribution.
  12     * Neither the name of the <organization> nor the
  13       names of its contributors may be used to endorse or promote products
  14       derived from this software without specific prior written permission.
  15
  16 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  17 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  18 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  19 DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
  20 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  21 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  22 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  23 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  25 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27
  28 /** \file client.h
  29  *  \brief Main header file.
  30  */
  31
  32 #ifndef _RADIUS_CLIENT_H_
  33 #define _RADIUS_CLIENT_H_ 1
  34
  35 /*
  36  *  System-specific header files.
  37  */
  38 #include <config.h>
  39 #include <errno.h>
  40 #include <stdio.h>
  41 #ifdef HAVE_STDINT_H
  42 #include <stdint.h>
  43 #endif
  44 #ifdef HAVE_STDLIB_H
  45 #include <stdlib.h>
  46 #endif
  47 #ifdef HAVE_STRING_H
  48 #include <string.h>
  49 #endif
  50 #include <stdarg.h>
  51 #include <sys/types.h>
  52 #ifdef HAVE_NETDB_H
  53 #include <netdb.h>
  54 #endif
  55 #ifdef HAVE_NETINET_IN_H
  56 #include <netinet/in.h>
  57 #endif
  58 #ifdef HAVE_SYS_TIME_H
  59 #include <sys/time.h>
  60 #endif
  61
  62 #include <radsec/radsec.h>
  63 #include <radsec/radsec-impl.h>
  64 #include <radsec/radius.h>
  65
  66 /** \defgroup build Build Helpers
  67  *
  68  * These definitions give the GNU C compiler more information about
  69  * the functions being compiled.  They are used to either remove
  70  * warnings, or to enable better warnings.
  71  **/
  72
  73 /** \defgroup custom Portability Functions
  74  *
  75  * These functions and definitions should be modified for your local
  76  * system.  See the individual definitions for details.
  77  */
  78
  79 /** \defgroup error Error handling
  80  *
  81  * These definitions and routines manage errors.
  82  */
  83
  84 /** \defgroup value_pair Attribute manipulation
  85  *
  86  * These routines manage structures which map to attributes.
  87  */
  88
  89 /**\defgroup dict Dictionary Lookup Functions
  90  *
  91  * \sa doc/dictionaries.txt
  92  *
  93  * The RADIUS dictionaries perform name to number mappings.  The names
  94  * are used only for administrator convenience, for parsing
  95  * configuration files, and printing humanly-readable output.  The
  96  * numbers are used when encoding data in a packet.
  97  *
  98  * When attributes are decoded from a packet, the numbers are used to
  99  * look up the associated name, which is then placed into a data
 100  * structure.
 101  *
 102  * When the data structures are encoded into a packet, the numbers are
 103  * used to create RFC and VSA format attributes.
 104  *
 105  * \attention The definitions, structures, and functions given below
 106  * are useful only for implementing "low level" RADIUS
 107  * functionality. There is usually no need to refer to them in a
 108  * client application.  The library should be used at a higher level,
 109  * which exposes a much simpler API.
 110  */
 111
 112 /** \defgroup packet Packet manipulation
 113  *
 114  * These routines perform encoding and decoding of RADIUS packets.
 115  */
 116
 117 /** \defgroup print Print / parse functions
 118  *
 119  * These routines convert the internal data structures to a printable
 120  * form, or parse them.
 121  */
 122
 123 /** \defgroup id ID allocation and freeing
 124  *
 125  *  These routines manage RADIUS ID allocation.
 126  */
 127
 128 /** \defgroup attr Low-level attribute encode/decoding
 129  *
 130  * These routines perform "low level" encoding, decoding, sending, and
 131  * reception of RADIUS attributes.  They are called by the \ref packet
 132  * functions.
 133  *
 134  * \attention The structures and functions given below are useful only
 135  * for implementing "low level" RADIUS functionality. There is usually
 136  * no need to refer to them in a client application.  The library
 137  * should be used at a higher level, which exposes a much simpler API.
 138  */
 139
 140 /** \defgroup internal Internal support functions.
 141  *
 142  * These functions are required to perform internal or "low-level"
 143  * data manipulation.  While they are exposed for completeness, they
 144  * should not be called by any application.
 145  */
 146
 147 #ifdef PW_EAP_MESSAGE
 148 #ifndef PW_MESSAGE_AUTHENTICATOR
 149 #error EAP-Message requires Message-Authenticator
 150 #endif
 151 #endif
 152
 153 #ifdef WITHOUT_OPENSSL
 154 #include "md5.h"
 155 #else
 156 #include <openssl/md5.h>
 157 #endif
 158
 159 /** Define for compile-time selection of the MD5 functions.  Defaults to using the OpenSSL functions.  \ingroup custom */
 160 #define RS_MD5_CTX      MD5_CTX
 161 /** Define for compile-time selection of the MD5 functions.  Defaults to using the OpenSSL functions. \ingroup custom */
 162 #define RS_MD5Init      MD5_Init
 163 /** Define for compile-time selection of the MD5 functions.  Defaults to using the OpenSSL functions. \ingroup custom */
 164 #define RS_MD5Update    MD5_Update
 165 /** Define for compile-time selection of the MD5 functions.  Defaults to using the OpenSSL functions. \ingroup custom */
 166 #define RS_MD5Final     MD5_Final
 167
 168
 169 #ifndef RS_MAX_PACKET_LEN
 170 /** The maximum size of a packet that the library will send or receive.  \ingroup custom
 171  *
 172  *  The RFC requirement is to handle at least 4K packets.  However, if
 173  *  you expect to only do username/password authentication, this value
 174  *  can be set to a smaller value, such as 256.
 175  *
 176  *  Be warned that any packets larger than this value will be ignored
 177  *  and silently discarded.
 178  */
 179 #define RS_MAX_PACKET_LEN (4096)
 180 #endif
 181
 182 #ifndef RS_MAX_ATTRIBUTES
 183 /** The maximum number of attributes that the library will allow in a packet.  \ingroup custom
 184  *
 185  *  Packets which contain more than ::RS_MAX_ATTRIBUTES will generate
 186  *  an error.  This value is configurable because there may be a need
 187  *  to accept a large mumber of attributes.
 188  *
 189  *  This value is ignored when packets are sent.  The library will
 190  *  send as many attributes as it is told to send.
 191  */
 192 #define RS_MAX_ATTRIBUTES (200)
 193 #endif
 194
 195 #undef RS_MAX_PACKET_CODE
 196 /** The maximum RADIUS_PACKET::code which we can accept. \ingroup dict
 197  *
 198  *  \attention This should not be changed, as it is used by other
 199  *  structures such as ::nr_packet_codes.
 200  */
 201 #define RS_MAX_PACKET_CODE PW_COA_NAK
 202
 203 /**  The maximum vendor number which is permitted. \ingroup dict
 204  *
 205  *  The RFCs require that the Vendor Id or Private Enterprise Number
 206  *  be encoded as 32 bits, with the upper 8 bits being zero.
 207  */
 208 #define RS_MAX_VENDOR           (1 << 24)
 209
 210 /** Data Type Definitions. \ingroup dict
 211  */
 212 #define TAG_VALID(x)          ((x) < 0x20)
 213
 214 /** The attribute is not encrypted. */
 215 #define FLAG_ENCRYPT_NONE            (0)
 216
 217 /** The attribute is encrypted using the RFC 2865 User-Password method */
 218 #define FLAG_ENCRYPT_USER_PASSWORD   (1)
 219
 220 /** The attribute is encrypted using the RFC 2868 Tunnel-Password method */
 221 #define FLAG_ENCRYPT_TUNNEL_PASSWORD (2)
 222
 223 /** A set of flags which determine how the attribute should be handled.
 224  *
 225  * Most attributes are "normal", and do not require special handling.
 226  * However, some require "encryption", tagging, or have other special
 227  * formats.  This structure contains the various options for the
 228  * attribute formats.
 229  */
 230 typedef struct attr_flags {
 231         unsigned int            has_tag : 1; /**< Attribute has an RFC 2868 tag */
 232         unsigned int            unknown : 1; /**< Attribute is unknown */
 233 #ifdef RS_TYPE_TLV
 234         unsigned int            has_tlv : 1; /* has sub attributes */
 235         unsigned int            is_tlv : 1; /* is a sub attribute */
 236 #endif
 237         unsigned int            extended : 1; /* extended attribute */
 238         unsigned int            extended_flags : 1; /* with flag */
 239         unsigned int            evs : 1;            /* extended VSA */
 240         uint8_t                 encrypt;      /**< Attribute encryption method */
 241         uint8_t                 length;       /**< The expected length of the attribute */
 242 } ATTR_FLAGS;
 243
 244
 245 /** Defines an dictionary mapping for an attribute.  \ingroup dict
 246  *
 247  *  The RADIUS dictionaries map humanly readable names to protocol
 248  *  numbers.  The protocol numbers are used to encode/decode the
 249  *  attributes in a packet.
 250  */
 251 typedef struct nr_dict_attr {
 252         unsigned int            attr;           /**< Attribute number  */
 253         rs_attr_type_t          type;           /**< Data type */
 254         unsigned int            vendor;         /**< Vendor-Id number  */
 255         ATTR_FLAGS              flags;
 256         const char              *name;          /**< Printable name  */
 257 } DICT_ATTR;
 258
 259 /** Defines a dictionary mapping for a named enumeration.  \ingroup dict
 260  *
 261  *  This structure is currently not used.
 262  */
 263 typedef struct nr_dict_value {
 264         const DICT_ATTR         *da;            /**< pointer to a ::DICT_ATTR  */
 265         int                     value;          /**< enumerated value  */
 266         char                    name[1];        /**< printable name  */
 267 } DICT_VALUE;
 268
 269 /** Defines an dictionary mapping for a vendor.  \ingroup dict
 270  *
 271  *  The RADIUS dictionaries map humanly readable vendor names to a
 272  *  Vendor-Id (or Private Enterprise Code) assigned by IANA.  The
 273  *  Vendor-Id is used to encode/decode Vendor-Specific attributes in a
 274  *  packet.
 275  */
 276 typedef struct nr_dict_vendor {
 277         unsigned int            vendor; /**< Vendor Private Enterprise Code  */
 278         size_t                  type;      /**< size of Vendor-Type field */
 279         size_t                  length;    /**< size of Vendor-Length field */
 280         const char              *name;          /**< Printable name  */
 281 } DICT_VENDOR;
 282
 283 /** Union holding all possible types of data for a ::VALUE_PAIR. \ingroup value_pair
 284  *
 285  */
 286 typedef union value_pair_data {
 287         char                    strvalue[RS_MAX_STRING_LEN]; /* +1 for NUL */
 288         uint8_t                 octets[253];
 289         struct in_addr          ipaddr;
 290         struct in6_addr         ipv6addr;
 291         uint32_t                date;
 292         uint32_t                integer;
 293 #ifdef RS_TYPE_SIGNED
 294         int32_t                 sinteger;
 295 #endif
 296 #ifdef RS_TYPE_ABINARY
 297         uint8_t                 filter[32];
 298 #endif
 299         uint8_t                 ifid[8]; /* struct? */
 300         uint8_t                 ipv6prefix[18]; /* struct? */
 301 #ifdef RS_TYPE_TLV
 302         uint8_t                 *tlv;
 303 #endif
 304 } VALUE_PAIR_DATA;
 305
 306
 307 /** C structure version of a RADIUS attribute. \ingroup value_pair
 308  *
 309  * The library APIs use this structure to avoid depending on the
 310  * details of the protocol.
 311  */
 312 typedef struct value_pair {
 313         const DICT_ATTR         *da; /**< dictionary definition */
 314         size_t                  length; /**< number of octets in the data */
 315         int                     tag; /**< tag value if da->flags.has_tag */
 316         struct value_pair       *next; /**< enables a linked list of values  */
 317         VALUE_PAIR_DATA         data;  /**< the data of the attribute */
 318 } VALUE_PAIR;
 319 #define vp_strvalue   data.strvalue
 320 #define vp_octets     data.octets
 321 #define vp_ipv6addr   data.ipv6addr
 322 #define vp_ifid       data.ifid
 323 #define vp_ipv6prefix data.ipv6prefix
 324 #define vp_ipaddr     data.ipaddr.s_addr
 325 #define vp_date       data.integer
 326 #define vp_integer    data.integer
 327 #ifdef RS_TYPE_ABINARY
 328 #define vp_filter     data.filter
 329 #endif
 330 #ifdef RS_TYPE_ETHER
 331 #define vp_ether      data.ether
 332 #endif
 333 #ifdef RS_TYPE_SIGNED
 334 #define vp_signed     data.sinteger
 335 #endif
 336 #ifdef RS_TYPE_TLV
 337 #define vp_tlv        data.tlv
 338 #endif
 339
 340 #ifdef RS_TYPE_TLV
 341 #define RS_ATTR_MAX_TLV (4)
 342 extern const int nr_attr_shift[RS_ATTR_MAX_TLV];
 343 extern const int nr_attr_mask[RS_ATTR_MAX_TLV];
 344 extern const unsigned int nr_attr_max_tlv;
 345 #endif
 346
 347 /** A structure which describes a RADIUS packet. \ingroup packet
 348  *
 349  *  In general, it should not be necessary to refererence the elements
 350  *  of this structure.
 351  */
 352 typedef struct radius_packet {
 353         int                     sockfd; /** The socket descriptor */
 354         struct sockaddr_storage src;    /**< The packet source address  */
 355         struct sockaddr_storage dst;    /**< the packet destination address */
 356         const char              *secret; /**< The shared secret */
 357         size_t                  sizeof_secret; /**< Length of the shared secret */
 358         unsigned int            code;   /**< The RADIUS Packet Code */
 359         int                     id;     /**< The RADIUS Packet Id */
 360         size_t                  length; /**< The RADIUS Packet Length.  This will be no larger than RADIUS_PACKET::sizeof_data */
 361         uint8_t                 vector[16]; /**< A copy of the authentication vector */
 362         int                     flags; /**< Internal flags.  Do not modify this field. */
 363         int                     attempts; /**< The number of transmission attempt  */
 364         uint8_t                 *data;    /**< The raw packet data  */
 365         size_t                  sizeof_data; /**< size of the data buffer  */
 366         VALUE_PAIR              *vps;   /**< linked list of ::VALUE_PAIR */
 367 } RADIUS_PACKET;
 368
 369 #define RS_PACKET_ENCODED  (1 << 0)
 370 #define RS_PACKET_HEADER   (1 << 1)
 371 #define RS_PACKET_SIGNED   (1 << 2)
 372 #define RS_PACKET_OK       (1 << 3)
 373 #define RS_PACKET_VERIFIED (1 << 4)
 374 #define RS_PACKET_DECODED  (1 << 5)
 375
 376
 377 /** Track packets sent to a server. \ingroup id
 378  *
 379  * This data structure tracks Identifiers which are used to
 380  * communicate with a particular destination server.  The application
 381  * should call nr_server_init() to initialize it.  If necessary, the
 382  * application should then call nr_server_set_ipv4() to open an IPv4
 383  * socket to the server.
 384  *
 385  * If the RADIUS packets are being transported over an encapsulation
 386  * layer (e.g. RADIUS over TLS), then nr_server_set_ipv4() does not
 387  * need to be called.  The ::nr_server_t structure should instead be
 388  * associated wih the TLS session / socket.
 389  */
 390 typedef struct nr_server_t {
 391         int sockfd;             /**< socket for sending packets  */
 392         int code;               /**< default value for the Code */
 393
 394         struct sockaddr_storage src; /**< Source address of the packet */
 395         struct sockaddr_storage dst; /**< Destination address of the packet  */
 396
 397         /** The shared secret.
 398          *
 399          *  See also nr_packet_send() and nr_packet_recv().
 400          */
 401         const char      *secret;
 402
 403         /** The length of the shared secret.
 404          *
 405          *  See also nr_packet_send() and nr_packet_recv().
 406          */
 407         size_t          sizeof_secret;
 408
 409         int             used;   /**< Number of used IDs */
 410
 411         void            *free_list; /**< For managing packets */
 412
 413         RADIUS_PACKET   *ids[256]; /**< Pointers to "in flight" packets  */
 414 } nr_server_t;
 415
 416
 417 /** Return a printable error message. \ingroup error
 418  *
 419  *  This function returns a string describing the last error that
 420  *  occurred.  These messages are intended for developers, and are not
 421  *  suitable for display to an end user.  The application using this
 422  *  library should instead produce a "summary" message when an error
 423  *  occurs.  e.g. "Failed to receive a response", is better than
 424  *  messages produced by this function, which contain text like
 425  *  "invalid response authentication vector".  The first is
 426  *  understandable, the second is not.
 427  *
 428  * @param[in] error   The error code (can be less than zero)
 429  * @return            A printable string describing the error.
 430  */
 431 extern const char *nr_strerror(int error);
 432
 433 /** Allocate a ::VALUE_PAIR which refers to a ::DICT_ATTR.  \ingroup value_pair
 434  *
 435  *  This returned ::VALUE_PAIR has no data associated with it.  The
 436  *  nr_vp_set_data() function must be called before placing the
 437  *  ::VALUE_PAIR in a ::RADIUS_PACKET.
 438  *
 439  * @param[in] da       The ::DICT_ATTR associated with the ::VALUE_PAIR
 440  * @return             The created ::VALUE_PAIR, or NULL on error.
 441  */
 442 extern VALUE_PAIR *nr_vp_alloc(const DICT_ATTR *da);
 443
 444 /** Free a ::VALUE_PAIR.  \ingroup value_pair
 445  *
 446  *  This function frees the ::VALUE_PAIR, and sets the head pointer to NULL.
 447  *  If head refers to a ::VALUE_PAIR list, then all of the structures in the
 448  *  list are freed.
 449  *
 450  * @param[in,out] head   The pointer to a ::VALUE_PAIR, or a ::VALUE_PAIR list.
 451  */
 452 extern void nr_vp_free(VALUE_PAIR **head);
 453
 454 /** Initializes a ::VALUE_PAIR from a ::DICT_ATTR \ingroup value_pair
 455  *
 456  *  This function assumes that the ::VALUE_PAIR points to existing
 457  *  and writable memory.
 458  *
 459  * @param[in,out] vp   The ::VALUE_PAIR to be initialized
 460  * @param[in] da       The ::DICT_ATTR used to initialize the ::VALUE_PAIR
 461  * @return             The initialized  ::VALUE_PAIR, or NULL on error.
 462  */
 463 extern VALUE_PAIR *nr_vp_init(VALUE_PAIR *vp, const DICT_ATTR *da);
 464
 465 /** Allocate a ::VALUE_PAIR which refers to an unknown attribute.  \ingroup value_pair
 466  *
 467  *  It is used when an attribute is received, and that attribute does
 468  *  not exist in the dictionaries.
 469  *
 470  *  The returned ::VALUE_PAIR has no data (i.e. VALUE_PAIR::length is
 471  *  zero).  The nr_vp_set_data() function must be called before
 472  *  placing the ::VALUE_PAIR in a ::RADIUS_PACKET.
 473  *
 474  * @param[in] attr     The attribute number, 0..2^16
 475  * @param[in] vendor   The vendor number, 0..2^16
 476  * @return             The created ::VALUE_PAIR, or NULL on error.
 477  */
 478 extern VALUE_PAIR *nr_vp_alloc_raw(unsigned int attr, unsigned int vendor);
 479
 480 /** Set the data associated with a previously allocated ::VALUE_PAIR.  \ingroup value_pair
 481  *
 482  *  If this function succeeds, VALUE_PAIR::length is no longer zero,
 483  *  and the structure contains the data.
 484  *
 485  * @param[in,out] vp   The ::VALUE_PAIR to update
 486  * @param[in] data     Data to set inside of the ::VALUE_PAIR
 487  * @param[in] data_len Length of the data field
 488  * @return             <0 on error, 0 for "data was truncated"
 489  *                      >0 for "data successfully added"
 490  */
 491 extern int nr_vp_set_data(VALUE_PAIR *vp, const void *data, size_t data_len);
 492
 493 /** Create a ::VALUE_PAIR and set its data.  \ingroup value_pair
 494  *
 495  * @param[in] attr     The attribute number of the ::VALUE_PAIR to create
 496  * @param[in] vendor   The vendor number of the ::VALUE_PAIR to create
 497  * @param[in] data     Data to set inside of the ::VALUE_PAIR
 498  * @param[in] data_len Length of the data field
 499  * @return             The created ::VALUE_PAIR, or NULL on error.
 500  */
 501 extern VALUE_PAIR *nr_vp_create(int attr, int vendor, const void *data,
 502                               size_t data_len);
 503
 504 /** Append a ::VALUE_PAIR to the end of a ::VALUE_PAIR list.  \ingroup value_pair
 505  *
 506  * @param[in,out] head The head of the ::VALUE_PAIR list.  May not be NULL.
 507  * @param[in] vp       The ::VALUE_PAIR to append to the list.
 508  */
 509 extern void nr_vps_append(VALUE_PAIR **head, VALUE_PAIR *vp);
 510
 511 /** Search a ::VALUE_PAIR list for one of a given number.  \ingroup value_pair
 512  *
 513  * @param[in] head     The head of the ::VALUE_PAIR list to search.
 514  * @param[in] attr     The attribute number of the ::VALUE_PAIR to find
 515  * @param[in] vendor   The vendor number of the ::VALUE_PAIR to find
 516  * @return             The found ::VALUE_PAIR, or NULL if it was not found.
 517  */
 518 extern VALUE_PAIR *nr_vps_find(VALUE_PAIR *head,
 519                             unsigned int attr, unsigned int vendor);
 520
 521 /** Look up an attribute in the dictionaries.  \ingroup dict
 522  *
 523  *  The dictionary mapping contains information about the attribute,
 524  *  such as printable name, data type (ipaddr, integer, etc), and
 525  *  various other things used to encode/decode the attribute in a
 526  *  packet.
 527  *
 528  *  \attention There is usually no need to call this function.  Use
 529  *  the RS_DA_* definitions instead.
 530  *
 531  * @param[in] attr    Value of the attribute
 532  * @param[in] vendor  Value of the vendor
 533  * @return    NULL for "not found", or a pointer to the attribute mapping.
 534  */
 535 extern const DICT_ATTR *nr_dict_attr_byvalue(unsigned int attr,
 536                                          unsigned int vendor);
 537
 538 /** Look up an attribute in the dictionaries.  \ingroup dict
 539  *
 540  *  The dictionary mapping contains information about the attribute,
 541  *  such as printable name, data type (ipaddr, integer, etc), and
 542  *  various other things used to encode/decode the attribute in a
 543  *  packet.
 544  *
 545  *  \attention There is usually no need to call this function.
 546  *
 547  * @param[in] name    Name of the attribute
 548  * @return    NULL for "not found", or a pointer to the attribute mapping.
 549  */
 550 extern const DICT_ATTR *nr_dict_attr_byname(const char *name);
 551
 552 /** Converts raw data to a ::DICT_ATTR structure.  \ingroup dict
 553  *
 554  *  It is called when the library is asked to decode an attribute
 555  *  which is not in the pre-defined dictionaries.
 556  *
 557  *  \attention There is usually no need to call this function.
 558  *
 559  * @param[in,out] da      The ::DICT_ATTR structure to initialize
 560  * @param[in]     attr    The attribute number
 561  * @param[in]     vendor  The vendor number
 562  * @param[in]     buffer  The buffer where the name of the attribute is stored
 563  * @param[in]     bufsize Size of the buffer
 564  * @return    <0 for error, 0 for success
 565  */
 566 extern int nr_dict_attr_2struct(DICT_ATTR *da,
 567                                 unsigned int attr, unsigned int vendor,
 568                                 char *buffer, size_t bufsize);
 569
 570 /**  Unused. \ngroup dict
 571  *
 572  */
 573 extern const DICT_VALUE *nr_dict_value_byattr(unsigned int attr,
 574                                         unsigned int vendor,
 575                                         int value);
 576
 577 /**  Unused. \ngroup dict
 578  *
 579  */
 580 const DICT_VALUE *nr_dict_value_byname(unsigned int attr,
 581                                  unsigned int vendor,
 582                                  const char *name);
 583
 584 /** Look up a vendor in the dictionaries.  \ingroup dict
 585  *
 586  *  The dictionary mapping contains information about the vendor, such
 587  *  as printable name, VSA encoding method, etc.
 588  *
 589  *  \attention There is usually no need to call this function.
 590  *  Applications do not need access to low-level RADIUS protocol
 591  *  information.
 592  *
 593  * @param[in] name    Name of the vendor.
 594  * @return    NULL for "not found", or a pointer to the vendor mapping.
 595  */
 596 extern int nr_dict_vendor_byname(const char *name);
 597
 598 /** Look up an vendor in the dictionaries.  \ingroup dict
 599  *
 600  *  The dictionary mapping contains information about the vendor, such
 601  *  as printable name, VSA encoding method, etc.
 602  *
 603  *  \attention There is usually no need to call this function.
 604  *
 605  * @param[in] vendor Vendor-Id (or Private Enterprise code) for the vendor.
 606  * @return    NULL for "not found", or a pointer to the vendor mapping.
 607  */
 608 extern const DICT_VENDOR *nr_dict_vendor_byvalue(unsigned int vendor);
 609
 610 /**  Static array of known vendors.  \ingroup dict
 611  *
 612  *  \attention This structure should only be accessed by internal RADIUS library
 613  *  functions.
 614  */
 615 extern const DICT_VENDOR nr_dict_vendors[];
 616
 617 /** The number of attribute definitions in the dictionary.  \ingroup dict
 618  *
 619  *  This number is guaranteed to be at least 256, for speed.
 620  *
 621  *  \attention This variable should only be accessed by internal RADIUS library
 622  *  functions.
 623  */
 624 extern const int nr_dict_num_attrs;
 625
 626 /** The list of attribute definitions.  \ingroup dict
 627  *
 628  *  The "standard" RFC attributes are located in the first 256
 629  *  entries.  Standard attributes without a dictionary definition are
 630  *  given an empty entry.
 631  *
 632  *  The attributes are orderd by (vendor, attribute), in increasing
 633  *  order.  This allows the dictionary lookups to find attributes by a
 634  *  binary search.
 635  *
 636  *  \attention This variable should only be accessed by internal RADIUS library
 637  *  functions.
 638  */
 639 extern const DICT_ATTR nr_dict_attrs[];
 640
 641 /** The number of attributes with names.  \ingroup dict
 642  *
 643  *  \attention This variable should only be accessed by internal RADIUS library
 644  *  functions.
 645  */
 646 extern const int nr_dict_num_names;
 647
 648 /** The list of attribute definitions, organized by name.  \ingroup dict
 649  *
 650  *  The attributes are orderd by name (case insensitive), in
 651  *  increasing order.  This allows the dictionary lookups to find
 652  *  attributes by a binary search.
 653  *
 654  *  \attention This variable should only be accessed by internal RADIUS library
 655  *  functions.
 656  */
 657 extern const DICT_ATTR const *nr_dict_attr_names[];
 658
 659 /** Static array containing names the RADIUS_PACKET::code field.  \ingroup dict
 660  *
 661  *  The names are hard-coded and not in any dictionary because they do
 662  *  not change.
 663  *
 664  *  The names are exported because they may be useful in your
 665  *  application.  Packet codes which are not handled by the library
 666  *  have NULL for their names.
 667  */
 668 extern const char *nr_packet_codes[RS_MAX_PACKET_CODE + 1];
 669
 670 /** Verifies that a packet is "well formed".  \ingroup packet
 671  *
 672  *  This function performs basic validation to see if the packet is
 673  *  well formed.  It is automatically called by nr_packet_decode().
 674  *
 675  * @param[in] packet      A pointer to the ::RADIUS_PACKET data.
 676  * @return                <0 means malformed, >= 0 means well-formed.
 677  */
 678 extern int nr_packet_ok(RADIUS_PACKET *packet);
 679
 680 /** Verifies that a packet is "well formed".  \ingroup packet
 681  *
 682  *  This function performs basic validation to see if the packet is
 683  *  well formed.  You should normally use nr_packet_ok() instead of
 684  *  this function.
 685  *
 686  * @param[in] data        A pointer to the raw packet data.
 687  * @param[in] sizeof_data The length of the raw packet data
 688  * @return                <0 means malformed, >= 0 means well-formed.
 689  */
 690 extern int nr_packet_ok_raw(const uint8_t *data, size_t sizeof_data);
 691
 692 /** Encodes a packet.  \ingroup packet
 693  *
 694  *  This function encodes a packet using the fields of the
 695  *  ::RADIUS_PACKET structure.  The RADIUS_PACKET::code and
 696  *  RADIUS_PACKET::id fields are used to fill in the relevant fields
 697  *  of the raw (encoded) packet.  The RADIUS_PACKET::vps list is
 698  *  walked to encode the attributes.  The packet is signed, if
 699  *  required.
 700  *
 701  *  The raw packet is placed into the RADIUS_PACKET::data field, up to
 702  *  RADIUS_PACKET::sizeof_data bytes.  the RADIUS_PACKET::length field
 703  *  is updated with the length of the raw packet.  This field is
 704  *  always less than, or equal to, the RADIUS_PACKET::size_data field.
 705  *  If there is insufficient room to store all of the attributes, then
 706  *  some attributes are silently discarded.
 707  *
 708  *  The RADIUS_PACKET::vector field is either calculated as part of
 709  *  the signing process, or is initialized by this function to be a
 710  *  random sequence of bytes.  That field should therefore be left
 711  *  alone by the caller.
 712  *
 713  *  When the encoding has been successful, it sets the
 714  *  RADIUS_PACKET::encoded field to non-zero.
 715  *
 716  *  In addition, all required attribute "encryption" is performed.
 717  *
 718  *  User-Password.  The vp_strvalue field is assumed to contain the
 719  *  "clear-text" version of the password.  The encrypted version is
 720  *  calculated, and placed in the packet.
 721  *
 722  *  CHAP-Password.  The vp_strvalue field is assumed to contain the
 723  *  "clear-text" version of the password.  The encrypted version is
 724  *  calculated, and placed in the packet.  If the RADIUS_PACKET::vps
 725  *  list contains a CHAP-Challenge attribute, it is used.  Otherwise
 726  *  the RADIUS_PACKET::vector field is used a the challenge.
 727  *
 728  *  Message-Authenticator.  The contents of the Message-Authenticator
 729  *  in the RADIUS_PACKET::vps list are ignored.  Instead, a
 730  *  "place-holder" is put into the packt.  Tthe correct value is
 731  *  calculated and placed into the packet by nr_packet_sign().
 732  *
 733  *  The RADIUS_PACKET::vps list is left untouched by this function,
 734  *  even when attribute encryption or signing is performed.  Any
 735  *  VALUE_PAIR structures can therefore be taken from static "const"
 736  *  variables.
 737  *
 738  * @param[in] packet   The RADIUS packet to encode.
 739  * @param[in] original The original request, when encoding a response.
 740  * @return             <0 on error, >= 0 on success.
 741  */
 742 extern int nr_packet_encode(RADIUS_PACKET *packet, const RADIUS_PACKET *original);
 743
 744 /** Decodes a packet.  \ingroup packet
 745  *
 746  *  This function decodes a packet from the RADIUS_PACKET::data field
 747  *  into a sequence of ::VALUE_PAIR structures in the
 748  *  RADIUS_PACKET::vps list.
 749  *
 750  * @param[in] packet   The RADIUS packet to decode.
 751  * @param[in] original The original request, when decoding a response.
 752  * @return             <0 on error, >= 0 on success.
 753  */
 754 extern int nr_packet_decode(RADIUS_PACKET *packet, const RADIUS_PACKET *original);
 755
 756 /** Signs a packet so that it can be sent.  \ingroup packet
 757  *
 758  * This function calculates the Message-Authenticator (if required),
 759  * and signs the packet.
 760  *
 761  * @param[in] packet   The RADIUS packet to sign.
 762  * @param[in] original The original request, when signing a response.
 763  * @return             <0 on error, >= 0 on success.
 764  */
 765 extern int nr_packet_sign(RADIUS_PACKET *packet, const RADIUS_PACKET *original);
 766
 767 /** Verifies that a packet is well-formed and contains the correct signature.  \ingroup packet
 768  *
 769  *  If "original" is specified, it also verifies that the packet is a
 770  *  response to the original request, and that it has the correct
 771  *  signature.
 772  *
 773  * @param[in] packet   The RADIUS packet to verify.
 774  * @param[in] original The original request, when verifying a response.
 775  * @return             <0 on error, >= 0 on success.
 776  */
 777 extern int nr_packet_verify(RADIUS_PACKET *packet,
 778                             const RADIUS_PACKET *original);
 779
 780 /** Pretty-prints a hex dump of a RADIUS packet.  \ingroup packet print
 781  *
 782  *  This function is available only in debugging builds of the
 783  *  library.  It is useful during development, but should not be used
 784  *  in a production system.
 785  *
 786  *  The packet headers are printed individually, and each attribute is
 787  *  printed as "type length data..."
 788  *
 789  * @param[in] packet   The RADIUS packet to print
 790  */
 791 extern void nr_packet_print_hex(RADIUS_PACKET *packet);
 792
 793
 794 /** Return the given number of random bytes.  \ingroup custom
 795  *
 796  * This function should be replaced by one that is specific to your
 797  * system.
 798  *
 799  *  This is a wrapper function which enables the library to be more
 800  *  portable.
 801  *
 802  * @param[in] data      Location where the random bytes will be stored
 803  * @param[in] data_len  Number of bytes to store
 804  * @return              <0 on error, or the total number of bytes stored.
 805  */
 806 extern ssize_t nr_rand_bytes(uint8_t *data, size_t data_len);
 807
 808 /** Return a random 32-bit integer.  \ingroup custom
 809  *
 810  * This function should be replaced by one that is specific to your
 811  * system.  The version supplied here just calls nr_rand_bytes() each
 812  * time, which is slow.
 813  *
 814  *  This is a wrapper function which enables the library to be more
 815  *  portable.
 816  *
 817  * @return An unsigned 32-bit random integer.
 818  */
 819 extern uint32_t nr_rand(void);
 820
 821 /** Add a time to the given ::struct timeval.  \ingroup custom
 822  *
 823  *  This is a wrapper function which enables the library to be more
 824  *  portable.
 825  *
 826  *  @param[in,out] t       The timeval to which the time is added.
 827  *  @param[in]     seconds Time in seconds to add
 828  *  @param[in]     usec    Time in microseconds to add
 829  */
 830 extern void nr_timeval_add(struct timeval *t, unsigned int seconds,
 831                            unsigned int usec);
 832
 833 /** Compare two times.  \ingroup custom
 834  *
 835  *  This is a wrapper function which enables the library to be more
 836  *  portable.
 837  *
 838  * @param[in] a One timeval
 839  * @param[in] b Another one
 840  * @return a <=> b
 841  */
 842 extern int nr_timeval_cmp(const struct timeval *a, const struct timeval *b);
 843
 844 /** Initializes an ::nr_server_t.  \ingroup id
 845  *
 846  * @param[in,ut] s      The ::nr_server_t to initialize
 847  * @param[in]    code   The packet code used for packets sent to this server
 848  * @param[in]    secret The shared secret used for packet sent to this server
 849  * @return <0 for error, >= 0 for success
 850  */
 851 extern int nr_server_init(nr_server_t *s, int code, const char *secret);
 852
 853 /** Closes an ::nr_server_t data structure.  \ingroup id
 854  *
 855  *  Ensures that all IDs are free, and closes the socket.
 856  *
 857  * @param[in] s      The server structure to close.
 858  * @return <0 for error, 0 for success
 859  */
 860 extern int nr_server_close(const nr_server_t *s);
 861
 862 /** Allocate a RADIUS_PACKET::id value for sending a packet to a server. \ingroup id
 863  *
 864  * This function allocates a RADIUS_PACKET::id from the ::nr_server_t
 865  * structure.  It also fills in the RADIUS_PACKET::sockfd,
 866  * RADIUS_PACKET::code, and RADIUS_PACKET::dst fields.
 867  *
 868  * @param[in] s      The server structure which tracks the ID
 869  * @param[in] packet The packet which needs an ID
 870  * @return <0 for error, 0 for success
 871  */
 872 extern int nr_server_id_alloc(nr_server_t *id, RADIUS_PACKET *packet);
 873
 874 /** Re-allocate a RADIUS_PACKET::id value for sending a packet to a server. \ingroup id
 875  *
 876  *  It is used when retransmitting an Accounting-Request packet to a
 877  *  server, after updating the Acct-Delay-Time field.  The "realloc"
 878  *  name means that the new ID is allocated, and is guaranteed to be
 879  *  different from the old one.
 880  *
 881  * @param[in] s      The server structure which tracks the ID
 882  * @param[in] packet The packet which needs a new ID
 883  * @return <0 for error, 0 for success
 884  */
 885 extern int nr_server_id_realloc(nr_server_t *id, RADIUS_PACKET *packet);
 886
 887 /** Free a RADIUS_PACKET::id value after sending a packet to a server. \ingroup id
 888  *
 889  * @param[in] s      The server structure which tracks the ID
 890  * @param[in] packet The packet which has an ID, and wants to free it
 891  * @return <0 for error, 0 for success
 892  */
 893 extern int nr_server_id_free(nr_server_t *id, RADIUS_PACKET *packet);
 894
 895
 896 /** Allocates a packet using malloc(), and initializes it. \ingroup id
 897  *
 898  * @param[in] s             The server structure
 899  * @param[in,out] packet_p  Pointer to the ::RADIUS_PACKET to be allocated
 900  * @return <0 for error, 0 for success
 901  */
 902 extern int nr_server_packet_alloc(const nr_server_t *s, RADIUS_PACKET **packet_p);
 903
 904 /**  Record a humanly readable error message. \ingroup error
 905  *
 906  *  \attention This structure should only be accessed by internal
 907  *  RADIUS library functions.
 908  *
 909  * @param[in] fmt   The format to use.
 910  */
 911 extern void nr_strerror_printf(const char *fmt, ...);
 912
 913 #ifndef NDEBUG
 914 #define nr_debug_error nr_strerror_printf /** \ingroup error */
 915 #else
 916 #define nr_debug_error if (0) nr_strerror_printf
 917 #endif
 918
 919 /**  Encrypts or decrypts a User-Password attribute. \ingroup internal
 920  *
 921  *  \attention This structure should only be accessed by internal
 922  *  RADIUS library functions.
 923  *
 924  * @param[out] output   Buffer where the password is stored
 925  * @param[out] outlen   Size of the output buffer
 926  * @param[in]  input    Input buffer with password
 927  * @param[in]  inlen    Length of the input buffer
 928  * @param[in]  secret   The shared secret
 929  * @param[in]  vector   Authentication vector
 930  * @return <0 on error, or the length of data in "output"
 931  */
 932 extern ssize_t nr_password_encrypt(uint8_t *output, size_t outlen,
 933                                    const uint8_t *input, size_t inlen,
 934                                    const char *secret, const uint8_t *vector);
 935
 936 /**  Encrypts a Tunnel-Password attribute. \ingroup internal
 937  *
 938  *  \attention This structure should only be accessed by internal
 939  *  RADIUS library functions.
 940  *
 941  * @param[out] output   Buffer where the password is stored
 942  * @param[out] outlen   Size of the output buffer
 943  * @param[in]  input    Input buffer with password
 944  * @param[in]  inlen    Length of the input buffer
 945  * @param[in]  secret   The shared secret
 946  * @param[in]  vector   Authentication vector
 947  * @return <0 on error, or the length of data in "output"
 948  */
 949 extern ssize_t nr_tunnelpw_encrypt(uint8_t *output, size_t outlen,
 950                                    const uint8_t *input, size_t inlen,
 951                                    const char *secret, const uint8_t *vector);
 952
 953 /**  Decrypts a Tunnel-Password attribute. \ingroup internal
 954  *
 955  *
 956  *  \attention This structure should only be accessed by internal
 957  *  RADIUS library functions.
 958  *
 959  * @param[out] output   Buffer where the password is stored
 960  * @param[out] outlen   Size of the output buffer
 961  * @param[in]  input    Input buffer with password
 962  * @param[in]  inlen    Length of the input buffer
 963  * @param[in]  secret   The shared secret
 964  * @param[in]  vector   Authentication vector
 965  * @return <0 on error, or the length of data in "output"
 966  */
 967 extern ssize_t nr_tunnelpw_decrypt(uint8_t *output, size_t outlen,
 968                                    const uint8_t *input, size_t inlen,
 969                                    const char *secret, const uint8_t *vector);
 970
 971 /**  Calculates an HMAC-MD5. \ingroup internal
 972  *
 973  * @param[in] data      Data to be hashed
 974  * @param[in] data_len  Length of data to be hashed
 975  * @param[in] key       Key for the HMAC
 976  * @param[in] key_len   Length of the key
 977  * @param[out] digest
 978  */
 979 extern void nr_hmac_md5(const uint8_t *data, size_t data_len,
 980                         const uint8_t *key, size_t key_len,
 981                         uint8_t digest[16]);
 982
 983 /** Checks if a TLV is properly formatted. \ingroup internal
 984  *
 985  *  \attention This structure should only be accessed by internal
 986  *  RADIUS library functions.
 987  *
 988  * @param[in] data      Data to check
 989  * @param[in] length    Length of the data field
 990  * @param[in] dv_type   Length of the TLV "type" field
 991  * @param[in] dv_length Length of the TLV "length" field
 992  * @return             <0 on error, 0 for "TLV is OK"
 993  */
 994 extern int nr_tlv_ok(const uint8_t *data, size_t length,
 995                       size_t dv_type, size_t dv_length);
 996
 997 /** A callback function used by nr_packet_walk().  \ingroup packet
 998  *
 999  *  The function should return 0 on success (i.e. keep walking), and
1000  *  otherwise a negative number indicating an error code
1001  *  (::nr_error_t).  That negative number will be used as the return
1002  *  code for nr_packet_walk().
1003  */
1004 typedef int (*nr_packet_walk_func_t)(void *, const DICT_ATTR *, const uint8_t *, size_t);
1005
1006 /** Walks over all attributes in a packet. \ingroup packet
1007  *
1008  *  This function is an iterator which calls a user-supplied callback
1009  *  function for each attribute in the packet.  It should be used
1010  *  instead of manually walking over the attributes.  There are a
1011  *  number of odd corner cases when handling Vendor-Specific
1012  *  attributes, and it is easy to get those corner cases wrong.
1013  *
1014  *  This function iterates over *all* attributes, including nested
1015  *  VSAs.  That is its main value.
1016  *
1017  *  Encrypted attributes such as User-Password are not decrypted.
1018  *
1019  * @param[in] packet    The packet containing the data
1020  * @param[in] ctx       A user-supplied context.  May be NULL
1021  * @param[in] callback  The callback function where the information is passed.
1022  *
1023  * @return <0 for error,
1024  *          0 for success.
1025  */
1026 extern int nr_packet_walk(RADIUS_PACKET *packet, void *ctx,
1027                           nr_packet_walk_func_t callback);
1028
1029 /** Initialize a packet
1030  *
1031  *  If original is specified, the packet is initialized as a response
1032  *  to the original request.
1033  *
1034  * @param[in,out] packet  The packet to initialize
1035  * @param[in] original    The original request (if any) to use as a template
1036  * @param[in] secret      Shared secret
1037  * @param[in] code        RADIUS Code field.
1038  * @param[in] data        Buffer where packets will be stored (RADIUS_PACKET::data)
1039  * @param[in] sizeof_data Size of buffer (RADIUS_PACKET::sizeof_data)
1040  * @return  <0 on error, 0 for success.
1041  */
1042 extern int nr_packet_init(RADIUS_PACKET *packet, const RADIUS_PACKET *original,
1043                           const char *secret, int code,
1044                           void *data, size_t sizeof_data);
1045
1046 /** Add one attribute to the packet.
1047  *
1048  *  This function can be used to add "raw" data to a packet.  It
1049  *  allows the caller to extend the RADIUS packet without using a
1050  *  ::VALUE_PAIR data structure.
1051  *
1052  *  Some attributes are handled specially by this function.
1053  *
1054  *  EAP-Message.  This attribute is automatically split into 253-octet
1055  *  chunks.
1056  *
1057  *  User-Password, CHAP-Password, and Message-Authenticator.  These
1058  *  attributes are automatically encrypted, as is done by
1059  *  nr_packet_encode().
1060  *
1061  * @param[in] packet   The packet to edit
1062  * @param[in] original The original request (if any)
1063  * @param[in] da       Pointer to the attribute definition
1064  * @param[in] data     Data to append to the packet
1065  * @param[in] data_len Length of data to append to the packet
1066  *
1067  * @return <0 for error, >= 0 for "successfully appended data"
1068  *  The function returns the number of octets appended to the packet.
1069  */
1070 extern ssize_t nr_packet_attr_append(RADIUS_PACKET *packet,
1071                                      const RADIUS_PACKET *original,
1072                                      const DICT_ATTR *da,
1073                                      const void *data, size_t data_len);
1074
1075
1076 /** Encodes any ::VALUE_PAIR into an attribute.  \ingroup attr
1077  *
1078  *  This function can be called for any ::VALUE_PAIR.  It will examine
1079  *  that structure, and call one of nr_vp2rfc() or nr_vp2vsa() as
1080  *  necessary.
1081  *
1082  * \attention This function should not be called.
1083  *
1084  * @param[in] packet   Where to place the encoded attribute.
1085  * @param[in] original The original request (optional), if "packet" is a response
1086  * @param[in,out] pvp  The ::VALUE_PAIR to encode.  On any return >=0, it is updated to point to the "next" ::VALUE_PAIR which should be encoded.
1087  * @param[in] data     Where the attribute is to be encoded.
1088  * @param[in] room     How many octets are available for attribute encoding.
1089  *
1090  * @return <0 for error, or the number of octets used to encode the attribute.
1091  */
1092 extern ssize_t nr_vp2attr(const RADIUS_PACKET *packet,
1093                       const RADIUS_PACKET *original,
1094                       const VALUE_PAIR **pvp, uint8_t *data, size_t room);
1095
1096 /** Encodes an RFC "standard" ::VALUE_PAIR into an attribute.  \ingroup attr
1097  *
1098  *  \attention This function should not be called.
1099  *
1100  * @param[in] packet   Where to place the encoded attribute.
1101  * @param[in] original The original request (optional), if "packet" is a response
1102  * @param[in,out] pvp  The ::VALUE_PAIR to encode.  On any return >=0, it is updated to point to the "next" ::VALUE_PAIR which should be encoded.
1103  * @param[in] data      Where the attribute is to be encoded.
1104  * @param[in] room     How many octets are available for attribute encoding.
1105  *
1106  * @return <0 for error, or the number of octets used to encode the attribute.
1107  */
1108 extern ssize_t nr_vp2rfc(const RADIUS_PACKET *packet,
1109                      const RADIUS_PACKET *original,
1110                      const VALUE_PAIR **pvp,
1111                      uint8_t *data, size_t room);
1112
1113 /** Decodes any attribute into a ::VALUE_PAIR.  \ingroup attr
1114  *
1115  *  \attention This function should not be called.
1116  *
1117  * @param[in] packet   The packet containing the attribute to be decoded.
1118  * @param[in] original The original request (optional), if "packet" is a response
1119  * @param[out] pvp     Where to place the decoded ::VALUE_PAIR.  On any return >=0, it is updated to point to the ::VALUE_PAIR which was decoded from the packet.
1120  * @param[in] data     Where the attribute is to be encoded.
1121  * @param[in] length   How many octets are available for attribute decoding.
1122  *
1123  * @return <0 for error, or the number of octets used to decode the attribute.
1124  */
1125 extern ssize_t nr_attr2vp(const RADIUS_PACKET *packet, const RADIUS_PACKET *original,
1126                             const uint8_t *data, size_t length,
1127                             VALUE_PAIR **pvp);
1128
1129 /** Decodes an RFC "standard" attribute into a ::VALUE_PAIR.  \ingroup attr
1130  *
1131  *  \attention This function should not be called.
1132  *
1133  * @param[in] packet   The packet containing the attribute to be decoded.
1134  * @param[in] original The original request (optional), if "packet" is a response
1135  * @param[out] pvp     Where to place the decoded ::VALUE_PAIR.  On any return >=0, it is updated to point to the ::VALUE_PAIR which was decoded from the packet.
1136  * @param[in] data     Where the attribute is to be encoded.
1137  * @param[in] length   How many octets are available for attribute decoding.
1138  *
1139  * @return <0 for error, or the number of octets used to decode the attribute.
1140  */
1141 extern ssize_t nr_attr2vp_rfc(const RADIUS_PACKET *packet,
1142                         const RADIUS_PACKET *original,
1143                         const uint8_t *data, size_t length,
1144                         VALUE_PAIR **pvp);
1145
1146 /** Decodes a Vendor-Specific attribute into a ::VALUE_PAIR.  \ingroup attr
1147  *
1148  *  \attention This function should not be called.
1149  *
1150  * @param[in] packet   The packet containing the attribute to be decoded.
1151  * @param[in] original The original request (optional), if "packet" is a response
1152  * @param[out] pvp     Where to place the decoded ::VALUE_PAIR.  On any return >=0, it is updated to point to the ::VALUE_PAIR which was decoded from the packet.
1153  * @param[in] data     Where the attribute is to be encoded.
1154  * @param[in] length   How many octets are available for attribute decoding.
1155  *
1156  * @return <0 for error, or the number of octets used to decode the attribute.
1157  */
1158 extern ssize_t nr_attr2vp_vsa(const RADIUS_PACKET *packet,
1159                         const RADIUS_PACKET *original,
1160                         const uint8_t *data, size_t length,
1161                         VALUE_PAIR **pvp);
1162
1163 /** Decodes an attribute with an unexpected length into a ::VALUE_PAIR.  \ingroup attr
1164  *
1165  *  \attention This function should not be called.
1166  *
1167  * @param[in] packet   The packet containing the attribute to be decoded.
1168  * @param[in] original The original request (optional), if "packet" is a response
1169  * @param[out] pvp     Where to place the decoded ::VALUE_PAIR.  On any return >=0, it is updated to point to the ::VALUE_PAIR which was decoded from the packet.
1170  * @param[in] data     Where the attribute is to be encoded.
1171  * @param[in] length   How many octets are available for attribute decoding.
1172  *
1173  * @return <0 for error, or the number of octets used to decode the attribute.
1174  */
1175 extern ssize_t nr_attr2vp_raw(const RADIUS_PACKET *packet,
1176                         const RADIUS_PACKET *original,
1177                         const uint8_t *data, size_t length,
1178                         VALUE_PAIR **pvp);
1179
1180 /** Encodes a Vendor-Specific ::VALUE_PAIR into an attribute.
1181  *
1182  *  \attention This function should not be called.
1183  *
1184  * @param[in] packet   Where to place the encoded attribute.
1185  * @param[in] original The original request (optional), if "packet" is a response
1186  * @param[in,out] pvp  The ::VALUE_PAIR to encode.  On any return >=0, it is updated to point to the "next" ::VALUE_PAIR which should be encoded.
1187  * @param[in] data     Where the attribute is to be encoded.
1188  * @param[in] room     How many octets are available for attribute encoding.
1189  *
1190  * @return <0 for error, or the number of octets used to encode the attribute.
1191  */
1192 extern ssize_t nr_vp2vsa(const RADIUS_PACKET *packet, const RADIUS_PACKET *original,
1193                      const VALUE_PAIR **pvp, uint8_t *data,
1194                      size_t room);
1195
1196 /** Returns raw data from the RADIUS packet, for a given attribute. \ingroup attr
1197  *
1198  *  This function can be called repeatedly to find all instances of a
1199  *  given attribute.  The first time it is called, the "start"
1200  *  parameter should be zero.  If the function returns a non-zero
1201  *  positive number, it means that there *may* be more attributes
1202  *  available.  The returned value should be then passed via the
1203  *  "start" option in any subsequent calls to the function.
1204  *
1205  *  This function should be called by an application when it wants
1206  *  access to data which is not in the pre-defined dictionaries.
1207  *
1208  * @param[in] packet   The packet containing the attribute.
1209  * @param[in] start    Where in the packet we start searching for the attribute.
1210  * @param[in] attr     Value of the attribute to search for
1211  * @param[in] vendor   Value of the vendor (use 0 for IETF attributes)
1212  * @param[out] pdata   Pointer to the data.  If no data was found, the pointer is unchanged.
1213  * @param[out] plength  Length of the data.  If no data was found, the value pointed to is unchanged.
1214  *
1215  * @return <0 for error,
1216  *          0 for "no attribute found, stop searching"
1217  *         >0 offset where the attribute was found.
1218  */
1219 extern ssize_t nr_attr2data(const RADIUS_PACKET *packet, ssize_t start,
1220                              unsigned int attr, unsigned int vendor,
1221                              const uint8_t **pdata, size_t *plength);
1222
1223 /**  Pretty-print the entire ::VALUE_PAIR \ingroup print
1224  *
1225  *  All data is printed in ASCII format.  The data type of "octets" is
1226  *  printed as a hex string (e.g. 0xabcdef01...).  The data type of
1227  *  "ipaddr" is printed as a dotted-quad (e.g. 192.0.2.15).
1228  *
1229  *  The format is "Attribute-Name = value"
1230  *
1231  * @param[out] buffer  Where the printable version of the ::VALUE_PAIR is stored
1232  * @param[in]  bufsize size of the output buffer
1233  * @param[in]  vp      ::VALUE_PAIR to print
1234  * @return   length of data in buffer
1235  */
1236 extern size_t nr_vp_snprintf(char *buffer, size_t bufsize, const VALUE_PAIR *vp);
1237
1238 /**  Pretty-print the VALUE_PAIR::data field \ingroup print
1239  *
1240  *  Prints the value of a ::VALUE_PAIR, without the name or "=" sign.
1241  *
1242  * @param[out] buffer  Where the printable version of the ::VALUE_PAIR is stored
1243  * @param[in]  bufsize size of the output buffer
1244  * @param[in]  vp      ::VALUE_PAIR to print
1245  * @return   length of data in buffer
1246  */
1247 extern size_t nr_vp_snprintf_value(char *buffer, size_t bufsize, const VALUE_PAIR *vp);
1248
1249 /** Prints a list of :VALUE_PAIR structures to the given output. \ingroup print
1250  *
1251  * @param[in] fp   Where to print the results
1252  * @param[in] vps  Linked list of ::VALUE_PAIR to print
1253  */
1254 extern void nr_vp_fprintf_list(FILE *fp, const VALUE_PAIR *vps);
1255
1256 /** Scan a string into a ::VALUE_PAIR.  The counterpart to
1257  * nr_vp_snprintf_value() \ingroup print
1258  *
1259  * @param[in] string  Printable version of the ::VALUE_PAIR
1260  * @param[out] pvp    Newly allocated ::VALUE_PAIR
1261  * @return <0 on error, 0 for success.
1262  */
1263 extern int nr_vp_sscanf(const char *string, VALUE_PAIR **pvp);
1264
1265 /** Scan the data portion of a ::VALUE_PAIR.  The counterpart to
1266  * nr_vp_snprintf_value() \ingroup print
1267  *
1268  * @param[in,out] vp    The ::VALUE_PAIR where the data will be stored
1269  * @param[in]     value The string version of the data to be parsed
1270  * @return             <0 on error, >=0 for the number of characters parsed in value.
1271  */
1272 extern ssize_t nr_vp_sscanf_value(VALUE_PAIR *vp, const char *value);
1273
1274 #if defined(__GNUC__)
1275 # define PRINTF_LIKE(n) __attribute__ ((format(printf, n, n+1)))
1276 # define NEVER_RETURNS __attribute__ ((noreturn))
1277 # define UNUSED __attribute__ ((unused))
1278 # define BLANK_FORMAT " "       /* GCC_LINT whines about empty formats */
1279 #else
1280
1281 /** Macro used to quiet compiler warnings inside of the library. \ingroup build
1282  *
1283  */
1284 # define PRINTF_LIKE(n)
1285
1286 /** Macro used to quiet compiler warnings inside of the library. \ingroup build
1287  *
1288  */
1289 # define NEVER_RETURNS
1290
1291 /** Macro used to quiet compiler warnings inside of the library. \ingroup build
1292  *
1293  */
1294 # define UNUSED
1295
1296 /** Macro used to quiet compiler warnings inside of the library. \ingroup build
1297  *
1298  */
1299 # define BLANK_FORMAT ""
1300 #endif
1301
1302 #endif /* _RADIUS_CLIENT_H_ */