summaryrefslogtreecommitdiff
path: root/lib/radius/client.h
blob: ab4718a26e97b6644986c177c49472e858677205 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
/*
Copyright (c) 2011, Network RADIUS SARL
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
    * Neither the name of the <organization> nor the
      names of its contributors may be used to endorse or promote products
      derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/** \file client.h
 *  \brief Main header file.
 */

#ifndef _RADIUS_CLIENT_H_
#define _RADIUS_CLIENT_H_ 1

/*
 *  System-specific header files.
 */
#include <config.h>
#include <errno.h>
#include <stdio.h>
#ifdef HAVE_STDINT_H
#include <stdint.h>
#endif
#ifdef HAVE_STDLIB_H
#include <stdlib.h>
#endif
#ifdef HAVE_STRING_H
#include <string.h>
#endif
#include <stdarg.h>
#include <sys/types.h>
#ifdef HAVE_NETDB_H
#include <netdb.h>
#endif
#ifdef HAVE_NETINET_IN_H
#include <netinet/in.h>
#endif
#ifdef HAVE_SYS_TIME_H
#include <sys/time.h>
#endif

#include <radsec/radsec.h>
#include <radsec/radsec-impl.h>
#include <radsec/radius.h>

/** \defgroup build Build Helpers
 *
 * These definitions give the GNU C compiler more information about
 * the functions being compiled.  They are used to either remove
 * warnings, or to enable better warnings.
 **/

/** \defgroup custom Portability Functions
 *
 * These functions and definitions should be modified for your local
 * system.  See the individual definitions for details.
 */

/** \defgroup error Error handling
 *
 * These definitions and routines manage errors.
 */

/** \defgroup value_pair Attribute manipulation
 *
 * These routines manage structures which map to attributes.
 */

/**\defgroup dict Dictionary Lookup Functions
 *
 * \sa doc/dictionaries.txt
 *
 * The RADIUS dictionaries perform name to number mappings.  The names
 * are used only for administrator convenience, for parsing
 * configuration files, and printing humanly-readable output.  The
 * numbers are used when encoding data in a packet.
 *
 * When attributes are decoded from a packet, the numbers are used to
 * look up the associated name, which is then placed into a data
 * structure.
 *
 * When the data structures are encoded into a packet, the numbers are
 * used to create RFC and VSA format attributes.
 *
 * \attention The definitions, structures, and functions given below
 * are useful only for implementing "low level" RADIUS
 * functionality. There is usually no need to refer to them in a
 * client application.  The library should be used at a higher level,
 * which exposes a much simpler API.
 */

/** \defgroup packet Packet manipulation
 *
 * These routines perform encoding and decoding of RADIUS packets.
 */

/** \defgroup print Print / parse functions
 *
 * These routines convert the internal data structures to a printable
 * form, or parse them.
 */

/** \defgroup id ID allocation and freeing
 *
 *  These routines manage RADIUS ID allocation.
 */

/** \defgroup attr Low-level attribute encode/decoding
 *
 * These routines perform "low level" encoding, decoding, sending, and
 * reception of RADIUS attributes.  They are called by the \ref packet
 * functions.
 *
 * \attention The structures and functions given below are useful only
 * for implementing "low level" RADIUS functionality. There is usually
 * no need to refer to them in a client application.  The library
 * should be used at a higher level, which exposes a much simpler API.
 */

/** \defgroup internal Internal support functions.
 *
 * These functions are required to perform internal or "low-level"
 * data manipulation.  While they are exposed for completeness, they
 * should not be called by any application.
 */

#ifdef PW_EAP_MESSAGE
#ifndef PW_MESSAGE_AUTHENTICATOR
#error EAP-Message requires Message-Authenticator
#endif
#endif

#ifdef WITHOUT_OPENSSL
#include "md5.h"
#else
#include <openssl/md5.h>
#endif

/** Define for compile-time selection of the MD5 functions.  Defaults to using the OpenSSL functions.  \ingroup custom */
#define RS_MD5_CTX	MD5_CTX
/** Define for compile-time selection of the MD5 functions.  Defaults to using the OpenSSL functions. \ingroup custom */
#define RS_MD5Init	MD5_Init
/** Define for compile-time selection of the MD5 functions.  Defaults to using the OpenSSL functions. \ingroup custom */
#define RS_MD5Update	MD5_Update
/** Define for compile-time selection of the MD5 functions.  Defaults to using the OpenSSL functions. \ingroup custom */
#define RS_MD5Final	MD5_Final


#ifndef RS_MAX_PACKET_LEN
/** The maximum size of a packet that the library will send or receive.  \ingroup custom
 *
 *  The RFC requirement is to handle at least 4K packets.  However, if
 *  you expect to only do username/password authentication, this value
 *  can be set to a smaller value, such as 256.
 *
 *  Be warned that any packets larger than this value will be ignored
 *  and silently discarded.
 */
#define RS_MAX_PACKET_LEN (4096)
#endif

#ifndef RS_MAX_ATTRIBUTES
/** The maximum number of attributes that the library will allow in a packet.  \ingroup custom
 *
 *  Packets which contain more than ::RS_MAX_ATTRIBUTES will generate
 *  an error.  This value is configurable because there may be a need
 *  to accept a large mumber of attributes.
 *
 *  This value is ignored when packets are sent.  The library will
 *  send as many attributes as it is told to send.
 */
#define RS_MAX_ATTRIBUTES (200)
#endif

#undef RS_MAX_PACKET_CODE
/** The maximum RADIUS_PACKET::code which we can accept. \ingroup dict
 *
 *  \attention This should not be changed, as it is used by other
 *  structures such as ::nr_packet_codes.
 */
#define RS_MAX_PACKET_CODE PW_COA_NAK

/**  The maximum vendor number which is permitted. \ingroup dict
 *
 *  The RFCs require that the Vendor Id or Private Enterprise Number
 *  be encoded as 32 bits, with the upper 8 bits being zero.
 */
#define RS_MAX_VENDOR		(1 << 24)

/** Data Type Definitions. \ingroup dict
 */
#define TAG_VALID(x)          ((x) < 0x20)

/** The attribute is not encrypted. */
#define FLAG_ENCRYPT_NONE            (0)

