2 Copyright (c) 2011, Network RADIUS SARL
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.
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.
29 * \brief Main header file.
33 * System-specific header files.
42 #include <netinet/in.h>
46 * Definitions of attributes.
48 #include <networkradius-devel/radius.h>
50 /** \defgroup build Build Helpers
52 * These definitions give the GNU C compiler more information about
53 * the functions being compiled. They are used to either remove
54 * warnings, or to enable better warnings.
57 /** \defgroup custom Portability Functions
59 * These functions and definitions should be modified for your local
60 * system. See the individual definitions for details.
63 /** \defgroup error Error handling
65 * These definitions and routines manage errors.
68 /** \defgroup value_pair Attribute manipulation
70 * These routines manage structures which map to attributes.
73 /**\defgroup dict Dictionary Lookup Functions
75 * \sa doc/dictionaries.txt
77 * The RADIUS dictionaries perform name to number mappings. The names
78 * are used only for administrator convenience, for parsing
79 * configuration files, and printing humanly-readable output. The
80 * numbers are used when encoding data in a packet.
82 * When attributes are decoded from a packet, the numbers are used to
83 * look up the associated name, which is then placed into a data
86 * When the data structures are encoded into a packet, the numbers are
87 * used to create RFC and VSA format attributes.
89 * \attention The definitions, structures, and functions given below
90 * are useful only for implementing "low level" RADIUS
91 * functionality. There is usually no need to refer to them in a
92 * client application. The library should be used at a higher level,
93 * which exposes a much simpler API.
96 /** \defgroup packet Packet manipulation
98 * These routines perform encoding and decoding of RADIUS packets.
101 /** \defgroup print Print / parse functions
103 * These routines convert the internal data structures to a printable
104 * form, or parse them.
107 /** \defgroup id ID allocation and freeing
109 * These routines manage RADIUS ID allocation.
112 /** \defgroup attr Low-level attribute encode/decoding
114 * These routines perform "low level" encoding, decoding, sending, and
115 * reception of RADIUS attributes. They are called by the \ref packet
118 * \attention The structures and functions given below are useful only
119 * for implementing "low level" RADIUS functionality. There is usually
120 * no need to refer to them in a client application. The library
121 * should be used at a higher level, which exposes a much simpler API.
124 /** \defgroup internal Internal support functions.
126 * These functions are required to perform internal or "low-level"
127 * data manipulation. While they are exposed for completeness, they
128 * should not be called by any application.
131 #ifdef PW_EAP_MESSAGE
132 #ifndef PW_MESSAGE_AUTHENTICATOR
133 #error EAP-Message requires Message-Authenticator
137 #ifdef WITHOUT_OPENSSL
139 #error NR_MD5_CTX must be defined
142 #error n_rMD5Init must be defined
145 #error nr_MD5Updyae must be defined
148 #error nr_MD5Final must be defined
150 #ifndef nr_MD5Transform
151 #error nr_MD5Transform must be defined
154 #else /* WITHOUT_OPENSSL */
156 #include <openssl/md5.h>
157 /** Define for compile-time selection of the MD5 functions. Defaults to using the OpenSSL functions. \ingroup custom */
158 #define NR_MD5_CTX MD5_CTX
159 /** Define for compile-time selection of the MD5 functions. Defaults to using the OpenSSL functions. \ingroup custom */
160 #define nr_MD5Init MD5_Init
161 /** Define for compile-time selection of the MD5 functions. Defaults to using the OpenSSL functions. \ingroup custom */
162 #define nr_MD5Update MD5_Update
163 /** Define for compile-time selection of the MD5 functions. Defaults to using the OpenSSL functions. \ingroup custom */
164 #define nr_MD5Final MD5_Final
165 /** Define for compile-time selection of the MD5 functions. Defaults to using the OpenSSL functions. \ingroup custom */
166 #define nr_MD5Transform MD5_Transform
169 #ifndef NR_MAX_PACKET_LEN
170 /** The maximum size of a packet that the library will send or receive. \ingroup custom
172 * The RFC requirement is to handle at least 4K packets. However, if
173 * you expect to only do username/password authentication, this value
174 * can be set to a smaller value, such as 256.
176 * Be warned that any packets larger than this value will be ignored
177 * and silently discarded.
179 #define NR_MAX_PACKET_LEN (4096)
182 #ifndef NR_MAX_ATTRIBUTES
183 /** The maximum number of attributes that the library will allow in a packet. \ingroup custom
185 * Packets which contain more than ::NR_MAX_ATTRIBUTES will generate
186 * an error. This value is configurable because there may be a need
187 * to accept a large mumber of attributes.
189 * This value is ignored when packets are sent. The library will
190 * send as many attributes as it is told to send.
192 #define NR_MAX_ATTRIBUTES (200)
195 #undef NR_MAX_PACKET_CODE
196 /** The maximum RADIUS_PACKET::code which we can accept. \ingroup dict
198 * \attention This should not be changed, as it is used by other
199 * structures such as ::nr_packet_codes.
201 #define NR_MAX_PACKET_CODE PW_COA_NAK
203 /** The maximum vendor number which is permitted. \ingroup dict
205 * The RFCs require that the Vendor Id or Private Enterprise Number
206 * be encoded as 32 bits, with the upper 8 bits being zero.
208 #define NR_MAX_VENDOR (1 << 24)
210 /** The maximum length of a RADIUS attribute.
212 * The RFCs require that a RADIUS attribute transport no more than
213 * 253 octets of data. We add an extra byte for a trailing NUL, so
214 * that the VALUE_PAIR::vp_strvalue field can be handled as a C
217 #define MAX_STRING_LEN (254)
219 /** Data Type Definitions. \ingroup dict
221 typedef enum nr_attr_type_t {
222 NR_TYPE_INVALID = 0, /**< Invalid data type */
223 NR_TYPE_STRING, /**< printable-text */
224 NR_TYPE_INTEGER, /**< a 32-bit unsigned integer */
225 NR_TYPE_IPADDR, /**< an IPv4 address */
226 NR_TYPE_DATE, /**< a 32-bit date, of seconds since January 1, 1970 */
227 NR_TYPE_OCTETS, /**< a sequence of binary octets */
228 NR_TYPE_IFID, /**< an Interface Id */
229 NR_TYPE_IPV6ADDR, /**< an IPv6 address */
230 NR_TYPE_IPV6PREFIX, /**< an IPv6 prefix */
231 NR_TYPE_BYTE, /**< an 8-bit integer */
232 NR_TYPE_SHORT, /**< a 16-bit integer */
235 #define PW_ACCESS_REQUEST 1
236 #define PW_ACCESS_ACCEPT 2
237 #define PW_ACCESS_REJECT 3
238 #define PW_ACCOUNTING_REQUEST 4
239 #define PW_ACCOUNTING_RESPONSE 5
240 #define PW_ACCOUNTING_STATUS 6
241 #define PW_PASSWORD_REQUEST 7
242 #define PW_PASSWORD_ACK 8
243 #define PW_PASSWORD_REJECT 9
244 #define PW_ACCOUNTING_MESSAGE 10
245 #define PW_ACCESS_CHALLENGE 11
246 #define PW_STATUS_SERVER 12
247 #define PW_STATUS_CLIENT 13
248 #define PW_DISCONNECT_REQUEST 40
249 #define PW_DISCONNECT_ACK 41
250 #define PW_DISCONNECT_NAK 42
251 #define PW_COA_REQUEST 43
252 #define PW_COA_ACK 44
253 #define PW_COA_NAK 45
255 /** Error codes \ingroup error
257 * The numerical value of these definitions may change from version
258 * to version of the library.
260 typedef enum nr_error_t {
261 /** Invalid argument */
262 NR_ERR_INVALID_ARG = 1,
263 /** Insufficient data to decode the packet */
264 NR_ERR_PACKET_TOO_SMALL,
265 /** The packet header says it is larger than the received data */
266 NR_ERR_PACKET_TOO_LARGE,
267 /** the attribute overflows the packet */
268 NR_ERR_ATTR_OVERFLOW,
269 /** the attribute header "length" field is too small */
270 NR_ERR_ATTR_TOO_SMALL,
271 /** the attribute is more than 256 octets long */
272 NR_ERR_ATTR_TOO_LARGE,
273 /** the attribute is unknown */
275 /** the attribute name is improperly formatted */
276 NR_ERR_ATTR_BAD_NAME,
277 /** the attribute value could not be parsed */
278 NR_ERR_ATTR_VALUE_MALFORMED,
279 /** the attribute "type" is invalid */
281 /** the packet has too many attributes */
282 NR_ERR_TOO_MANY_ATTRS,
283 /** the attribute has an unsupported data type */
284 NR_ERR_ATTR_TYPE_UNKNOWN,
285 /** the Message-Authenticator has the wrong length */
287 /** the Message-Authenticator is wrong */
288 NR_ERR_MSG_AUTH_WRONG,
289 /** we need a request packet to calculate something in the response */
290 NR_ERR_REQUEST_REQUIRED,
291 /** the request code is unsupported */
292 NR_ERR_REQUEST_CODE_INVALID,
293 /** the Authentication Vector is wrong */
294 NR_ERR_AUTH_VECTOR_WRONG,
295 /** the response code is unsupported */
296 NR_ERR_RESPONSE_CODE_INVALID,
297 /** the response ID field is invalid */
298 NR_ERR_RESPONSE_ID_INVALID,
299 /** the response is not from the correct source IP/port */
300 NR_ERR_RESPONSE_SRC_INVALID,
301 /** Look at "errno" for the error */
303 /** We cannot encode the packet because of invalid arguments */
304 NR_ERR_NO_PACKET_DATA,
305 /** the vendor is unknown */
306 NR_ERR_VENDOR_UNKNOWN,
307 /** an internal sanity check failed */
308 NR_ERR_INTERNAL_FAILURE,
309 /** the caller requested an unsupported featuer */
311 /** we were unable to allocate memory */
313 /** Resource is in use */
317 #define TAG_VALID(x) ((x) < 0x20)
319 /** The attribute is not encrypted. */
320 #define FLAG_ENCRYPT_NONE (0)
322 /** The attribute is encrypted using the RFC 2865 User-Password method */
323 #define FLAG_ENCRYPT_USER_PASSWORD (1)
325 /** The attribute is encrypted using the RFC 2868 Tunnel-Password method */
326 #define FLAG_ENCRYPT_TUNNEL_PASSWORD (2)
328 /** A set of flags which determine how the attribute should be handled.
330 * Most attributes are "normal", and do not require special handling.
331 * However, some require "encryption", tagging, or have other special
332 * formats. This structure contains the various options for the
335 typedef struct attr_flags {
336 unsigned int has_tag : 1; /**< Attribute has an RFC 2868 tag */
337 unsigned int unknown : 1; /**< Attribute is unknown */
339 unsigned int has_tlv : 1; /* has sub attributes */
340 unsigned int is_tlv : 1; /* is a sub attribute */
342 #ifdef VENDOR_EXTENDED
343 unsigned int extended : 1; /* extended attribute */
344 unsigned int extended_flags : 1; /* with flag */
345 unsigned int evs : 1; /* extended VSA */
348 uint8_t encrypt; /**< Attribute encryption method */
349 uint8_t length; /**< The expected length of the attribute */
353 /** Defines an dictionary mapping for an attribute. \ingroup dict
355 * The RADIUS dictionaries map humanly readable names to protocol
356 * numbers. The protocol numbers are used to encode/decode the
357 * attributes in a packet.
359 typedef struct nr_dict_attr {
360 unsigned int attr; /**< Attribute number */
361 nr_attr_type_t type; /**< Data type */
362 unsigned int vendor; /**< Vendor-Id number */
364 const char *name; /**< Printable name */
367 /** Defines a dictionary mapping for a named enumeration. \ingroup dict
369 * This structure is currently not used.
371 typedef struct nr_dict_value {
372 const DICT_ATTR *da; /**< pointer to a ::DICT_ATTR */
373 int value; /**< enumerated value */
374 char name[1]; /**< printable name */
377 /** Defines an dictionary mapping for a vendor. \ingroup dict
379 * The RADIUS dictionaries map humanly readable vendor names to a
380 * Vendor-Id (or Private Enterprise Code) assigned by IANA. The
381 * Vendor-Id is used to encode/decode Vendor-Specific attributes in a
384 typedef struct nr_dict_vendor {
385 unsigned int vendor; /**< Vendor Private Enterprise Code */
386 size_t type; /**< size of Vendor-Type field */
387 size_t length; /**< size of Vendor-Length field */
388 const char *name; /**< Printable name */
391 /** Union holding all possible types of data for a ::VALUE_PAIR. \ingroup value_pair
394 typedef union value_pair_data {
395 char strvalue[MAX_STRING_LEN]; /* +1 for NUL */
397 struct in_addr ipaddr;
398 struct in6_addr ipv6addr;
401 #ifdef NR_TYPE_SIGNED
404 #ifdef NR_TYPE_ABINARY
407 uint8_t ifid[8]; /* struct? */
408 uint8_t ipv6prefix[18]; /* struct? */
415 /** C structure version of a RADIUS attribute. \ingroup value_pair
417 * The library APIs use this structure to avoid depending on the
418 * details of the protocol.
420 typedef struct value_pair {
421 const DICT_ATTR *da; /**< dictionary definition */
422 size_t length; /**< number of octets in the data */
423 int tag; /**< tag value if da->flags.has_tag */
424 struct value_pair *next; /**< enables a linked list of values */
425 VALUE_PAIR_DATA data; /**< the data of the attribute */
427 #define vp_strvalue data.strvalue
428 #define vp_octets data.octets
429 #define vp_ipv6addr data.ipv6addr
430 #define vp_ifid data.ifid
431 #define vp_ipv6prefix data.ipv6prefix
432 #define vp_ipaddr data.ipaddr.s_addr
433 #define vp_date data.integer
434 #define vp_integer data.integer
435 #ifdef NR_TYPE_ABINARY
436 #define vp_filter data.filter
439 #define vp_ether data.ether
441 #ifdef NR_TYPE_SIGNED
442 #define vp_signed data.sinteger
445 #define vp_tlv data.tlv
449 #define NR_ATTR_MAX_TLV (4)
450 extern const int nr_attr_shift[NR_ATTR_MAX_TLV];
451 extern const int nr_attr_mask[NR_ATTR_MAX_TLV];
452 extern const unsigned int nr_attr_max_tlv;
455 /** A structure which describes a RADIUS packet. \ingroup packet
457 * In general, it should not be necessary to refererence the elements
460 typedef struct radius_packet {
461 int sockfd; /** The socket descriptor */
462 struct sockaddr_storage src; /**< The packet source address */
463 struct sockaddr_storage dst; /**< the packet destination address */
464 const char *secret; /**< The shared secret */
465 size_t sizeof_secret; /**< Length of the shared secret */
466 unsigned int code; /**< The RADIUS Packet Code */
467 int id; /**< The RADIUS Packet Id */
468 size_t length; /**< The RADIUS Packet Length. This will be no larger than RADIUS_PACKET::sizeof_data */
469 uint8_t vector[16]; /**< A copy of the authentication vector */
470 int flags; /**< Internal flags. Do not modify this field. */
471 int attempts; /**< The number of transmission attempt */
472 uint8_t *data; /**< The raw packet data */
473 size_t sizeof_data; /**< size of the data buffer */
474 VALUE_PAIR *vps; /**< linked list of ::VALUE_PAIR */
477 #define NR_PACKET_ENCODED (1 << 0)
478 #define NR_PACKET_HEADER (1 << 1)
479 #define NR_PACKET_SIGNED (1 << 2)
480 #define NR_PACKET_OK (1 << 3)
481 #define NR_PACKET_VERIFIED (1 << 4)
482 #define NR_PACKET_DECODED (1 << 5)
485 /** Track packets sent to a server. \ingroup id
487 * This data structure tracks Identifiers which are used to
488 * communicate with a particular destination server. The application
489 * should call nr_server_init() to initialize it. If necessary, the
490 * application should then call nr_server_set_ipv4() to open an IPv4
491 * socket to the server.
493 * If the RADIUS packets are being transported over an encapsulation
494 * layer (e.g. RADIUS over TLS), then nr_server_set_ipv4() does not
495 * need to be called. The ::nr_server_t structure should instead be
496 * associated wih the TLS session / socket.
498 typedef struct nr_server_t {
499 int sockfd; /**< socket for sending packets */
500 int code; /**< default value for the Code */
502 struct sockaddr_storage src; /**< Source address of the packet */
503 struct sockaddr_storage dst; /**< Destination address of the packet */
505 /** The shared secret.
507 * See also nr_packet_send() and nr_packet_recv().
511 /** The length of the shared secret.
513 * See also nr_packet_send() and nr_packet_recv().
515 size_t sizeof_secret;
517 int used; /**< Number of used IDs */
519 void *free_list; /**< For managing packets */
521 RADIUS_PACKET *ids[256]; /**< Pointers to "in flight" packets */
525 /** Return a printable error message. \ingroup error
527 * This function returns a string describing the last error that
528 * occurred. These messages are intended for developers, and are not
529 * suitable for display to an end user. The application using this
530 * library should instead produce a "summary" message when an error
531 * occurs. e.g. "Failed to receive a response", is better than
532 * messages produced by this function, which contain text like
533 * "invalid response authentication vector". The first is
534 * understandable, the second is not.
536 * @param[in] error The error code (can be less than zero)
537 * @return A printable string describing the error.
539 extern const char *nr_strerror(int error);
541 /** Allocate a ::VALUE_PAIR which refers to a ::DICT_ATTR. \ingroup value_pair
543 * This returned ::VALUE_PAIR has no data associated with it. The
544 * nr_vp_set_data() function must be called before placing the
545 * ::VALUE_PAIR in a ::RADIUS_PACKET.
547 * @param[in] da The ::DICT_ATTR associated with the ::VALUE_PAIR
548 * @return The created ::VALUE_PAIR, or NULL on error.
550 extern VALUE_PAIR *nr_vp_alloc(const DICT_ATTR *da);
552 /** Free a ::VALUE_PAIR. \ingroup value_pair
554 * This function frees the ::VALUE_PAIR, and sets the head pointer to NULL.
555 * If head refers to a ::VALUE_PAIR list, then all of the structures in the
558 * @param[in,out] head The pointer to a ::VALUE_PAIR, or a ::VALUE_PAIR list.
560 extern void nr_vp_free(VALUE_PAIR **head);
562 /** Initializes a ::VALUE_PAIR from a ::DICT_ATTR \ingroup value_pair
564 * This function assumes that the ::VALUE_PAIR points to existing
565 * and writable memory.
567 * @param[in,out] vp The ::VALUE_PAIR to be initialized
568 * @param[in] da The ::DICT_ATTR used to initialize the ::VALUE_PAIR
569 * @return The initialized ::VALUE_PAIR, or NULL on error.
571 extern VALUE_PAIR *nr_vp_init(VALUE_PAIR *vp, const DICT_ATTR *da);
573 /** Allocate a ::VALUE_PAIR which refers to an unknown attribute. \ingroup value_pair
575 * It is used when an attribute is received, and that attribute does
576 * not exist in the dictionaries.
578 * The returned ::VALUE_PAIR has no data (i.e. VALUE_PAIR::length is
579 * zero). The nr_vp_set_data() function must be called before
580 * placing the ::VALUE_PAIR in a ::RADIUS_PACKET.
582 * @param[in] attr The attribute number, 0..2^16
583 * @param[in] vendor The vendor number, 0..2^16
584 * @return The created ::VALUE_PAIR, or NULL on error.
586 extern VALUE_PAIR *nr_vp_alloc_raw(unsigned int attr, unsigned int vendor);
588 /** Set the data associated with a previously allocated ::VALUE_PAIR. \ingroup value_pair
590 * If this function succeeds, VALUE_PAIR::length is no longer zero,
591 * and the structure contains the data.
593 * @param[in,out] vp The ::VALUE_PAIR to update
594 * @param[in] data Data to set inside of the ::VALUE_PAIR
595 * @param[in] data_len Length of the data field
596 * @return <0 on error, 0 for "data was truncated"
597 * >0 for "data successfully added"
599 extern int nr_vp_set_data(VALUE_PAIR *vp, const void *data, size_t data_len);
601 /** Create a ::VALUE_PAIR and set its data. \ingroup value_pair
603 * @param[in] attr The attribute number of the ::VALUE_PAIR to create
604 * @param[in] vendor The vendor number of the ::VALUE_PAIR to create
605 * @param[in] data Data to set inside of the ::VALUE_PAIR
606 * @param[in] data_len Length of the data field
607 * @return The created ::VALUE_PAIR, or NULL on error.
609 extern VALUE_PAIR *nr_vp_create(int attr, int vendor, const void *data,
612 /** Append a ::VALUE_PAIR to the end of a ::VALUE_PAIR list. \ingroup value_pair
614 * @param[in,out] head The head of the ::VALUE_PAIR list. May not be NULL.
615 * @param[in] vp The ::VALUE_PAIR to append to the list.
617 extern void nr_vps_append(VALUE_PAIR **head, VALUE_PAIR *vp);
619 /** Search a ::VALUE_PAIR list for one of a given number. \ingroup value_pair
621 * @param[in] head The head of the ::VALUE_PAIR list to search.
622 * @param[in] attr The attribute number of the ::VALUE_PAIR to find
623 * @param[in] vendor The vendor number of the ::VALUE_PAIR to find
624 * @return The found ::VALUE_PAIR, or NULL if it was not found.
626 extern VALUE_PAIR *nr_vps_find(VALUE_PAIR *head,
627 unsigned int attr, unsigned int vendor);
629 /** Look up an attribute in the dictionaries. \ingroup dict
631 * The dictionary mapping contains information about the attribute,
632 * such as printable name, data type (ipaddr, integer, etc), and
633 * various other things used to encode/decode the attribute in a
636 * \attention There is usually no need to call this function. Use
637 * the NR_DA_* definitions instead.
639 * @param[in] attr Value of the attribute
640 * @param[in] vendor Value of the vendor
641 * @return NULL for "not found", or a pointer to the attribute mapping.
643 extern const DICT_ATTR *nr_dict_attr_byvalue(unsigned int attr,
644 unsigned int vendor);
646 /** Look up an attribute in the dictionaries. \ingroup dict
648 * The dictionary mapping contains information about the attribute,
649 * such as printable name, data type (ipaddr, integer, etc), and
650 * various other things used to encode/decode the attribute in a
653 * \attention There is usually no need to call this function.
655 * @param[in] name Name of the attribute
656 * @return NULL for "not found", or a pointer to the attribute mapping.
658 extern const DICT_ATTR *nr_dict_attr_byname(const char *name);
660 /** Converts raw data to a ::DICT_ATTR structure. \ingroup dict
662 * It is called when the library is asked to decode an attribute
663 * which is not in the pre-defined dictionaries.
665 * \attention There is usually no need to call this function.
667 * @param[in,out] da The ::DICT_ATTR structure to initialize
668 * @param[in] attr The attribute number
669 * @param[in] vendor The vendor number
670 * @param[in] buffer The buffer where the name of the attribute is stored
671 * @param[in] bufsize Size of the buffer
672 * @return <0 for error, 0 for success
674 extern int nr_dict_attr_2struct(DICT_ATTR *da,
675 unsigned int attr, unsigned int vendor,
676 char *buffer, size_t bufsize);
678 /** Unused. \ngroup dict
681 extern const DICT_VALUE *nr_dict_value_byattr(unsigned int attr,
685 /** Unused. \ngroup dict
688 const DICT_VALUE *nr_dict_value_byname(unsigned int attr,
692 /** Look up a vendor in the dictionaries. \ingroup dict
694 * The dictionary mapping contains information about the vendor, such
695 * as printable name, VSA encoding method, etc.
697 * \attention There is usually no need to call this function.
698 * Applications do not need access to low-level RADIUS protocol
701 * @param[in] name Name of the vendor.
702 * @return NULL for "not found", or a pointer to the vendor mapping.
704 extern int nr_dict_vendor_byname(const char *name);
706 /** Look up an vendor in the dictionaries. \ingroup dict
708 * The dictionary mapping contains information about the vendor, such
709 * as printable name, VSA encoding method, etc.
711 * \attention There is usually no need to call this function.
713 * @param[in] vendor Vendor-Id (or Private Enterprise code) for the vendor.
714 * @return NULL for "not found", or a pointer to the vendor mapping.
716 extern const DICT_VENDOR *nr_dict_vendor_byvalue(unsigned int vendor);
718 /** Static array of known vendors. \ingroup dict
720 * \attention This structure should only be accessed by internal RADIUS library
723 extern const DICT_VENDOR nr_dict_vendors[];
725 /** The number of attribute definitions in the dictionary. \ingroup dict
727 * This number is guaranteed to be at least 256, for speed.
729 * \attention This variable should only be accessed by internal RADIUS library
732 extern const int nr_dict_num_attrs;
734 /** The list of attribute definitions. \ingroup dict
736 * The "standard" RFC attributes are located in the first 256
737 * entries. Standard attributes without a dictionary definition are
738 * given an empty entry.
740 * The attributes are orderd by (vendor, attribute), in increasing
741 * order. This allows the dictionary lookups to find attributes by a
744 * \attention This variable should only be accessed by internal RADIUS library
747 extern const DICT_ATTR nr_dict_attrs[];
749 /** The number of attributes with names. \ingroup dict
751 * \attention This variable should only be accessed by internal RADIUS library
754 extern const int nr_dict_num_names;
756 /** The list of attribute definitions, organized by name. \ingroup dict
758 * The attributes are orderd by name (case insensitive), in
759 * increasing order. This allows the dictionary lookups to find
760 * attributes by a binary search.
762 * \attention This variable should only be accessed by internal RADIUS library
765 extern const DICT_ATTR const *nr_dict_attr_names[];
767 /** Static array containing names the RADIUS_PACKET::code field. \ingroup dict
769 * The names are hard-coded and not in any dictionary because they do
772 * The names are exported because they may be useful in your
773 * application. Packet codes which are not handled by the library
774 * have NULL for their names.
776 extern const char *nr_packet_codes[NR_MAX_PACKET_CODE + 1];
778 /** Verifies that a packet is "well formed". \ingroup packet
780 * This function performs basic validation to see if the packet is
781 * well formed. It is automatically called by nr_packet_decode().
783 * @param[in] packet A pointer to the ::RADIUS_PACKET data.
784 * @return <0 means malformed, >= 0 means well-formed.
786 extern int nr_packet_ok(RADIUS_PACKET *packet);
788 /** Verifies that a packet is "well formed". \ingroup packet
790 * This function performs basic validation to see if the packet is
791 * well formed. You should normally use nr_packet_ok() instead of
794 * @param[in] data A pointer to the raw packet data.
795 * @param[in] sizeof_data The length of the raw packet data
796 * @return <0 means malformed, >= 0 means well-formed.
798 extern int nr_packet_ok_raw(const uint8_t *data, size_t sizeof_data);
800 /** Encodes a packet. \ingroup packet
802 * This function encodes a packet using the fields of the
803 * ::RADIUS_PACKET structure. The RADIUS_PACKET::code and
804 * RADIUS_PACKET::id fields are used to fill in the relevant fields
805 * of the raw (encoded) packet. The RADIUS_PACKET::vps list is
806 * walked to encode the attributes. The packet is signed, if
809 * The raw packet is placed into the RADIUS_PACKET::data field, up to
810 * RADIUS_PACKET::sizeof_data bytes. the RADIUS_PACKET::length field
811 * is updated with the length of the raw packet. This field is
812 * always less than, or equal to, the RADIUS_PACKET::size_data field.
813 * If there is insufficient room to store all of the attributes, then
814 * some attributes are silently discarded.
816 * The RADIUS_PACKET::vector field is either calculated as part of
817 * the signing process, or is initialized by this function to be a
818 * random sequence of bytes. That field should therefore be left
819 * alone by the caller.
821 * When the encoding has been successful, it sets the
822 * RADIUS_PACKET::encoded field to non-zero.
824 * In addition, all required attribute "encryption" is performed.
826 * User-Password. The vp_strvalue field is assumed to contain the
827 * "clear-text" version of the password. The encrypted version is
828 * calculated, and placed in the packet.
830 * CHAP-Password. The vp_strvalue field is assumed to contain the
831 * "clear-text" version of the password. The encrypted version is
832 * calculated, and placed in the packet. If the RADIUS_PACKET::vps
833 * list contains a CHAP-Challenge attribute, it is used. Otherwise
834 * the RADIUS_PACKET::vector field is used a the challenge.
836 * Message-Authenticator. The contents of the Message-Authenticator
837 * in the RADIUS_PACKET::vps list are ignored. Instead, a
838 * "place-holder" is put into the packt. Tthe correct value is
839 * calculated and placed into the packet by nr_packet_sign().
841 * The RADIUS_PACKET::vps list is left untouched by this function,
842 * even when attribute encryption or signing is performed. Any
843 * VALUE_PAIR structures can therefore be taken from static "const"
846 * @param[in] packet The RADIUS packet to encode.
847 * @param[in] original The original request, when encoding a response.
848 * @return <0 on error, >= 0 on success.
850 extern int nr_packet_encode(RADIUS_PACKET *packet, const RADIUS_PACKET *original);
852 /** Decodes a packet. \ingroup packet
854 * This function decodes a packet from the RADIUS_PACKET::data field
855 * into a sequence of ::VALUE_PAIR structures in the
856 * RADIUS_PACKET::vps list.
858 * @param[in] packet The RADIUS packet to decode.
859 * @param[in] original The original request, when decoding a response.
860 * @return <0 on error, >= 0 on success.
862 extern int nr_packet_decode(RADIUS_PACKET *packet, const RADIUS_PACKET *original);
864 /** Signs a packet so that it can be sent. \ingroup packet
866 * This function calculates the Message-Authenticator (if required),
867 * and signs the packet.
869 * @param[in] packet The RADIUS packet to sign.
870 * @param[in] original The original request, when signing a response.
871 * @return <0 on error, >= 0 on success.
873 extern int nr_packet_sign(RADIUS_PACKET *packet, const RADIUS_PACKET *original);
875 /** Verifies that a packet is well-formed and contains the correct signature. \ingroup packet
877 * If "original" is specified, it also verifies that the packet is a
878 * response to the original request, and that it has the correct
881 * @param[in] packet The RADIUS packet to verify.
882 * @param[in] original The original request, when verifying a response.
883 * @return <0 on error, >= 0 on success.
885 extern int nr_packet_verify(RADIUS_PACKET *packet,
886 const RADIUS_PACKET *original);
888 /** Pretty-prints a hex dump of a RADIUS packet. \ingroup packet print
890 * This function is available only in debugging builds of the
891 * library. It is useful during development, but should not be used
892 * in a production system.
894 * The packet headers are printed individually, and each attribute is
895 * printed as "type length data..."
897 * @param[in] packet The RADIUS packet to print
899 extern void nr_packet_print_hex(RADIUS_PACKET *packet);
902 /** Return the given number of random bytes. \ingroup custom
904 * This function should be replaced by one that is specific to your
907 * This is a wrapper function which enables the library to be more
910 * @param[in] data Location where the random bytes will be stored
911 * @param[in] data_len Number of bytes to store
912 * @return <0 on error, or the total number of bytes stored.
914 extern ssize_t nr_rand_bytes(uint8_t *data, size_t data_len);
916 /** Return a random 32-bit integer. \ingroup custom
918 * This function should be replaced by one that is specific to your
919 * system. The version supplied here just calls nr_rand_bytes() each
920 * time, which is slow.
922 * This is a wrapper function which enables the library to be more
925 * @return An unsigned 32-bit random integer.
927 extern uint32_t nr_rand(void);
929 /** Add a time to the given ::struct timeval. \ingroup custom
931 * This is a wrapper function which enables the library to be more
934 * @param[in,out] t The timeval to which the time is added.
935 * @param[in] seconds Time in seconds to add
936 * @param[in] usec Time in microseconds to add
938 extern void nr_timeval_add(struct timeval *t, unsigned int seconds,
941 /** Compare two times. \ingroup custom
943 * This is a wrapper function which enables the library to be more
946 * @param[in] a One timeval
947 * @param[in] b Another one
950 extern int nr_timeval_cmp(const struct timeval *a, const struct timeval *b);
952 /** Initializes an ::nr_server_t. \ingroup id
954 * @param[in,ut] s The ::nr_server_t to initialize
955 * @param[in] code The packet code used for packets sent to this server
956 * @param[in] secret The shared secret used for packet sent to this server
957 * @return <0 for error, >= 0 for success
959 extern int nr_server_init(nr_server_t *s, int code, const char *secret);
961 /** Closes an ::nr_server_t data structure. \ingroup id
963 * Ensures that all IDs are free, and closes the socket.
965 * @param[in] s The server structure to close.
966 * @return <0 for error, 0 for success
968 extern int nr_server_close(const nr_server_t *s);
970 /** Allocate a RADIUS_PACKET::id value for sending a packet to a server. \ingroup id
972 * This function allocates a RADIUS_PACKET::id from the ::nr_server_t
973 * structure. It also fills in the RADIUS_PACKET::sockfd,
974 * RADIUS_PACKET::code, and RADIUS_PACKET::dst fields.
976 * @param[in] s The server structure which tracks the ID
977 * @param[in] packet The packet which needs an ID
978 * @return <0 for error, 0 for success
980 extern int nr_server_id_alloc(nr_server_t *id, RADIUS_PACKET *packet);
982 /** Re-allocate a RADIUS_PACKET::id value for sending a packet to a server. \ingroup id
984 * It is used when retransmitting an Accounting-Request packet to a
985 * server, after updating the Acct-Delay-Time field. The "realloc"
986 * name means that the new ID is allocated, and is guaranteed to be
987 * different from the old one.
989 * @param[in] s The server structure which tracks the ID
990 * @param[in] packet The packet which needs a new ID
991 * @return <0 for error, 0 for success
993 extern int nr_server_id_realloc(nr_server_t *id, RADIUS_PACKET *packet);
995 /** Free a RADIUS_PACKET::id value after sending a packet to a server. \ingroup id
997 * @param[in] s The server structure which tracks the ID
998 * @param[in] packet The packet which has an ID, and wants to free it
999 * @return <0 for error, 0 for success
1001 extern int nr_server_id_free(nr_server_t *id, RADIUS_PACKET *packet);
1004 /** Allocates a packet using malloc(), and initializes it. \ingroup id
1006 * @param[in] s The server structure
1007 * @param[in,out] packet_p Pointer to the ::RADIUS_PACKET to be allocated
1008 * @return <0 for error, 0 for success
1010 extern int nr_server_packet_alloc(const nr_server_t *s, RADIUS_PACKET **packet_p);
1012 /** Record a humanly readable error message. \ingroup error
1014 * \attention This structure should only be accessed by internal
1015 * RADIUS library functions.
1017 * @param[in] fmt The format to use.
1019 extern void nr_strerror_printf(const char *fmt, ...);
1022 #define nr_debug_error nr_strerror_printf /** \ingroup error */
1024 #define nr_debug_error if (0) nr_strerror_printf
1027 /** Encrypts or decrypts a User-Password attribute. \ingroup internal
1029 * \attention This structure should only be accessed by internal
1030 * RADIUS library functions.
1032 * @param[out] output Buffer where the password is stored
1033 * @param[out] outlen Size of the output buffer
1034 * @param[in] input Input buffer with password
1035 * @param[in] inlen Length of the input buffer
1036 * @param[in] secret The shared secret
1037 * @param[in] vector Authentication vector
1038 * @return <0 on error, or the length of data in "output"
1040 extern ssize_t nr_password_encrypt(uint8_t *output, size_t outlen,
1041 const uint8_t *input, size_t inlen,
1042 const char *secret, const uint8_t *vector);
1044 /** Encrypts a Tunnel-Password attribute. \ingroup internal
1046 * \attention This structure should only be accessed by internal
1047 * RADIUS library functions.
1049 * @param[out] output Buffer where the password is stored
1050 * @param[out] outlen Size of the output buffer
1051 * @param[in] input Input buffer with password
1052 * @param[in] inlen Length of the input buffer
1053 * @param[in] secret The shared secret
1054 * @param[in] vector Authentication vector
1055 * @return <0 on error, or the length of data in "output"
1057 extern ssize_t nr_tunnelpw_encrypt(uint8_t *output, size_t outlen,
1058 const uint8_t *input, size_t inlen,
1059 const char *secret, const uint8_t *vector);
1061 /** Decrypts a Tunnel-Password attribute. \ingroup internal
1064 * \attention This structure should only be accessed by internal
1065 * RADIUS library functions.
1067 * @param[out] output Buffer where the password is stored
1068 * @param[out] outlen Size of the output buffer
1069 * @param[in] input Input buffer with password
1070 * @param[in] inlen Length of the input buffer
1071 * @param[in] secret The shared secret
1072 * @param[in] vector Authentication vector
1073 * @return <0 on error, or the length of data in "output"
1075 extern ssize_t nr_tunnelpw_decrypt(uint8_t *output, size_t outlen,
1076 const uint8_t *input, size_t inlen,
1077 const char *secret, const uint8_t *vector);
1079 /** Calculates an HMAC-MD5. \ingroup internal
1081 * @param[in] data Data to be hashed
1082 * @param[in] data_len Length of data to be hashed
1083 * @param[in] key Key for the HMAC
1084 * @param[in] key_len Length of the key
1085 * @param[out] digest
1087 extern void nr_hmac_md5(const uint8_t *data, size_t data_len,
1088 const uint8_t *key, size_t key_len,
1089 uint8_t digest[16]);
1091 /** Checks if a TLV is properly formatted. \ingroup internal
1093 * \attention This structure should only be accessed by internal
1094 * RADIUS library functions.
1096 * @param[in] data Data to check
1097 * @param[in] length Length of the data field
1098 * @param[in] dv_type Length of the TLV "type" field
1099 * @param[in] dv_length Length of the TLV "length" field
1100 * @return <0 on error, 0 for "TLV is OK"
1102 extern int nr_tlv_ok(const uint8_t *data, size_t length,
1103 size_t dv_type, size_t dv_length);
1105 /** A callback function used by nr_packet_walk(). \ingroup packet
1107 * The function should return 0 on success (i.e. keep walking), and
1108 * otherwise a negative number indicating an error code
1109 * (::nr_error_t). That negative number will be used as the return
1110 * code for nr_packet_walk().
1112 typedef int (*nr_packet_walk_func_t)(void *, const DICT_ATTR *, const uint8_t *, size_t);
1114 /** Walks over all attributes in a packet. \ingroup packet
1116 * This function is an iterator which calls a user-supplied callback
1117 * function for each attribute in the packet. It should be used
1118 * instead of manually walking over the attributes. There are a
1119 * number of odd corner cases when handling Vendor-Specific
1120 * attributes, and it is easy to get those corner cases wrong.
1122 * This function iterates over *all* attributes, including nested
1123 * VSAs. That is its main value.
1125 * Encrypted attributes such as User-Password are not decrypted.
1127 * @param[in] packet The packet containing the data
1128 * @param[in] ctx A user-supplied context. May be NULL
1129 * @param[in] callback The callback function where the information is passed.
1131 * @return <0 for error,
1134 extern int nr_packet_walk(RADIUS_PACKET *packet, void *ctx,
1135 nr_packet_walk_func_t callback);
1137 /** Initialize a packet
1139 * If original is specified, the packet is initialized as a response
1140 * to the original request.
1142 * @param[in,out] packet The packet to initialize
1143 * @param[in] original The original request (if any) to use as a template
1144 * @param[in] secret Shared secret
1145 * @param[in] code RADIUS Code field.
1146 * @param[in] data Buffer where packets will be stored (RADIUS_PACKET::data)
1147 * @param[in] sizeof_data Size of buffer (RADIUS_PACKET::sizeof_data)
1148 * @return <0 on error, 0 for success.
1150 extern int nr_packet_init(RADIUS_PACKET *packet, const RADIUS_PACKET *original,
1151 const char *secret, int code,
1152 void *data, size_t sizeof_data);
1154 /** Add one attribute to the packet.
1156 * This function can be used to add "raw" data to a packet. It
1157 * allows the caller to extend the RADIUS packet without using a
1158 * ::VALUE_PAIR data structure.
1160 * Some attributes are handled specially by this function.
1162 * EAP-Message. This attribute is automatically split into 253-octet
1165 * User-Password, CHAP-Password, and Message-Authenticator. These
1166 * attributes are automatically encrypted, as is done by
1167 * nr_packet_encode().
1169 * @param[in] packet The packet to edit
1170 * @param[in] original The original request (if any)
1171 * @param[in] da Pointer to the attribute definition
1172 * @param[in] data Data to append to the packet
1173 * @param[in] data_len Length of data to append to the packet
1175 * @return <0 for error, >= 0 for "successfully appended data"
1176 * The function returns the number of octets appended to the packet.
1178 extern ssize_t nr_packet_attr_append(RADIUS_PACKET *packet,
1179 const RADIUS_PACKET *original,
1180 const DICT_ATTR *da,
1181 const void *data, size_t data_len);
1184 /** Encodes any ::VALUE_PAIR into an attribute. \ingroup attr
1186 * This function can be called for any ::VALUE_PAIR. It will examine
1187 * that structure, and call one of nr_vp2rfc() or nr_vp2vsa() as
1190 * \attention This function should not be called.
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.
1198 * @return <0 for error, or the number of octets used to encode the attribute.
1200 extern ssize_t nr_vp2attr(const RADIUS_PACKET *packet,
1201 const RADIUS_PACKET *original,
1202 const VALUE_PAIR **pvp, uint8_t *data, size_t room);
1204 /** Encodes an RFC "standard" ::VALUE_PAIR into an attribute. \ingroup attr
1206 * \attention This function should not be called.
1208 * @param[in] packet Where to place the encoded attribute.
1209 * @param[in] original The original request (optional), if "packet" is a response
1210 * @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.
1211 * @param[in] data Where the attribute is to be encoded.
1212 * @param[in] room How many octets are available for attribute encoding.
1214 * @return <0 for error, or the number of octets used to encode the attribute.
1216 extern ssize_t nr_vp2rfc(const RADIUS_PACKET *packet,
1217 const RADIUS_PACKET *original,
1218 const VALUE_PAIR **pvp,
1219 uint8_t *data, size_t room);
1221 /** Decodes any attribute into a ::VALUE_PAIR. \ingroup attr
1223 * \attention This function should not be called.
1225 * @param[in] packet The packet containing the attribute to be decoded.
1226 * @param[in] original The original request (optional), if "packet" is a response
1227 * @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.
1228 * @param[in] data Where the attribute is to be encoded.
1229 * @param[in] length How many octets are available for attribute decoding.
1231 * @return <0 for error, or the number of octets used to decode the attribute.
1233 extern ssize_t nr_attr2vp(const RADIUS_PACKET *packet, const RADIUS_PACKET *original,
1234 const uint8_t *data, size_t length,
1237 /** Decodes an RFC "standard" attribute into a ::VALUE_PAIR. \ingroup attr
1239 * \attention This function should not be called.
1241 * @param[in] packet The packet containing the attribute to be decoded.
1242 * @param[in] original The original request (optional), if "packet" is a response
1243 * @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.
1244 * @param[in] data Where the attribute is to be encoded.
1245 * @param[in] length How many octets are available for attribute decoding.
1247 * @return <0 for error, or the number of octets used to decode the attribute.
1249 extern ssize_t nr_attr2vp_rfc(const RADIUS_PACKET *packet,
1250 const RADIUS_PACKET *original,
1251 const uint8_t *data, size_t length,
1254 /** Decodes a Vendor-Specific attribute into a ::VALUE_PAIR. \ingroup attr
1256 * \attention This function should not be called.
1258 * @param[in] packet The packet containing the attribute to be decoded.
1259 * @param[in] original The original request (optional), if "packet" is a response
1260 * @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.
1261 * @param[in] data Where the attribute is to be encoded.
1262 * @param[in] length How many octets are available for attribute decoding.
1264 * @return <0 for error, or the number of octets used to decode the attribute.
1266 extern ssize_t nr_attr2vp_vsa(const RADIUS_PACKET *packet,
1267 const RADIUS_PACKET *original,
1268 const uint8_t *data, size_t length,
1271 /** Decodes an attribute with an unexpected length into a ::VALUE_PAIR. \ingroup attr
1273 * \attention This function should not be called.
1275 * @param[in] packet The packet containing the attribute to be decoded.
1276 * @param[in] original The original request (optional), if "packet" is a response
1277 * @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.
1278 * @param[in] data Where the attribute is to be encoded.
1279 * @param[in] length How many octets are available for attribute decoding.
1281 * @return <0 for error, or the number of octets used to decode the attribute.
1283 extern ssize_t nr_attr2vp_raw(const RADIUS_PACKET *packet,
1284 const RADIUS_PACKET *original,
1285 const uint8_t *data, size_t length,
1288 /** Encodes a Vendor-Specific ::VALUE_PAIR into an attribute.
1290 * \attention This function should not be called.
1292 * @param[in] packet Where to place the encoded attribute.
1293 * @param[in] original The original request (optional), if "packet" is a response
1294 * @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.
1295 * @param[in] data Where the attribute is to be encoded.
1296 * @param[in] room How many octets are available for attribute encoding.
1298 * @return <0 for error, or the number of octets used to encode the attribute.
1300 extern ssize_t nr_vp2vsa(const RADIUS_PACKET *packet, const RADIUS_PACKET *original,
1301 const VALUE_PAIR **pvp, uint8_t *data,
1304 /** Returns raw data from the RADIUS packet, for a given attribute. \ingroup attr
1306 * This function can be called repeatedly to find all instances of a
1307 * given attribute. The first time it is called, the "start"
1308 * parameter should be zero. If the function returns a non-zero
1309 * positive number, it means that there *may* be more attributes
1310 * available. The returned value should be then passed via the
1311 * "start" option in any subsequent calls to the function.
1313 * This function should be called by an application when it wants
1314 * access to data which is not in the pre-defined dictionaries.
1316 * @param[in] packet The packet containing the attribute.
1317 * @param[in] start Where in the packet we start searching for the attribute.
1318 * @param[in] attr Value of the attribute to search for
1319 * @param[in] vendor Value of the vendor (use 0 for IETF attributes)
1320 * @param[out] pdata Pointer to the data. If no data was found, the pointer is unchanged.
1321 * @param[out] plength Length of the data. If no data was found, the value pointed to is unchanged.
1323 * @return <0 for error,
1324 * 0 for "no attribute found, stop searching"
1325 * >0 offset where the attribute was found.
1327 extern ssize_t nr_attr2data(const RADIUS_PACKET *packet, ssize_t start,
1328 unsigned int attr, unsigned int vendor,
1329 const uint8_t **pdata, size_t *plength);
1331 /** Pretty-print the entire ::VALUE_PAIR \ingroup print
1333 * All data is printed in ASCII format. The data type of "octets" is
1334 * printed as a hex string (e.g. 0xabcdef01...). The data type of
1335 * "ipaddr" is printed as a dotted-quad (e.g. 192.0.2.15).
1337 * The format is "Attribute-Name = value"
1339 * @param[out] buffer Where the printable version of the ::VALUE_PAIR is stored
1340 * @param[in] bufsize size of the output buffer
1341 * @param[in] vp ::VALUE_PAIR to print
1342 * @return length of data in buffer
1344 extern size_t nr_vp_snprintf(char *buffer, size_t bufsize, const VALUE_PAIR *vp);
1346 /** Pretty-print the VALUE_PAIR::data field \ingroup print
1348 * Prints the value of a ::VALUE_PAIR, without the name or "=" sign.
1350 * @param[out] buffer Where the printable version of the ::VALUE_PAIR is stored
1351 * @param[in] bufsize size of the output buffer
1352 * @param[in] vp ::VALUE_PAIR to print
1353 * @return length of data in buffer
1355 extern size_t nr_vp_snprintf_value(char *buffer, size_t bufsize, const VALUE_PAIR *vp);
1357 /** Prints a list of :VALUE_PAIR structures to the given output. \ingroup print
1359 * @param[in] fp Where to print the results
1360 * @param[in] vps Linked list of ::VALUE_PAIR to print
1362 extern void nr_vp_fprintf_list(FILE *fp, const VALUE_PAIR *vps);
1364 /** Scan a string into a ::VALUE_PAIR. The counterpart to
1365 * nr_vp_snprintf_value() \ingroup print
1367 * @param[in] string Printable version of the ::VALUE_PAIR
1368 * @param[out] pvp Newly allocated ::VALUE_PAIR
1369 * @return <0 on error, 0 for success.
1371 extern int nr_vp_sscanf(const char *string, VALUE_PAIR **pvp);
1373 /** Scan the data portion of a ::VALUE_PAIR. The counterpart to
1374 * nr_vp_snprintf_value() \ingroup print
1376 * @param[in,out] vp The ::VALUE_PAIR where the data will be stored
1377 * @param[in] value The string version of the data to be parsed
1378 * @return <0 on error, >=0 for the number of characters parsed in value.
1380 extern ssize_t nr_vp_sscanf_value(VALUE_PAIR *vp, const char *value);
1382 #if defined(__GNUC__)
1383 # define PRINTF_LIKE(n) __attribute__ ((format(printf, n, n+1)))
1384 # define NEVER_RETURNS __attribute__ ((noreturn))
1385 # define UNUSED __attribute__ ((unused))
1386 # define BLANK_FORMAT " " /* GCC_LINT whines about empty formats */
1389 /** Macro used to quiet compiler warnings inside of the library. \ingroup build
1392 # define PRINTF_LIKE(n)
1394 /** Macro used to quiet compiler warnings inside of the library. \ingroup build
1397 # define NEVER_RETURNS
1399 /** Macro used to quiet compiler warnings inside of the library. \ingroup build
1404 /** Macro used to quiet compiler warnings inside of the library. \ingroup build
1407 # define BLANK_FORMAT ""