embedaddon/bird/doc/prog-7.html - view

File: [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird / doc / prog-7.html
Revision 1.1.1.1 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Tue Aug 22 12:33:54 2017 UTC (6 years, 10 months ago) by misho
Branches: bird, MAIN
CVS tags: v1_6_8p3, v1_6_3p0, v1_6_3, HEAD

bird 1.6.3

1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> 2: <HTML> 3: <HEAD> 4: <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 1.0.9"> 5: <TITLE>BIRD Programmer's Documentation: Library functions</TITLE> 6: <LINK HREF="prog-8.html" REL=next> 7: <LINK HREF="prog-6.html" REL=previous> 8: <LINK HREF="prog.html#toc7" REL=contents> 9: </HEAD> 10: <BODY> 11: <A HREF="prog-8.html">Next</A> 12: <A HREF="prog-6.html">Previous</A> 13: <A HREF="prog.html#toc7">Contents</A> 14: <HR> 15: <H2><A NAME="s7">7.</A> <A HREF="prog.html#toc7">Library functions</A></H2> 16: 17: <H2><A NAME="ss7.1">7.1</A> <A HREF="prog.html#toc7.1">IP addresses</A> 18: </H2> 19: 20:  21: BIRD uses its own abstraction of IP address in order to share the same 22: code for both IPv4 and IPv6. IP addresses are represented as entities 23: of type ip_addr which are never to be treated as numbers and instead 24: they must be manipulated using the following functions and macros. 25:  26: <HR><H3>Function</H3> 27: char * 28: ip_scope_text 29: (uint scope) -- get textual representation of address scope 30:  31: <H3>Arguments</H3> 32:  33: <DL> 34: <DT>uint scope<DD>scope (SCOPE_xxx) 35: </DL> 36: <H3>Description</H3> 37: Returns a pointer to a textual name of the scope given. 38: 39: 40: <HR><H3>Function</H3> 41: int 42: ipa_equal 43: (ip_addr x, ip_addr y) -- compare two IP addresses for equality 44:  45: <H3>Arguments</H3> 46:  47: <DL> 48: <DT>ip_addr x<DD>IP address 49: <DT>ip_addr y<DD>IP address 50: </DL> 51: <H3>Description</H3> 52: ipa_equal() returns 1 if x and y represent the same IP address, else 0. 53: 54: 55: <HR><H3>Function</H3> 56: int 57: ipa_nonzero 58: (ip_addr x) -- test if an IP address is defined 59:  60: <H3>Arguments</H3> 61:  62: <DL> 63: <DT>ip_addr x<DD>IP address 64: </DL> 65: <H3>Description</H3> 66: ipa_nonzero returns 1 if x is a defined IP address (not all bits are zero), 67: else 0. 68: The undefined all-zero address is reachable as a <CODE>IPA_NONE</CODE> macro. 69: 70: 71: <HR><H3>Function</H3> 72: ip_addr 73: ipa_and 74: (ip_addr x, ip_addr y) -- compute bitwise and of two IP addresses 75:  76: <H3>Arguments</H3> 77:  78: <DL> 79: <DT>ip_addr x<DD>IP address 80: <DT>ip_addr y<DD>IP address 81: </DL> 82: <H3>Description</H3> 83: This function returns a bitwise and of x and y. It's primarily 84: used for network masking. 85: 86: 87: <HR><H3>Function</H3> 88: ip_addr 89: ipa_or 90: (ip_addr x, ip_addr y) -- compute bitwise or of two IP addresses 91:  92: <H3>Arguments</H3> 93:  94: <DL> 95: <DT>ip_addr x<DD>IP address 96: <DT>ip_addr y<DD>IP address 97: </DL> 98: <H3>Description</H3> 99: This function returns a bitwise or of x and y. 100: 101: 102: <HR><H3>Function</H3> 103: ip_addr 104: ipa_xor 105: (ip_addr x, ip_addr y) -- compute bitwise xor of two IP addresses 106:  107: <H3>Arguments</H3> 108:  109: <DL> 110: <DT>ip_addr x<DD>IP address 111: <DT>ip_addr y<DD>IP address 112: </DL> 113: <H3>Description</H3> 114: This function returns a bitwise xor of x and y. 115: 116: 117: <HR><H3>Function</H3> 118: ip_addr 119: ipa_not 120: (ip_addr x) -- compute bitwise negation of two IP addresses 121:  122: <H3>Arguments</H3> 123:  124: <DL> 125: <DT>ip_addr x<DD>IP address 126: </DL> 127: <H3>Description</H3> 128: This function returns a bitwise negation of x. 129: 130: 131: <HR><H3>Function</H3> 132: ip_addr 133: ipa_mkmask 134: (int x) -- create a netmask 135:  136: <H3>Arguments</H3> 137:  138: <DL> 139: <DT>int x<DD>prefix length 140: </DL> 141: <H3>Description</H3> 142: This function returns an ip_addr corresponding of a netmask 143: of an address prefix of size x. 144: 145: 146: <HR><H3>Function</H3> 147: int 148: ipa_masklen 149: (ip_addr x) -- calculate netmask length 150:  151: <H3>Arguments</H3> 152:  153: <DL> 154: <DT>ip_addr x<DD>IP address 155: </DL> 156: <H3>Description</H3> 157: This function checks whether x represents a valid netmask and 158: returns the size of the associate network prefix or -1 for invalid 159: mask. 160: 161: 162: <HR><H3>Function</H3> 163: int 164: ipa_hash 165: (ip_addr x) -- hash IP addresses 166:  167: <H3>Arguments</H3> 168:  169: <DL> 170: <DT>ip_addr x<DD>IP address 171: </DL> 172: <H3>Description</H3> 173: ipa_hash() returns a 16-bit hash value of the IP address x. 174: 175: 176: <HR><H3>Function</H3> 177: void 178: ipa_hton 179: (ip_addr x) -- convert IP address to network order 180:  181: <H3>Arguments</H3> 182:  183: <DL> 184: <DT>ip_addr x<DD>IP address 185: </DL> 186: <H3>Description</H3> 187: Converts the IP address x to the network byte order. 188: Beware, this is a macro and it alters the argument! 189: 190: 191: <HR><H3>Function</H3> 192: void 193: ipa_ntoh 194: (ip_addr x) -- convert IP address to host order 195:  196: <H3>Arguments</H3> 197:  198: <DL> 199: <DT>ip_addr x<DD>IP address 200: </DL> 201: <H3>Description</H3> 202: Converts the IP address x from the network byte order. 203: Beware, this is a macro and it alters the argument! 204: 205: 206: <HR><H3>Function</H3> 207: int 208: ipa_classify 209: (ip_addr x) -- classify an IP address 210:  211: <H3>Arguments</H3> 212:  213: <DL> 214: <DT>ip_addr x<DD>IP address 215: </DL> 216: <H3>Description</H3> 217: ipa_classify() returns an address class of x, that is a bitwise or 218: of address type (IADDR_INVALID, IADDR_HOST, IADDR_BROADCAST, IADDR_MULTICAST) 219: with address scope (SCOPE_HOST to SCOPE_UNIVERSE) or -1 (IADDR_INVALID) 220: for an invalid address. 221: 222: 223: <HR><H3>Function</H3> 224: ip4_addr 225: ip4_class_mask 226: (ip4_addr x) -- guess netmask according to address class 227:  228: <H3>Arguments</H3> 229:  230: <DL> 231: <DT>ip4_addr x<DD>IPv4 address 232: </DL> 233: <H3>Description</H3> 234: This function (available in IPv4 version only) returns a 235: network mask according to the address class of x. Although 236: classful addressing is nowadays obsolete, there still live 237: routing protocols transferring no prefix lengths nor netmasks 238: and this function could be useful to them. 239: 240: 241: <HR><H3>Function</H3> 242: u32 243: ipa_from_u32 244: (ip_addr x) -- convert IPv4 address to an integer 245:  246: <H3>Arguments</H3> 247:  248: <DL> 249: <DT>ip_addr x<DD>IP address 250: </DL> 251: <H3>Description</H3> 252: This function takes an IPv4 address and returns its numeric 253: representation. 254: 255: 256: <HR><H3>Function</H3> 257: ip_addr 258: ipa_to_u32 259: (u32 x) -- convert integer to IPv4 address 260:  261: <H3>Arguments</H3> 262:  263: <DL> 264: <DT>u32 x<DD>a 32-bit integer 265: </DL> 266: <H3>Description</H3> 267: ipa_to_u32() takes a numeric representation of an IPv4 address 268: and converts it to the corresponding ip_addr. 269: 270: 271: <HR><H3>Function</H3> 272: int 273: ipa_compare 274: (ip_addr x, ip_addr y) -- compare two IP addresses for order 275:  276: <H3>Arguments</H3> 277:  278: <DL> 279: <DT>ip_addr x<DD>IP address 280: <DT>ip_addr y<DD>IP address 281: </DL> 282: <H3>Description</H3> 283: The ipa_compare() function takes two IP addresses and returns 284: -1 if x is less than y in canonical ordering (lexicographical 285: order of the bit strings), 1 if x is greater than y and 0 286: if they are the same. 287: 288: 289: <HR><H3>Function</H3> 290: ip_addr 291: ipa_build6 292: (u32 a1, u32 a2, u32 a3, u32 a4) -- build an IPv6 address from parts 293:  294: <H3>Arguments</H3> 295:  296: <DL> 297: <DT>u32 a1<DD>part #1 298: <DT>u32 a2<DD>part #2 299: <DT>u32 a3<DD>part #3 300: <DT>u32 a4<DD>part #4 301: </DL> 302: <H3>Description</H3> 303: ipa_build() takes a1 to a4 and assembles them to a single IPv6 304: address. It's used for example when a protocol wants to bind its 305: socket to a hard-wired multicast address. 306: 307: 308: <HR><H3>Function</H3> 309: char * 310: ip_ntop 311: (ip_addr a, char * buf) -- convert IP address to textual representation 312:  313: <H3>Arguments</H3> 314:  315: <DL> 316: <DT>ip_addr a<DD>IP address 317: <DT>char * buf<DD>buffer of size at least STD_ADDRESS_P_LENGTH 318: </DL> 319: <H3>Description</H3> 320: This function takes an IP address and creates its textual 321: representation for presenting to the user. 322: 323: 324: <HR><H3>Function</H3> 325: char * 326: ip_ntox 327: (ip_addr a, char * buf) -- convert IP address to hexadecimal representation 328:  329: <H3>Arguments</H3> 330:  331: <DL> 332: <DT>ip_addr a<DD>IP address 333: <DT>char * buf<DD>buffer of size at least STD_ADDRESS_P_LENGTH 334: </DL> 335: <H3>Description</H3> 336: This function takes an IP address and creates its hexadecimal 337: textual representation. Primary use: debugging dumps. 338: 339: 340: <HR><H3>Function</H3> 341: int 342: ip_pton 343: (char * a, ip_addr * o) -- parse textual representation of IP address 344:  345: <H3>Arguments</H3> 346:  347: <DL> 348: <DT>char * a<DD>textual representation 349: <DT>ip_addr * o<DD>where to put the resulting address 350: </DL> 351: <H3>Description</H3> 352: This function parses a textual IP address representation and 353: stores the decoded address to a variable pointed to by o. 354: Returns 0 if a parse error has occurred, else 0. 355: 356: <H2><A NAME="ss7.2">7.2</A> <A HREF="prog.html#toc7.2">Linked lists</A> 357: </H2> 358: 359:  360: The BIRD library provides a set of functions for operating on linked 361: lists. The lists are internally represented as standard doubly linked 362: lists with synthetic head and tail which makes all the basic operations 363: run in constant time and contain no extra end-of-list checks. Each list 364: is described by a list structure, nodes can have any format as long 365: as they start with a node structure. If you want your nodes to belong 366: to multiple lists at once, you can embed multiple node structures in them 367: and use the SKIP_BACK() macro to calculate a pointer to the start of the 368: structure from a node pointer, but beware of obscurity. 369: There also exist safe linked lists (slist, snode and all functions 370: being prefixed with <CODE>s_</CODE>) which support asynchronous walking very 371: similar to that used in the fib structure. 372:  373: <HR><H3>Function</H3> 374: LIST_INLINE void 375: add_tail 376: (list * l, node * n) -- append a node to a list 377:  378: <H3>Arguments</H3> 379:  380: <DL> 381: <DT>list * l<DD>linked list 382: <DT>node * n<DD>list node 383: </DL> 384: <H3>Description</H3> 385: add_tail() takes a node n and appends it at the end of the list l. 386: 387: 388: <HR><H3>Function</H3> 389: LIST_INLINE void 390: add_head 391: (list * l, node * n) -- prepend a node to a list 392:  393: <H3>Arguments</H3> 394:  395: <DL> 396: <DT>list * l<DD>linked list 397: <DT>node * n<DD>list node 398: </DL> 399: <H3>Description</H3> 400: add_head() takes a node n and prepends it at the start of the list l. 401: 402: 403: <HR><H3>Function</H3> 404: LIST_INLINE void 405: insert_node 406: (node * n, node * after) -- insert a node to a list 407:  408: <H3>Arguments</H3> 409:  410: <DL> 411: <DT>node * n<DD>a new list node 412: <DT>node * after<DD>a node of a list 413: </DL> 414: <H3>Description</H3> 415: Inserts a node n to a linked list after an already inserted 416: node after. 417: 418: 419: <HR><H3>Function</H3> 420: LIST_INLINE void 421: rem_node 422: (node * n) -- remove a node from a list 423:  424: <H3>Arguments</H3> 425:  426: <DL> 427: <DT>node * n<DD>node to be removed 428: </DL> 429: <H3>Description</H3> 430: Removes a node n from the list it's linked in. Afterwards, node n is cleared. 431: 432: 433: <HR><H3>Function</H3> 434: LIST_INLINE void 435: replace_node 436: (node * old, node * new) -- replace a node in a list with another one 437:  438: <H3>Arguments</H3> 439:  440: <DL> 441: <DT>node * old<DD>node to be removed 442: <DT>node * new<DD>node to be inserted 443: </DL> 444: <H3>Description</H3> 445: Replaces node old in the list it's linked in with node new. Node 446: old may be a copy of the original node, which is not accessed 447: through the list. The function could be called with old == new, 448: which just fixes neighbors' pointers in the case that the node 449: was reallocated. 450: 451: 452: <HR><H3>Function</H3> 453: LIST_INLINE void 454: init_list 455: (list * l) -- create an empty list 456:  457: <H3>Arguments</H3> 458:  459: <DL> 460: <DT>list * l<DD>list 461: </DL> 462: <H3>Description</H3> 463: init_list() takes a list structure and initializes its 464: fields, so that it represents an empty list. 465: 466: 467: <HR><H3>Function</H3> 468: LIST_INLINE void 469: add_tail_list 470: (list * to, list * l) -- concatenate two lists 471:  472: <H3>Arguments</H3> 473:  474: <DL> 475: <DT>list * to<DD>destination list 476: <DT>list * l<DD>source list 477: </DL> 478: <H3>Description</H3> 479: This function appends all elements of the list l to 480: the list to in constant time. 481: 482: <H2><A NAME="ss7.3">7.3</A> <A HREF="prog.html#toc7.3">Miscellaneous functions.</A> 483: </H2> 484: 485:  486:  487: <HR><H3>Function</H3> 488: int 489: ipsum_verify 490: (void * frag, uint len, ... ...) -- verify an IP checksum 491:  492: <H3>Arguments</H3> 493:  494: <DL> 495: <DT>void * frag<DD>first packet fragment 496: <DT>uint len<DD>length in bytes 497: <DT>... ...<DD>variable arguments 498: </DL> 499: <H3>Description</H3> 500: This function verifies whether a given fragmented packet 501: has correct one's complement checksum as used by the IP 502: protocol. 503: It uses all the clever tricks described in RFC 1071 to speed 504: up checksum calculation as much as possible. 505: <H3>Result</H3> 506: 1 if the checksum is correct, 0 else. 507: 508: 509: <HR><H3>Function</H3> 510: u16 511: ipsum_calculate 512: (void * frag, uint len, ... ...) -- compute an IP checksum 513:  514: <H3>Arguments</H3> 515:  516: <DL> 517: <DT>void * frag<DD>first packet fragment 518: <DT>uint len<DD>length in bytes 519: <DT>... ...<DD>variable arguments 520: </DL> 521: <H3>Description</H3> 522: This function calculates a one's complement checksum of a given fragmented 523: packet. 524: It uses all the clever tricks described in RFC 1071 to speed 525: up checksum calculation as much as possible. 526: 527: 528: <HR><H3>Function</H3> 529: u32 530: u32_mkmask 531: (uint n) -- create a bit mask 532:  533: <H3>Arguments</H3> 534:  535: <DL> 536: <DT>uint n<DD>number of bits 537: </DL> 538: <H3>Description</H3> 539: u32_mkmask() returns an unsigned 32-bit integer which binary 540: representation consists of n ones followed by zeroes. 541: 542: 543: <HR><H3>Function</H3> 544: int 545: u32_masklen 546: (u32 x) -- calculate length of a bit mask 547:  548: <H3>Arguments</H3> 549:  550: <DL> 551: <DT>u32 x<DD>bit mask 552: </DL> 553: <H3>Description</H3> 554: This function checks whether the given integer x represents 555: a valid bit mask (binary representation contains first ones, then 556: zeroes) and returns the number of ones or -1 if the mask is invalid. 557: 558: 559: <HR><H3>Function</H3> 560: u32 561: u32_log2 562: (u32 v) -- compute a binary logarithm. 563:  564: <H3>Arguments</H3> 565:  566: <DL> 567: <DT>u32 v<DD>number 568: </DL> 569: <H3>Description</H3> 570: This function computes a integral part of binary logarithm of given 571: integer v and returns it. The computed value is also an index of the 572: most significant non-zero bit position. 573: 574: 575: <HR><H3>Function</H3> 576: int 577: patmatch 578: (byte * p, byte * s) -- match shell-like patterns 579:  580: <H3>Arguments</H3> 581:  582: <DL> 583: <DT>byte * p<DD>pattern 584: <DT>byte * s<DD>string 585: </DL> 586: <H3>Description</H3> 587: patmatch() returns whether given string s matches the given shell-like 588: pattern p. The patterns consist of characters (which are matched literally), 589: question marks which match any single character, asterisks which match any 590: (possibly empty) string of characters and backslashes which are used to 591: escape any special characters and force them to be treated literally. 592: The matching process is not optimized with respect to time, so please 593: avoid using this function for complex patterns. 594: 595: 596: <HR><H3>Function</H3> 597: int 598: bvsnprintf 599: (char * buf, int size, const char * fmt, va_list args) -- BIRD's vsnprintf() 600:  601: <H3>Arguments</H3> 602:  603: <DL> 604: <DT>char * buf<DD>destination buffer 605: <DT>int size<DD>size of the buffer 606: <DT>const char * fmt<DD>format string 607: <DT>va_list args<DD>a list of arguments to be formatted 608: </DL> 609: <H3>Description</H3> 610: This functions acts like ordinary sprintf() except that it checks 611: available space to avoid buffer overflows and it allows some more 612: <H3>format specifiers</H3> 613: <CODE>I</CODE> for formatting of IP addresses (any non-zero 614: width is automatically replaced by standard IP address width which 615: depends on whether we use IPv4 or IPv6; <CODE>%#I</CODE> gives hexadecimal format), 616: <CODE>R</CODE> for Router / Network ID (u32 value printed as IPv4 address) 617: <CODE>lR</CODE> for 64bit Router / Network ID (u64 value printed as eight :-separated octets) 618: and <CODE>m</CODE> resp. <CODE>M</CODE> for error messages (uses strerror() to translate errno code to 619: message text). On the other hand, it doesn't support floating 620: point numbers. 621: <H3>Result</H3> 622: number of characters of the output string or -1 if 623: the buffer space was insufficient. 624: 625: 626: <HR><H3>Function</H3> 627: int 628: bvsprintf 629: (char * buf, const char * fmt, va_list args) -- BIRD's vsprintf() 630:  631: <H3>Arguments</H3> 632:  633: <DL> 634: <DT>char * buf<DD>buffer 635: <DT>const char * fmt<DD>format string 636: <DT>va_list args<DD>a list of arguments to be formatted 637: </DL> 638: <H3>Description</H3> 639: This function is equivalent to bvsnprintf() with an infinite 640: buffer size. Please use carefully only when you are absolutely 641: sure the buffer won't overflow. 642: 643: 644: <HR><H3>Function</H3> 645: int 646: bsprintf 647: (char * buf, const char * fmt, ... ...) -- BIRD's sprintf() 648:  649: <H3>Arguments</H3> 650:  651: <DL> 652: <DT>char * buf<DD>buffer 653: <DT>const char * fmt<DD>format string 654: <DT>... ...<DD>variable arguments 655: </DL> 656: <H3>Description</H3> 657: This function is equivalent to bvsnprintf() with an infinite 658: buffer size and variable arguments instead of a va_list. 659: Please use carefully only when you are absolutely 660: sure the buffer won't overflow. 661: 662: 663: <HR><H3>Function</H3> 664: int 665: bsnprintf 666: (char * buf, int size, const char * fmt, ... ...) -- BIRD's snprintf() 667:  668: <H3>Arguments</H3> 669:  670: <DL> 671: <DT>char * buf<DD>buffer 672: <DT>int size<DD>buffer size 673: <DT>const char * fmt<DD>format string 674: <DT>... ...<DD>variable arguments 675: </DL> 676: <H3>Description</H3> 677: This function is equivalent to bsnprintf() with variable arguments instead of a va_list. 678: 679: 680: <HR><H3>Function</H3> 681: void * 682: xmalloc 683: (uint size) -- malloc with checking 684:  685: <H3>Arguments</H3> 686:  687: <DL> 688: <DT>uint size<DD>block size 689: </DL> 690: <H3>Description</H3> 691: This function is equivalent to malloc() except that in case of 692: failure it calls die() to quit the program instead of returning 693: a NULL pointer. 694: Wherever possible, please use the memory resources instead. 695: 696: 697: <HR><H3>Function</H3> 698: void * 699: xrealloc 700: (void * ptr, uint size) -- realloc with checking 701:  702: <H3>Arguments</H3> 703:  704: <DL> 705: <DT>void * ptr<DD>original memory block 706: <DT>uint size<DD>block size 707: </DL> 708: <H3>Description</H3> 709: This function is equivalent to realloc() except that in case of 710: failure it calls die() to quit the program instead of returning 711: a NULL pointer. 712: Wherever possible, please use the memory resources instead. 713: 714: <H2><A NAME="ss7.4">7.4</A> <A HREF="prog.html#toc7.4">Message authentication codes</A> 715: </H2> 716: 717:  718: MAC algorithms are simple cryptographic tools for message authentication. 719: They use shared a secret key a and message text to generate authentication 720: code, which is then passed with the message to the other side, where the code 721: is verified. There are multiple families of MAC algorithms based on different 722: cryptographic primitives, BIRD implements two MAC families which use hash 723: functions. 724: The first family is simply a cryptographic hash camouflaged as MAC algorithm. 725: Originally supposed to be (m|k)-hash (message is concatenated with key, and 726: that is hashed), but later it turned out that a raw hash is more practical. 727: This is used for cryptographic authentication in OSPFv2, RIP and BFD. 728: The second family is the standard HMAC (RFC 2104), using inner and outer hash 729: to process key and message. HMAC (with SHA) is used in advanced OSPF and RIP 730: authentication (RFC 5709, RFC 4822). 731:  732: <HR><H3>Function</H3> 733: void 734: mac_init 735: (struct mac_context * ctx, uint id, const byte * key, uint keylen) -- initialize MAC algorithm 736:  737: <H3>Arguments</H3> 738:  739: <DL> 740: <DT>struct mac_context * ctx<DD>context to initialize 741: <DT>uint id<DD>MAC algorithm ID 742: <DT>const byte * key<DD>MAC key 743: <DT>uint keylen<DD>MAC key length 744: </DL> 745: <H3>Description</H3> 746: Initialize MAC context ctx for algorithm id (e.g., ALG_HMAC_SHA1), with 747: key key of length keylen. After that, message data could be added using 748: mac_update() function. 749: 750: 751: <HR><H3>Function</H3> 752: void 753: mac_update 754: (struct mac_context * ctx, const byte * data, uint datalen) -- add more data to MAC algorithm 755:  756: <H3>Arguments</H3> 757:  758: <DL> 759: <DT>struct mac_context * ctx<DD>MAC context 760: <DT>const byte * data<DD>data to add 761: <DT>uint datalen<DD>length of data 762: </DL> 763: <H3>Description</H3> 764: Push another datalen bytes of data pointed to by data into the MAC 765: algorithm currently in ctx. Can be called multiple times for the same MAC 766: context. It has the same effect as concatenating all the data together and 767: passing them at once. 768: 769: 770: <HR><H3>Function</H3> 771: byte * 772: mac_final 773: (struct mac_context * ctx) -- finalize MAC algorithm 774:  775: <H3>Arguments</H3> 776:  777: <DL> 778: <DT>struct mac_context * ctx<DD>MAC context 779: </DL> 780: <H3>Description</H3> 781: Finish MAC computation and return a pointer to the result. No more 782: mac_update() calls could be done, but the context may be reinitialized 783: later. 784: Note that the returned pointer points into data in the ctx context. If it 785: ceases to exist, the pointer becomes invalid. 786: 787: 788: <HR><H3>Function</H3> 789: void 790: mac_cleanup 791: (struct mac_context * ctx) -- cleanup MAC context 792:  793: <H3>Arguments</H3> 794:  795: <DL> 796: <DT>struct mac_context * ctx<DD>MAC context 797: </DL> 798: <H3>Description</H3> 799: Cleanup MAC context after computation (by filling with zeros). Not strictly 800: necessary, just to erase sensitive data from stack. This also invalidates the 801: pointer returned by mac_final(). 802: 803: 804: <HR><H3>Function</H3> 805: void 806: mac_fill 807: (uint id, const byte * key, uint keylen, const byte * data, uint datalen, byte * mac) -- compute and fill MAC 808:  809: <H3>Arguments</H3> 810:  811: <DL> 812: <DT>uint id<DD>MAC algorithm ID 813: <DT>const byte * key<DD>secret key 814: <DT>uint keylen<DD>key length 815: <DT>const byte * data<DD>message data 816: <DT>uint datalen<DD>message length 817: <DT>byte * mac<DD>place to fill MAC 818: </DL> 819: <H3>Description</H3> 820: Compute MAC for specified key key and message data using algorithm id and 821: copy it to buffer mac. mac_fill() is a shortcut function doing all usual 822: steps for transmitted messages. 823: 824: 825: <HR><H3>Function</H3> 826: int 827: mac_verify 828: (uint id, const byte * key, uint keylen, const byte * data, uint datalen, const byte * mac) -- compute and verify MAC 829:  830: <H3>Arguments</H3> 831:  832: <DL> 833: <DT>uint id<DD>MAC algorithm ID 834: <DT>const byte * key<DD>secret key 835: <DT>uint keylen<DD>key length 836: <DT>const byte * data<DD>message data 837: <DT>uint datalen<DD>message length 838: <DT>const byte * mac<DD>received MAC 839: </DL> 840: <H3>Description</H3> 841: Compute MAC for specified key key and message data using algorithm id and 842: compare it with received mac, return whether they are the same. mac_verify() 843: is a shortcut function doing all usual steps for received messages. 844: 845:  846: <HR> 847: <A HREF="prog-8.html">Next</A> 848: <A HREF="prog-6.html">Previous</A> 849: <A HREF="prog.html#toc7">Contents</A> 850: </BODY> 851: </HTML>