/** The attribute is encrypted using the RFC 2865 User-Password method */
#define FLAG_ENCRYPT_USER_PASSWORD   (1)

/** The attribute is encrypted using the RFC 2868 Tunnel-Password method */
#define FLAG_ENCRYPT_TUNNEL_PASSWORD (2)

/** A set of flags which determine how the attribute should be handled.
 *
 * Most attributes are "normal", and do not require special handling.
 * However, some require "encryption", tagging, or have other special
 * formats.  This structure contains the various options for the
 * attribute formats.
 */
typedef struct attr_flags {
	unsigned int		has_tag : 1; /**< Attribute has an RFC 2868 tag */
	unsigned int		unknown : 1; /**< Attribute is unknown */
#ifdef RS_TYPE_TLV
	unsigned int		has_tlv : 1; /* has sub attributes */
	unsigned int		is_tlv : 1; /* is a sub attribute */
#endif
	unsigned int		extended : 1; /* extended attribute */
	unsigned int		extended_flags : 1; /* with flag */
	unsigned int		evs : 1;	    /* extended VSA */
	uint8_t		        encrypt;      /**< Attribute encryption method */
	uint8_t			length;	      /**< The expected length of the attribute */
} ATTR_FLAGS;


/** Defines an dictionary mapping for an attribute.  \ingroup dict
 *
 *  The RADIUS dictionaries map humanly readable names to protocol
 *  numbers.  The protocol numbers are used to encode/decode the
 *  attributes in a packet.
 */
typedef struct nr_dict_attr {
	unsigned int		attr;		/**< Attribute number  */
	rs_attr_type_t	      	type;		/**< Data type */
	unsigned int		vendor;		/**< Vendor-Id number  */
        ATTR_FLAGS              flags;
	const char		*name;		/**< Printable name  */
} DICT_ATTR;

/** Defines a dictionary mapping for a named enumeration.  \ingroup dict
 *
 *  This structure is currently not used.
 */
typedef struct nr_dict_value {
	const DICT_ATTR		*da;		/**< pointer to a ::DICT_ATTR  */
	int			value;		/**< enumerated value  */
	char			name[1];	/**< printable name  */
} DICT_VALUE;

/** Defines an dictionary mapping for a vendor.  \ingroup dict
 *
 *  The RADIUS dictionaries map humanly readable vendor names to a
 *  Vendor-Id (or Private Enterprise Code) assigned by IANA.  The
 *  Vendor-Id is used to encode/decode Vendor-Specific attributes in a
 *  packet.
 */
typedef struct nr_dict_vendor {
	unsigned int		vendor; /**< Vendor Private Enterprise Code  */
	size_t			type;	   /**< size of Vendor-Type field */
	size_t			length;    /**< size of Vendor-Length field */
	const char		*name;		/**< Printable name  */
} DICT_VENDOR;

/** Union holding all possible types of data for a ::VALUE_PAIR. \ingroup value_pair
 *
 */
typedef union value_pair_data {
	char			strvalue[RS_MAX_STRING_LEN]; /* +1 for NUL */
	uint8_t			octets[253];
	struct in_addr		ipaddr;
	struct in6_addr		ipv6addr;
	uint32_t		date;
	uint32_t		integer;
#ifdef RS_TYPE_SIGNED
	int32_t			sinteger;
#endif
#ifdef RS_TYPE_ABINARY
	uint8_t			filter[32];
#endif
	uint8_t			ifid[8]; /* struct? */
	uint8_t			ipv6prefix[18]; /* struct? */
#ifdef RS_TYPE_TLV
	uint8_t			*tlv;
#endif
} VALUE_PAIR_DATA;


/** C structure version of a RADIUS attribute. \ingroup value_pair
 *
 * The library APIs use this structure to avoid depending on the
 * details of the protocol.
 */
typedef struct value_pair {
	const DICT_ATTR		*da; /**< dictionary definition */
	size_t			length;	/**< number of octets in the data */
	int			tag; /**< tag value if da->flags.has_tag */
	struct value_pair	*next; /**< enables a linked list of values  */
	VALUE_PAIR_DATA		data;  /**< the data of the attribute */
} VALUE_PAIR;
#define vp_strvalue   data.strvalue
#define vp_octets     data.octets
#define vp_ipv6addr   data.ipv6addr
#define vp_ifid       data.ifid
#define vp_ipv6prefix data.ipv6prefix
#define vp_ipaddr     data.ipaddr.s_addr
#define vp_date       data.integer
#define vp_integer    data.integer
#ifdef RS_TYPE_ABINARY
#define vp_filter     data.filter
#endif
#ifdef RS_TYPE_ETHER
#define vp_ether      data.ether
#endif
#ifdef RS_TYPE_SIGNED
#define vp_signed     data.sinteger
#endif
#ifdef RS_TYPE_TLV
#define vp_tlv	      data.tlv
#endif

#ifdef RS_TYPE_TLV
#define RS_ATTR_MAX_TLV (4)
extern const int nr_attr_shift[RS_ATTR_MAX_TLV];
extern const int nr_attr_mask[RS_ATTR_MAX_TLV];
extern const unsigned int nr_attr_max_tlv;
#endif

/** A structure which describes a RADIUS packet. \ingroup packet
 *
 *  In general, it should not be necessary to refererence the elements
 *  of this structure.
 */
typedef struct radius_packet {
	int			sockfd; /** The socket descriptor */
	struct sockaddr_storage	src;    /**< The packet source address  */
        struct sockaddr_storage	dst;    /**< the packet destination address */
	const char		*secret; /**< The shared secret */
	size_t			sizeof_secret; /**< Length of the shared secret */
	unsigned int		code;	/**< The RADIUS Packet Code */
	int			id;	/**< The RADIUS Packet Id */
	size_t			length; /**< The RADIUS Packet Length.  This will be no larger than RADIUS_PACKET::sizeof_data */
	uint8_t			vector[16]; /**< A copy of the authentication vector */
	int			flags; /**< Internal flags.  Do not modify this field. */
	int			attempts; /**< The number of transmission attempt  */
	uint8_t			*data;	  /**< The raw packet data  */
	size_t			sizeof_data; /**< size of the data buffer  */
	VALUE_PAIR		*vps;	/**< linked list of ::VALUE_PAIR */
} RADIUS_PACKET;

