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