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