#define RS_PACKET_ENCODED  (1 << 0)
#define RS_PACKET_HEADER   (1 << 1)
#define RS_PACKET_SIGNED   (1 << 2)
#define RS_PACKET_OK	   (1 << 3)
#define RS_PACKET_VERIFIED (1 << 4)
#define RS_PACKET_DECODED  (1 << 5)


/** Track packets sent to a server. \ingroup id
 *
 * This data structure tracks Identifiers which are used to
 * communicate with a particular destination server.  The application
 * should call nr_server_init() to initialize it.  If necessary, the
 * application should then call nr_server_set_ipv4() to open an IPv4
 * socket to the server.
 *
 * If the RADIUS packets are being transported over an encapsulation
 * layer (e.g. RADIUS over TLS), then nr_server_set_ipv4() does not
 * need to be called.  The ::nr_server_t structure should instead be
 * associated wih the TLS session / socket.
 */
typedef struct nr_server_t {
	int sockfd;		/**< socket for sending packets  */
	int code;		/**< default value for the Code */

	struct sockaddr_storage src; /**< Source address of the packet */
	struct sockaddr_storage dst; /**< Destination address of the packet  */

	/** The shared secret.
	 *
	 *  See also nr_packet_send() and nr_packet_recv().
	 */
	const char	*secret;

	/** The length of the shared secret.
	 *
	 *  See also nr_packet_send() and nr_packet_recv().
	 */
	size_t		sizeof_secret;

	int		used;	/**< Number of used IDs */

	void		*free_list; /**< For managing packets */

	RADIUS_PACKET	*ids[256]; /**< Pointers to "in flight" packets  */
} nr_server_t;


/** Return a printable error message. \ingroup error
 *
 *  This function returns a string describing the last error that
 *  occurred.  These messages are intended for developers, and are not
 *  suitable for display to an end user.  The application using this
 *  library should instead produce a "summary" message when an error
 *  occurs.  e.g. "Failed to receive a response", is better than
 *  messages produced by this function, which contain text like
 *  "invalid response authentication vector".  The first is
 *  understandable, the second is not.
 *
 * @param[in] error   The error code (can be less than zero)
 * @return            A printable string describing the error.
 */
extern const char *nr_strerror(int error);

/** Allocate a ::VALUE_PAIR which refers to a ::DICT_ATTR.  \ingroup value_pair
 *
 *  This returned ::VALUE_PAIR has no data associated with it.  The
 *  nr_vp_set_data() function must be called before placing the
 *  ::VALUE_PAIR in a ::RADIUS_PACKET.
 *
 * @param[in] da       The ::DICT_ATTR associated with the ::VALUE_PAIR
 * @return             The created ::VALUE_PAIR, or NULL on error.
 */
extern VALUE_PAIR *nr_vp_alloc(const DICT_ATTR *da);

/** Free a ::VALUE_PAIR.  \ingroup value_pair
 *
 *  This function frees the ::VALUE_PAIR, and sets the head pointer to NULL.
 *  If head refers to a ::VALUE_PAIR list, then all of the structures in the
 *  list are freed.
 *
 * @param[in,out] head   The pointer to a ::VALUE_PAIR, or a ::VALUE_PAIR list.
 */
extern void nr_vp_free(VALUE_PAIR **head);

/** Initializes a ::VALUE_PAIR from a ::DICT_ATTR \ingroup value_pair
 *
 *  This function assumes that the ::VALUE_PAIR points to existing
 *  and writable memory.
 *
 * @param[in,out] vp   The ::VALUE_PAIR to be initialized
 * @param[in] da       The ::DICT_ATTR used to initialize the ::VALUE_PAIR
 * @return             The initialized  ::VALUE_PAIR, or NULL on error.
 */
extern VALUE_PAIR *nr_vp_init(VALUE_PAIR *vp, const DICT_ATTR *da);

/** Allocate a ::VALUE_PAIR which refers to an unknown attribute.  \ingroup value_pair
 *
 *  It is used when an attribute is received, and that attribute does
 *  not exist in the dictionaries.
 *
 *  The returned ::VALUE_PAIR has no data (i.e. VALUE_PAIR::length is
 *  zero).  The nr_vp_set_data() function must be called before
 *  placing the ::VALUE_PAIR in a ::RADIUS_PACKET.
 *
 * @param[in] attr     The attribute number, 0..2^16
 * @param[in] vendor   The vendor number, 0..2^16
 * @return             The created ::VALUE_PAIR, or NULL on error.
 */
extern VALUE_PAIR *nr_vp_alloc_raw(unsigned int attr, unsigned int vendor);

/** Set the data associated with a previously allocated ::VALUE_PAIR.  \ingroup value_pair
 *
 *  If this function succeeds, VALUE_PAIR::length is no longer zero,
 *  and the structure contains the data.
 *
 * @param[in,out] vp   The ::VALUE_PAIR to update
 * @param[in] data     Data to set inside of the ::VALUE_PAIR
 * @param[in] data_len Length of the data field
 * @return             <0 on error, 0 for "data was truncated"
 *                      >0 for "data successfully added"
 */
extern int nr_vp_set_data(VALUE_PAIR *vp, const void *data, size_t data_len);

/** Create a ::VALUE_PAIR and set its data.  \ingroup value_pair
 *
 * @param[in] attr     The attribute number of the ::VALUE_PAIR to create
 * @param[in] vendor   The vendor number of the ::VALUE_PAIR to create
 * @param[in] data     Data to set inside of the ::VALUE_PAIR
 * @param[in] data_len Length of the data field
 * @return             The created ::VALUE_PAIR, or NULL on error.
 */
extern VALUE_PAIR *nr_vp_create(int attr, int vendor, const void *data,
			      size_t data_len);

/** Append a ::VALUE_PAIR to the end of a ::VALUE_PAIR list.  \ingroup value_pair
 *
 * @param[in,out] head The head of the ::VALUE_PAIR list.  May not be NULL.
 * @param[in] vp       The ::VALUE_PAIR to append to the list.
 */
extern void nr_vps_append(VALUE_PAIR **head, VALUE_PAIR *vp);

/** Search a ::VALUE_PAIR list for one of a given number.  \ingroup value_pair
 *
 * @param[in] head     The head of the ::VALUE_PAIR list to search.
 * @param[in] attr     The attribute number of the ::VALUE_PAIR to find
 * @param[in] vendor   The vendor number of the ::VALUE_PAIR to find
 * @return             The found ::VALUE_PAIR, or NULL if it was not found.
 */
extern VALUE_PAIR *nr_vps_find(VALUE_PAIR *head,
			    unsigned int attr, unsigned int vendor);

/** Look up an attribute in the dictionaries.  \ingroup dict
 *
 *  The dictionary mapping contains information about the attribute,
 *  such as printable name, data type (ipaddr, integer, etc), and
 *  various other things used to encode/decode the attribute in a
 *  packet.
 *
 *  \attention There is usually no need to call this function.  Use
 *  the RS_DA_* definitions instead.
 *
 * @param[in] attr    Value of the attribute
 * @param[in] vendor  Value of the vendor
 * @return    NULL for "not found", or a pointer to the attribute mapping.
 */
extern const DICT_ATTR *nr_dict_attr_byvalue(unsigned int attr,
					 unsigned int vendor);

/** Look up an attribute in the dictionaries.  \ingroup dict
 *
 *  The dictionary mapping contains information about the attribute,
 *  such as printable name, data type (ipaddr, integer, etc), and
 *  various other things used to encode/decode the attribute in a
 *  packet.
 *
 *  \attention There is usually no need to call this function.
 *
 * @param[in] name    Name of the attribute
 * @return    NULL for "not found", or a pointer to the attribute mapping.
 */
extern const DICT_ATTR *nr_dict_attr_byname(const char *name);

/** Converts raw data to a ::DICT_ATTR structure.  \ingroup dict
 *
 *  It is called when the library is asked to decode an attribute
 *  which is not in the pre-defined dictionaries.
 *
 *  \attention There is usually no need to call this function.
 *
 * @param[in,out] da      The ::DICT_ATTR structure to initialize
 * @param[in]     attr    The attribute number
 * @param[in]     vendor  The vendor number
 * @param[in]     buffer  The buffer where the name of the attribute is stored
 * @param[in]     bufsize Size of the buffer
 * @return    <0 for error, 0 for success
 */
extern int nr_dict_attr_2struct(DICT_ATTR *da,
				unsigned int attr, unsigned int vendor,
				char *buffer, size_t bufsize);

/**  Unused. \ngroup dict
 *
 */
extern const DICT_VALUE *nr_dict_value_byattr(unsigned int attr,
					unsigned int vendor,
					int value);

/**  Unused. \ngroup dict
 *
 */
const DICT_VALUE *nr_dict_value_byname(unsigned int attr,
				 unsigned int vendor,
				 const char *name);

/** Look up a vendor in the dictionaries.  \ingroup dict
 *
 *  The dictionary mapping contains information about the vendor, such
 *  as printable name, VSA encoding method, etc.
 *
 *  \attention There is usually no need to call this function.
 *  Applications do not need access to low-level RADIUS protocol
 *  information.
 *
 * @param[in] name    Name of the vendor.
 * @return    NULL for "not found", or a pointer to the vendor mapping.
 */
extern int nr_dict_vendor_byname(const char *name);

/** Look up an vendor in the dictionaries.  \ingroup dict
 *
 *  The dictionary mapping contains information about the vendor, such
 *  as printable name, VSA encoding method, etc.
 *
 *  \attention There is usually no need to call this function.
 *
 * @param[in] vendor Vendor-Id (or Private Enterprise code) for the vendor.
 * @return    NULL for "not found", or a pointer to the vendor mapping.
 */
extern const DICT_VENDOR *nr_dict_vendor_byvalue(unsigned int vendor);

/**  Static array of known vendors.  \ingroup dict
 *
 *  \attention This structure should only be accessed by internal RADIUS library
 *  functions.
 */
extern const DICT_VENDOR nr_dict_vendors[];

/** The number of attribute definitions in the dictionary.  \ingroup dict
 *
 *  This number is guaranteed to be at least 256, for speed.
 *
 *  \attention This variable should only be accessed by internal RADIUS library
 *  functions.
 */
extern const int nr_dict_num_attrs;

/** The list of attribute definitions.  \ingroup dict
 *
 *  The "standard" RFC attributes are located in the first 256
 *  entries.  Standard attributes without a dictionary definition are
 *  given an empty entry.
 *
 *  The attributes are orderd by (vendor, attribute), in increasing
 *  order.  This allows the dictionary lookups to find attributes by a
 *  binary search.
 *
 *  \attention This variable should only be accessed by internal RADIUS library
 *  functions.
 */
extern const DICT_ATTR nr_dict_attrs[];

/** The number of attributes with names.  \ingroup dict
 *
 *  \attention This variable should only be accessed by internal RADIUS library
 *  functions.
 */
extern const int nr_dict_num_names;

/** The list of attribute definitions, organized by name.  \ingroup dict
 *
 *  The attributes are orderd by name (case insensitive), in
 *  increasing order.  This allows the dictionary lookups to find
 *  attributes by a binary search.
 *
 *  \attention This variable should only be accessed by internal RADIUS library
 *  functions.
 */
extern const DICT_ATTR const *nr_dict_attr_names[];

/** Static array containing names the RADIUS_PACKET::code field.  \ingroup dict
 *
 *  The names are hard-coded and not in any dictionary because they do
 *  not change.
 *
 *  The names are exported because they may be useful in your
 *  application.  Packet codes which are not handled by the library
 *  have NULL for their names.
 */
extern const char *nr_packet_codes[RS_MAX_PACKET_CODE + 1];

/** Verifies that a packet is "well formed".  \ingroup packet
 *
 *  This function performs basic validation to see if the packet is
 *  well formed.  It is automatically called by nr_packet_decode().
 *
 * @param[in] packet      A pointer to the ::RADIUS_PACKET data.
 * @return                <0 means malformed, >= 0 means well-formed.
 */
extern int nr_packet_ok(RADIUS_PACKET *packet);

/** Verifies that a packet is "well formed".  \ingroup packet
 *
 *  This function performs basic validation to see if the packet is
 *  well formed.  You should normally use nr_packet_ok() instead of
 *  this function.
 *
 * @param[in] data        A pointer to the raw packet data.
 * @param[in] sizeof_data The length of the raw packet data
 * @return                <0 means malformed, >= 0 means well-formed.
 */
extern int nr_packet_ok_raw(const uint8_t *data, size_t sizeof_data);

/** Encodes a packet.  \ingroup packet
 *
 *  This function encodes a packet using the fields of the
 *  ::RADIUS_PACKET structure.  The RADIUS_PACKET::code and
 *  RADIUS_PACKET::id fields are used to fill in the relevant fields
 *  of the raw (encoded) packet.  The RADIUS_PACKET::vps list is
 *  walked to encode the attributes.  The packet is signed, if
 *  required.
 *
 *  The raw packet is placed into the RADIUS_PACKET::data field, up to
 *  RADIUS_PACKET::sizeof_data bytes.  the RADIUS_PACKET::length field
 *  is updated with the length of the raw packet.  This field is
 *  always less than, or equal to, the RADIUS_PACKET::size_data field.
 *  If there is insufficient room to store all of the attributes, then
 *  some attributes are silently discarded.
 *
 *  The RADIUS_PACKET::vector field is either calculated as part of
 *  the signing process, or is initialized by this function to be a
 *  random sequence of bytes.  That field should therefore be left
 *  alone by the caller.
 *
 *  When the encoding has been successful, it sets the
 *  RADIUS_PACKET::encoded field to non-zero.
 *
 *  In addition, all required attribute "encryption" is performed.
 *
 *  User-Password.  The vp_strvalue field is assumed to contain the
 *  "clear-text" version of the password.  The encrypted version is
 *  calculated, and placed in the packet.
 *
 *  CHAP-Password.  The vp_strvalue field is assumed to contain the
 *  "clear-text" version of the password.  The encrypted version is
 *  calculated, and placed in the packet.  If the RADIUS_PACKET::vps
 *  list contains a CHAP-Challenge attribute, it is used.  Otherwise
 *  the RADIUS_PACKET::vector field is used a the challenge.
 *
 *  Message-Authenticator.  The contents of the Message-Authenticator
 *  in the RADIUS_PACKET::vps list are ignored.  Instead, a
 *  "place-holder" is put into the packt.  Tthe correct value is
 *  calculated and placed into the packet by nr_packet_sign().
 *
 *  The RADIUS_PACKET::vps list is left untouched by this function,
 *  even when attribute encryption or signing is performed.  Any
 *  VALUE_PAIR structures can therefore be taken from static "const"
 *  variables.
 *
 * @param[in] packet   The RADIUS packet to encode.
 * @param[in] original The original request, when encoding a response.
 * @return             <0 on error, >= 0 on success.
 */
extern int nr_packet_encode(RADIUS_PACKET *packet, const RADIUS_PACKET *original);

/** Decodes a packet.  \ingroup packet
 *
 *  This function decodes a packet from the RADIUS_PACKET::data field
 *  into a sequence of ::VALUE_PAIR structures in the
 *  RADIUS_PACKET::vps list.
 *
 * @param[in] packet   The RADIUS packet to decode.
 * @param[in] original The original request, when decoding a response.
 * @return             <0 on error, >= 0 on success.
 */
extern int nr_packet_decode(RADIUS_PACKET *packet, const RADIUS_PACKET *original);

/** Signs a packet so that it can be sent.  \ingroup packet
 *
 * This function calculates the Message-Authenticator (if required),
 * and signs the packet.
 *
 * @param[in] packet   The RADIUS packet to sign.
 * @param[in] original The original request, when signing a response.
 * @return             <0 on error, >= 0 on success.
 */
extern int nr_packet_sign(RADIUS_PACKET *packet, const RADIUS_PACKET *original);

/** Verifies that a packet is well-formed and contains the correct signature.  \ingroup packet
 *
 *  If "original" is specified, it also verifies that the packet is a
 *  response to the original request, and that it has the correct
 *  signature.
 *
 * @param[in] packet   The RADIUS packet to verify.
 * @param[in] original The original request, when verifying a response.
 * @return             <0 on error, >= 0 on success.
 */
extern int nr_packet_verify(RADIUS_PACKET *packet,
			    const RADIUS_PACKET *original);

/** Pretty-prints a hex dump of a RADIUS packet.  \ingroup packet print
 *
 *  This function is available only in debugging builds of the
 *  library.  It is useful during development, but should not be used
 *  in a production system.
 *
 *  The packet headers are printed individually, and each attribute is
 *  printed as "type length data..."
 *
 * @param[in] packet   The RADIUS packet to print
 */
extern void nr_packet_print_hex(RADIUS_PACKET *packet);


/** Return the given number of random bytes.  \ingroup custom
 *
 * This function should be replaced by one that is specific to your
 * system.
 *
 *  This is a wrapper function which enables the library to be more
 *  portable.
 *
 * @param[in] data      Location where the random bytes will be stored
 * @param[in] data_len  Number of bytes to store
 * @return              <0 on error, or the total number of bytes stored.
 */
extern ssize_t nr_rand_bytes(uint8_t *data, size_t data_len);

/** Return a random 32-bit integer.  \ingroup custom
 *
 * This function should be replaced by one that is specific to your
 * system.  The version supplied here just calls nr_rand_bytes() each
 * time, which is slow.
 *
 *  This is a wrapper function which enables the library to be more
 *  portable.
 *
 * @return An unsigned 32-bit random integer.
 */
extern uint32_t nr_rand(void);

/** Add a time to the given ::struct timeval.  \ingroup custom
 *
 *  This is a wrapper function which enables the library to be more
 *  portable.
 *
 *  @param[in,out] t       The timeval to which the time is added.
 *  @param[in]     seconds Time in seconds to add
 *  @param[in]     usec    Time in microseconds to add
 */
extern void nr_timeval_add(struct timeval *t, unsigned int seconds,
			   unsigned int usec);

/** Compare two times.  \ingroup custom
 *
 *  This is a wrapper function which enables the library to be more
 *  portable.
 *
 * @param[in] a One timeval
 * @param[in] b Another one
 * @return a <=> b
 */
extern int nr_timeval_cmp(const struct timeval *a, const struct timeval *b);

/** Initializes an ::nr_server_t.  \ingroup id
 *
 * @param[in,ut] s      The ::nr_server_t to initialize
 * @param[in]    code   The packet code used for packets sent to this server
 * @param[in]    secret The shared secret used for packet sent to this server
 * @return <0 for error, >= 0 for success
 */
extern int nr_server_init(nr_server_t *s, int code, const char *secret);

/** Closes an ::nr_server_t data structure.  \ingroup id
 *
 *  Ensures that all IDs are free, and closes the socket.
 *
 * @param[in] s      The server structure to close.
 * @return <0 for error, 0 for success
 */
extern int nr_server_close(const nr_server_t *s);

/** Allocate a RADIUS_PACKET::id value for sending a packet to a server. \ingroup id
 *
 * This function allocates a RADIUS_PACKET::id from the ::nr_server_t
 * structure.  It also fills in the RADIUS_PACKET::sockfd,
 * RADIUS_PACKET::code, and RADIUS_PACKET::dst fields.
 *
 * @param[in] s      The server structure which tracks the ID
 * @param[in] packet The packet which needs an ID
 * @return <0 for error, 0 for success
 */
extern int nr_server_id_alloc(nr_server_t *id, RADIUS_PACKET *packet);

/** Re-allocate a RADIUS_PACKET::id value for sending a packet to a server. \ingroup id
 *
 *  It is used when retransmitting an Accounting-Request packet to a
 *  server, after updating the Acct-Delay-Time field.  The "realloc"
 *  name means that the new ID is allocated, and is guaranteed to be
 *  different from the old one.
 *
 * @param[in] s      The server structure which tracks the ID
 * @param[in] packet The packet which needs a new ID
 * @return <0 for error, 0 for success
 */
extern int nr_server_id_realloc(nr_server_t *id, RADIUS_PACKET *packet);

/** Free a RADIUS_PACKET::id value after sending a packet to a server. \ingroup id
 *
 * @param[in] s      The server structure which tracks the ID
 * @param[in] packet The packet which has an ID, and wants to free it
 * @return <0 for error, 0 for success
 */
extern int nr_server_id_free(nr_server_t *id, RADIUS_PACKET *packet);


/** Allocates a packet using malloc(), and initializes it. \ingroup id
 *
 * @param[in] s             The server structure
 * @param[in,out] packet_p  Pointer to the ::RADIUS_PACKET to be allocated
 * @return <0 for error, 0 for success
 */
extern int nr_server_packet_alloc(const nr_server_t *s, RADIUS_PACKET **packet_p);

/**  Record a humanly readable error message. \ingroup error
 *
 *  \attention This structure should only be accessed by internal
 *  RADIUS library functions.
 *
 * @param[in] fmt   The format to use.
 */
extern void nr_strerror_printf(const char *fmt, ...);

#ifndef NDEBUG
#define nr_debug_error nr_strerror_printf /** \ingroup error */
#else
#define nr_debug_error if (0) nr_strerror_printf
#endif

/**  Encrypts or decrypts a User-Password attribute. \ingroup internal
 *
 *  \attention This structure should only be accessed by internal
 *  RADIUS library functions.
 *
 * @param[out] output   Buffer where the password is stored
 * @param[out] outlen   Size of the output buffer
 * @param[in]  input    Input buffer with password
 * @param[in]  inlen    Length of the input buffer
 * @param[in]  secret   The shared secret
 * @param[in]  vector   Authentication vector
 * @return <0 on error, or the length of data in "output"
 */
extern ssize_t nr_password_encrypt(uint8_t *output, size_t outlen,
				   const uint8_t *input, size_t inlen,
				   const char *secret, const uint8_t *vector);

/**  Encrypts a Tunnel-Password attribute. \ingroup internal
 *
 *  \attention This structure should only be accessed by internal
 *  RADIUS library functions.
 *
 * @param[out] output   Buffer where the password is stored
 * @param[out] outlen   Size of the output buffer
 * @param[in]  input    Input buffer with password
 * @param[in]  inlen    Length of the input buffer
 * @param[in]  secret   The shared secret
 * @param[in]  vector   Authentication vector
 * @return <0 on error, or the length of data in "output"
 */
extern ssize_t nr_tunnelpw_encrypt(uint8_t *output, size_t outlen,
				   const uint8_t *input, size_t inlen,
				   const char *secret, const uint8_t *vector);

/**  Decrypts a Tunnel-Password attribute. \ingroup internal
 *
 *
 *  \attention This structure should only be accessed by internal
 *  RADIUS library functions.
 *
 * @param[out] output   Buffer where the password is stored
 * @param[out] outlen   Size of the output buffer
 * @param[in]  input    Input buffer with password
 * @param[in]  inlen    Length of the input buffer
 * @param[in]  secret   The shared secret
 * @param[in]  vector   Authentication vector
 * @return <0 on error, or the length of data in "output"
 */
extern ssize_t nr_tunnelpw_decrypt(uint8_t *output, size_t outlen,
				   const uint8_t *input, size_t inlen,
				   const char *secret, const uint8_t *vector);

/**  Calculates an HMAC-MD5. \ingroup internal
 *
 * @param[in] data      Data to be hashed
 * @param[in] data_len  Length of data to be hashed
 * @param[in] key       Key for the HMAC
 * @param[in] key_len   Length of the key
 * @param[out] digest
 */
extern void nr_hmac_md5(const uint8_t *data, size_t data_len,
			const uint8_t *key, size_t key_len,
			uint8_t digest[16]);

/** Checks if a TLV is properly formatted. \ingroup internal
 *
 *  \attention This structure should only be accessed by internal
 *  RADIUS library functions.
 *
 * @param[in] data      Data to check
 * @param[in] length    Length of the data field
 * @param[in] dv_type   Length of the TLV "type" field
 * @param[in] dv_length Length of the TLV "length" field
 * @return             <0 on error, 0 for "TLV is OK"
 */
extern int nr_tlv_ok(const uint8_t *data, size_t length,
		      size_t dv_type, size_t dv_length);

/** A callback function used by nr_packet_walk().  \ingroup packet
 *
 *  The function should return 0 on success (i.e. keep walking), and
 *  otherwise a negative number indicating an error code
 *  (::nr_error_t).  That negative number will be used as the return
 *  code for nr_packet_walk().
 */
typedef int (*nr_packet_walk_func_t)(void *, const DICT_ATTR *, const uint8_t *, size_t);

/** Walks over all attributes in a packet. \ingroup packet
 *
 *  This function is an iterator which calls a user-supplied callback
 *  function for each attribute in the packet.  It should be used
 *  instead of manually walking over the attributes.  There are a
 *  number of odd corner cases when handling Vendor-Specific
 *  attributes, and it is easy to get those corner cases wrong.
 *
 *  This function iterates over *all* attributes, including nested
 *  VSAs.  That is its main value.
 *
 *  Encrypted attributes such as User-Password are not decrypted.
 *
 * @param[in] packet    The packet containing the data
 * @param[in] ctx       A user-supplied context.  May be NULL
 * @param[in] callback  The callback function where the information is passed.
 *
 * @return <0 for error,
 *          0 for success.
 */
extern int nr_packet_walk(RADIUS_PACKET *packet, void *ctx,
			  nr_packet_walk_func_t callback);

/** Initialize a packet
 *
 *  If original is specified, the packet is initialized as a response
 *  to the original request.
 *
 * @param[in,out] packet  The packet to initialize
 * @param[in] original    The original request (if any) to use as a template
 * @param[in] secret      Shared secret
 * @param[in] code        RADIUS Code field.
 * @param[in] data        Buffer where packets will be stored (RADIUS_PACKET::data)
 * @param[in] sizeof_data Size of buffer (RADIUS_PACKET::sizeof_data)
 * @return  <0 on error, 0 for success.
 */
extern int nr_packet_init(RADIUS_PACKET *packet, const RADIUS_PACKET *original,
			  const char *secret, int code,
			  void *data, size_t sizeof_data);

/** Add one attribute to the packet.
 *
 *  This function can be used to add "raw" data to a packet.  It
 *  allows the caller to extend the RADIUS packet without using a
 *  ::VALUE_PAIR data structure.
 *
 *  Some attributes are handled specially by this function.
 *
 *  EAP-Message.  This attribute is automatically split into 253-octet
 *  chunks.
 *
 *  User-Password, CHAP-Password, and Message-Authenticator.  These
 *  attributes are automatically encrypted, as is done by
 *  nr_packet_encode().
 *
 * @param[in] packet   The packet to edit
 * @param[in] original The original request (if any)
 * @param[in] da       Pointer to the attribute definition
 * @param[in] data     Data to append to the packet
 * @param[in] data_len Length of data to append to the packet
 *
 * @return <0 for error, >= 0 for "successfully appended data"
 *  The function returns the number of octets appended to the packet.
 */
extern ssize_t nr_packet_attr_append(RADIUS_PACKET *packet,
				     const RADIUS_PACKET *original,
				     const DICT_ATTR *da,
				     const void *data, size_t data_len);


/** Encodes any ::VALUE_PAIR into an attribute.  \ingroup attr
 *
 *  This function can be called for any ::VALUE_PAIR.  It will examine
 *  that structure, and call one of nr_vp2rfc() or nr_vp2vsa() as
 *  necessary.
 *
 * \attention This function should not be called.
 *
 * @param[in] packet   Where to place the encoded attribute.
 * @param[in] original The original request (optional), if "packet" is a response
 * @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.
 * @param[in] data     Where the attribute is to be encoded.
 * @param[in] room     How many octets are available for attribute encoding.
 *
 * @return <0 for error, or the number of octets used to encode the attribute.
 */
extern ssize_t nr_vp2attr(const RADIUS_PACKET *packet,
		      const RADIUS_PACKET *original,
		      const VALUE_PAIR **pvp, uint8_t *data, size_t room);

/** Encodes an RFC "standard" ::VALUE_PAIR into an attribute.  \ingroup attr
 *
 *  \attention This function should not be called.
 *
 * @param[in] packet   Where to place the encoded attribute.
 * @param[in] original The original request (optional), if "packet" is a response
 * @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.
 * @param[in] data      Where the attribute is to be encoded.
 * @param[in] room     How many octets are available for attribute encoding.
 *
 * @return <0 for error, or the number of octets used to encode the attribute.
 */
extern ssize_t nr_vp2rfc(const RADIUS_PACKET *packet,
		     const RADIUS_PACKET *original,
		     const VALUE_PAIR **pvp,
		     uint8_t *data, size_t room);

/** Decodes any attribute into a ::VALUE_PAIR.  \ingroup attr
 *
 *  \attention This function should not be called.
 *
 * @param[in] packet   The packet containing the attribute to be decoded.
 * @param[in] original The original request (optional), if "packet" is a response
 * @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.
 * @param[in] data     Where the attribute is to be encoded.
 * @param[in] length   How many octets are available for attribute decoding.
 *
 * @return <0 for error, or the number of octets used to decode the attribute.
 */
extern ssize_t nr_attr2vp(const RADIUS_PACKET *packet, const RADIUS_PACKET *original,
			    const uint8_t *data, size_t length,
			    VALUE_PAIR **pvp);

/** Decodes an RFC "standard" attribute into a ::VALUE_PAIR.  \ingroup attr
 *
 *  \attention This function should not be called.
 *
 * @param[in] packet   The packet containing the attribute to be decoded.
 * @param[in] original The original request (optional), if "packet" is a response
 * @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.
 * @param[in] data     Where the attribute is to be encoded.
 * @param[in] length   How many octets are available for attribute decoding.
 *
 * @return <0 for error, or the number of octets used to decode the attribute.
 */
extern ssize_t nr_attr2vp_rfc(const RADIUS_PACKET *packet,
			const RADIUS_PACKET *original,
			const uint8_t *data, size_t length,
			VALUE_PAIR **pvp);

/** Decodes a Vendor-Specific attribute into a ::VALUE_PAIR.  \ingroup attr
 *
 *  \attention This function should not be called.
 *
 * @param[in] packet   The packet containing the attribute to be decoded.
 * @param[in] original The original request (optional), if "packet" is a response
 * @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.
 * @param[in] data     Where the attribute is to be encoded.
 * @param[in] length   How many octets are available for attribute decoding.
 *
 * @return <0 for error, or the number of octets used to decode the attribute.
 */
extern ssize_t nr_attr2vp_vsa(const RADIUS_PACKET *packet,
			const RADIUS_PACKET *original,
			const uint8_t *data, size_t length,
			VALUE_PAIR **pvp);

/** Decodes an attribute with an unexpected length into a ::VALUE_PAIR.  \ingroup attr
 *
 *  \attention This function should not be called.
 *
 * @param[in] packet   The packet containing the attribute to be decoded.
 * @param[in] original The original request (optional), if "packet" is a response
 * @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.
 * @param[in] data     Where the attribute is to be encoded.
 * @param[in] length   How many octets are available for attribute decoding.
 *
 * @return <0 for error, or the number of octets used to decode the attribute.
 */
extern ssize_t nr_attr2vp_raw(const RADIUS_PACKET *packet,
			const RADIUS_PACKET *original,
			const uint8_t *data, size_t length,
			VALUE_PAIR **pvp);

/** Encodes a Vendor-Specific ::VALUE_PAIR into an attribute.
 *
 *  \attention This function should not be called.
 *
 * @param[in] packet   Where to place the encoded attribute.
 * @param[in] original The original request (optional), if "packet" is a response
 * @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.
 * @param[in] data     Where the attribute is to be encoded.
 * @param[in] room     How many octets are available for attribute encoding.
 *
 * @return <0 for error, or the number of octets used to encode the attribute.
 */
extern ssize_t nr_vp2vsa(const RADIUS_PACKET *packet, const RADIUS_PACKET *original,
		     const VALUE_PAIR **pvp, uint8_t *data,
		     size_t room);

/** Returns raw data from the RADIUS packet, for a given attribute. \ingroup attr
 *
 *  This function can be called repeatedly to find all instances of a
 *  given attribute.  The first time it is called, the "start"
 *  parameter should be zero.  If the function returns a non-zero
 *  positive number, it means that there *may* be more attributes
 *  available.  The returned value should be then passed via the
 *  "start" option in any subsequent calls to the function.
 *
 *  This function should be called by an application when it wants
 *  access to data which is not in the pre-defined dictionaries.
 *
 * @param[in] packet   The packet containing the attribute.
 * @param[in] start    Where in the packet we start searching for the attribute.
 * @param[in] attr     Value of the attribute to search for
 * @param[in] vendor   Value of the vendor (use 0 for IETF attributes)
 * @param[out] pdata   Pointer to the data.  If no data was found, the pointer is unchanged.
 * @param[out] plength  Length of the data.  If no data was found, the value pointed to is unchanged.
 *
 * @return <0 for error,
 *          0 for "no attribute found, stop searching"
 *         >0 offset where the attribute was found.
 */
extern ssize_t nr_attr2data(const RADIUS_PACKET *packet, ssize_t start,
			     unsigned int attr, unsigned int vendor,
			     const uint8_t **pdata, size_t *plength);

/**  Pretty-print the entire ::VALUE_PAIR \ingroup print
 *
 *  All data is printed in ASCII format.  The data type of "octets" is
 *  printed as a hex string (e.g. 0xabcdef01...).  The data type of
 *  "ipaddr" is printed as a dotted-quad (e.g. 192.0.2.15).
 *
 *  The format is "Attribute-Name = value"
 *
 * @param[out] buffer  Where the printable version of the ::VALUE_PAIR is stored
 * @param[in]  bufsize size of the output buffer
 * @param[in]  vp      ::VALUE_PAIR to print
 * @return   length of data in buffer
 */
extern size_t nr_vp_snprintf(char *buffer, size_t bufsize, const VALUE_PAIR *vp);

/**  Pretty-print the VALUE_PAIR::data field \ingroup print
 *
 *  Prints the value of a ::VALUE_PAIR, without the name or "=" sign.
 *
 * @param[out] buffer  Where the printable version of the ::VALUE_PAIR is stored
 * @param[in]  bufsize size of the output buffer
 * @param[in]  vp      ::VALUE_PAIR to print
 * @return   length of data in buffer
 */
extern size_t nr_vp_snprintf_value(char *buffer, size_t bufsize, const VALUE_PAIR *vp);

/** Prints a list of :VALUE_PAIR structures to the given output. \ingroup print
 *
 * @param[in] fp   Where to print the results
 * @param[in] vps  Linked list of ::VALUE_PAIR to print
 */
extern void nr_vp_fprintf_list(FILE *fp, const VALUE_PAIR *vps);

/** Scan a string into a ::VALUE_PAIR.  The counterpart to
 * nr_vp_snprintf_value() \ingroup print
 *
 * @param[in] string  Printable version of the ::VALUE_PAIR
 * @param[out] pvp    Newly allocated ::VALUE_PAIR
 * @return <0 on error, 0 for success.
 */
extern int nr_vp_sscanf(const char *string, VALUE_PAIR **pvp);

/** Scan the data portion of a ::VALUE_PAIR.  The counterpart to
 * nr_vp_snprintf_value() \ingroup print
 *
 * @param[in,out] vp    The ::VALUE_PAIR where the data will be stored
 * @param[in]     value The string version of the data to be parsed
 * @return             <0 on error, >=0 for the number of characters parsed in value.
 */
extern ssize_t nr_vp_sscanf_value(VALUE_PAIR *vp, const char *value);

#if defined(__GNUC__)
# define PRINTF_LIKE(n) __attribute__ ((format(printf, n, n+1)))
# define NEVER_RETURNS __attribute__ ((noreturn))
# define UNUSED __attribute__ ((unused))
# define BLANK_FORMAT " "	/* GCC_LINT whines about empty formats */
#else

/** Macro used to quiet compiler warnings inside of the library. \ingroup build
 *
 */
# define PRINTF_LIKE(n)

/** Macro used to quiet compiler warnings inside of the library. \ingroup build
 *
 */
# define NEVER_RETURNS

/** Macro used to quiet compiler warnings inside of the library. \ingroup build
 *
 */
# define UNUSED

/** Macro used to quiet compiler warnings inside of the library. \ingroup build
 *
 */
# define BLANK_FORMAT ""
#endif

#endif /* _RADIUS_CLIENT_H_ */