00001 /* 00002 * lib/attr.c Netlink Attributes 00003 * 00004 * This library is free software; you can redistribute it and/or 00005 * modify it under the terms of the GNU Lesser General Public 00006 * License as published by the Free Software Foundation version 2.1 00007 * of the License. 00008 * 00009 * Copyright (c) 2003-2008 Thomas Graf <tgraf@suug.ch> 00010 */ 00011 00012 #include <netlink-local.h> 00013 #include <netlink/netlink.h> 00014 #include <netlink/utils.h> 00015 #include <netlink/addr.h> 00016 #include <netlink/attr.h> 00017 #include <netlink/msg.h> 00018 #include <linux/socket.h> 00019 00020 /** 00021 * @ingroup msg 00022 * @defgroup attr Attributes 00023 * Netlink Attributes Construction/Parsing Interface 00024 * 00025 * \section attr_sec Netlink Attributes 00026 * Netlink attributes allow for data chunks of arbitary length to be 00027 * attached to a netlink message. Each attribute is encoded with a 00028 * type and length field, both 16 bits, stored in the attribute header 00029 * preceding the attribute data. The main advantage of using attributes 00030 * over packing everything into the family header is that the interface 00031 * stays extendable as new attributes can supersede old attributes while 00032 * remaining backwards compatible. Also attributes can be defined optional 00033 * thus avoiding the transmission of unnecessary empty data blocks. 00034 * Special nested attributes allow for more complex data structures to 00035 * be transmitted, e.g. trees, lists, etc. 00036 * 00037 * While not required, netlink attributes typically follow the family 00038 * header of a netlink message and must be properly aligned to NLA_ALIGNTO: 00039 * @code 00040 * +----------------+- - -+---------------+- - -+------------+- - -+ 00041 * | Netlink Header | Pad | Family Header | Pad | Attributes | Pad | 00042 * +----------------+- - -+---------------+- - -+------------+- - -+ 00043 * @endcode 00044 * 00045 * The actual attributes are chained together each separately aligned to 00046 * NLA_ALIGNTO. The position of an attribute is defined based on the 00047 * length field of the preceding attributes: 00048 * @code 00049 * +-------------+- - -+-------------+- - -+------ 00050 * | Attribute 1 | Pad | Attribute 2 | Pad | ... 00051 * +-------------+- - -+-------------+- - -+------ 00052 * nla_next(attr1)------^ 00053 * @endcode 00054 * 00055 * The attribute itself consists of the attribute header followed by 00056 * the actual payload also aligned to NLA_ALIGNTO. The function nla_data() 00057 * returns a pointer to the start of the payload while nla_len() returns 00058 * the length of the payload in bytes. 00059 * 00060 * \b Note: Be aware, NLA_ALIGNTO equals to 4 bytes, therefore it is not 00061 * safe to dereference any 64 bit data types directly. 00062 * 00063 * @code 00064 * <----------- nla_total_size(payload) -----------> 00065 * <-------- nla_attr_size(payload) ---------> 00066 * +------------------+- - -+- - - - - - - - - +- - -+ 00067 * | Attribute Header | Pad | Payload | Pad | 00068 * +------------------+- - -+- - - - - - - - - +- - -+ 00069 * nla_data(nla)-------------^ 00070 * <- nla_len(nla) -> 00071 * @endcode 00072 * 00073 * @subsection attr_datatypes Attribute Data Types 00074 * A number of basic data types are supported to simplify access and 00075 * validation of netlink attributes. This data type information is 00076 * not encoded in the attribute, both the kernel and userspace part 00077 * are required to share this information on their own. 00078 * 00079 * One of the major advantages of these basic types is the automatic 00080 * validation of each attribute based on an attribute policy. The 00081 * validation covers most of the checks required to safely use 00082 * attributes and thus keeps the individual sanity check to a minimum. 00083 * 00084 * Never access attribute payload without ensuring basic validation 00085 * first, attributes may: 00086 * - not be present even though required 00087 * - contain less actual payload than expected 00088 * - fake a attribute length which exceeds the end of the message 00089 * - contain unterminated character strings 00090 * 00091 * Policies are defined as array of the struct nla_policy. The array is 00092 * indexed with the attribute type, therefore the array must be sized 00093 * accordingly. 00094 * @code 00095 * static struct nla_policy my_policy[ATTR_MAX+1] = { 00096 * [ATTR_FOO] = { .type = ..., .minlen = ..., .maxlen = ... }, 00097 * }; 00098 * 00099 * err = nla_validate(attrs, attrlen, ATTR_MAX, &my_policy); 00100 * @endcode 00101 * 00102 * Some basic validations are performed on every attribute, regardless of type. 00103 * - If the attribute type exceeds the maximum attribute type specified or 00104 * the attribute type is lesser-or-equal than zero, the attribute will 00105 * be silently ignored. 00106 * - If the payload length falls below the \a minlen value the attribute 00107 * will be rejected. 00108 * - If \a maxlen is non-zero and the payload length exceeds the \a maxlen 00109 * value the attribute will be rejected. 00110 * 00111 * 00112 * @par Unspecific Attribute (NLA_UNSPEC) 00113 * This is the standard type if no type is specified. It is used for 00114 * binary data of arbitary length. Typically this attribute carries 00115 * a binary structure or a stream of bytes. 00116 * @par 00117 * @code 00118 * // In this example, we will assume a binary structure requires to 00119 * // be transmitted. The definition of the structure will typically 00120 * // go into a header file available to both the kernel and userspace 00121 * // side. 00122 * // 00123 * // Note: Be careful when putting 64 bit data types into a structure. 00124 * // The attribute payload is only aligned to 4 bytes, dereferencing 00125 * // the member may fail. 00126 * struct my_struct { 00127 * int a; 00128 * int b; 00129 * }; 00130 * 00131 * // The validation function will not enforce an exact length match to 00132 * // allow structures to grow as required. Note: While it is allowed 00133 * // to add members to the end of the structure, changing the order or 00134 * // inserting members in the middle of the structure will break your 00135 * // binary interface. 00136 * static struct nla_policy my_policy[ATTR_MAX+1] = { 00137 * [ATTR_MY_STRICT] = { .type = NLA_UNSPEC, 00138 * .minlen = sizeof(struct my_struct) }, 00139 * 00140 * // The binary structure is appened to the message using nla_put() 00141 * struct my_struct foo = { .a = 1, .b = 2 }; 00142 * nla_put(msg, ATTR_MY_STRUCT, sizeof(foo), &foo); 00143 * 00144 * // On the receiving side, a pointer to the structure pointing inside 00145 * // the message payload is returned by nla_get(). 00146 * if (attrs[ATTR_MY_STRUCT]) 00147 * struct my_struct *foo = nla_get(attrs[ATTR_MY_STRUCT]); 00148 * @endcode 00149 * 00150 * @par Integers (NLA_U8, NLA_U16, NLA_U32, NLA_U64) 00151 * Integers come in different sizes from 8 bit to 64 bit. However, since the 00152 * payload length is aligned to 4 bytes, integers smaller than 32 bit are 00153 * only useful to enforce the maximum range of values. 00154 * @par 00155 * \b Note: There is no difference made between signed and unsigned integers. 00156 * The validation only enforces the minimal payload length required to store 00157 * an integer of specified type. 00158 * @par 00159 * @code 00160 * // Even though possible, it does not make sense to specify .minlen or 00161 * // .maxlen for integer types. The data types implies the corresponding 00162 * // minimal payload length. 00163 * static struct nla_policy my_policy[ATTR_MAX+1] = { 00164 * [ATTR_FOO] = { .type = NLA_U32 }, 00165 * 00166 * // Numeric values can be appended directly using the respective 00167 * // nla_put_uxxx() function 00168 * nla_put_u32(msg, ATTR_FOO, 123); 00169 * 00170 * // Same for the receiving side. 00171 * if (attrs[ATTR_FOO]) 00172 * uint32_t foo = nla_get_u32(attrs[ATTR_FOO]); 00173 * @endcode 00174 * 00175 * @par Character string (NLA_STRING) 00176 * This data type represents a NUL terminated character string of variable 00177 * length. For binary data streams the type NLA_UNSPEC is recommended. 00178 * @par 00179 * @code 00180 * // Enforce a NUL terminated character string of at most 4 characters 00181 * // including the NUL termination. 00182 * static struct nla_policy my_policy[ATTR_MAX+1] = { 00183 * [ATTR_BAR] = { .type = NLA_STRING, maxlen = 4 }, 00184 * 00185 * // nla_put_string() creates a string attribute of the necessary length 00186 * // and appends it to the message including the NUL termination. 00187 * nla_put_string(msg, ATTR_BAR, "some text"); 00188 * 00189 * // It is safe to use the returned character string directly if the 00190 * // attribute has been validated as the validation enforces the proper 00191 * // termination of the string. 00192 * if (attrs[ATTR_BAR]) 00193 * char *text = nla_get_string(attrs[ATTR_BAR]); 00194 * @endcode 00195 * 00196 * @par Flag (NLA_FLAG) 00197 * This attribute type may be used to indicate the presence of a flag. The 00198 * attribute is only valid if the payload length is zero. The presence of 00199 * the attribute header indicates the presence of the flag. 00200 * @par 00201 * @code 00202 * // This attribute type is special as .minlen and .maxlen have no effect. 00203 * static struct nla_policy my_policy[ATTR_MAX+1] = { 00204 * [ATTR_FLAG] = { .type = NLA_FLAG }, 00205 * 00206 * // nla_put_flag() appends a zero sized attribute to the message. 00207 * nla_put_flag(msg, ATTR_FLAG); 00208 * 00209 * // There is no need for a receival function, the presence is the value. 00210 * if (attrs[ATTR_FLAG]) 00211 * // flag is present 00212 * @endcode 00213 * 00214 * @par Micro Seconds (NLA_MSECS) 00215 * 00216 * @par Nested Attribute (NLA_NESTED) 00217 * Attributes can be nested and put into a container to create groups, lists 00218 * or to construct trees of attributes. Nested attributes are often used to 00219 * pass attributes to a subsystem where the top layer has no knowledge of the 00220 * configuration possibilities of each subsystem. 00221 * @par 00222 * \b Note: When validating the attributes using nlmsg_validate() or 00223 * nlmsg_parse() it will only affect the top level attributes. Each 00224 * level of nested attributes must be validated seperately using 00225 * nla_parse_nested() or nla_validate(). 00226 * @par 00227 * @code 00228 * // The minimal length policy may be used to enforce the presence of at 00229 * // least one attribute. 00230 * static struct nla_policy my_policy[ATTR_MAX+1] = { 00231 * [ATTR_OPTS] = { .type = NLA_NESTED, minlen = NLA_HDRLEN }, 00232 * 00233 * // Nested attributes are constructed by enclosing the attributes 00234 * // to be nested with calls to nla_nest_start() respetively nla_nest_end(). 00235 * struct nlattr *opts = nla_nest_start(msg, ATTR_OPTS); 00236 * nla_put_u32(msg, ATTR_FOO, 123); 00237 * nla_put_string(msg, ATTR_BAR, "some text"); 00238 * nla_nest_end(msg, opts); 00239 * 00240 * // Various methods exist to parse nested attributes, the easiest being 00241 * // nla_parse_nested() which also allows validation in the same step. 00242 * if (attrs[ATTR_OPTS]) { 00243 * struct nlattr *nested[ATTR_MAX+1]; 00244 * 00245 * nla_parse_nested(nested, ATTR_MAX, attrs[ATTR_OPTS], &policy); 00246 * 00247 * if (nested[ATTR_FOO]) 00248 * uint32_t foo = nla_get_u32(nested[ATTR_FOO]); 00249 * } 00250 * @endcode 00251 * 00252 * @subsection attr_exceptions Exception Based Attribute Construction 00253 * Often a large number of attributes are added to a message in a single 00254 * function. In order to simplify error handling, a second set of 00255 * construction functions exist which jump to a error label when they 00256 * fail instead of returning an error code. This second set consists 00257 * of macros which are named after their error code based counterpart 00258 * except that the name is written all uppercase. 00259 * 00260 * All of the macros jump to the target \c nla_put_failure if they fail. 00261 * @code 00262 * void my_func(struct nl_msg *msg) 00263 * { 00264 * NLA_PUT_U32(msg, ATTR_FOO, 10); 00265 * NLA_PUT_STRING(msg, ATTR_BAR, "bar"); 00266 * 00267 * return 0; 00268 * 00269 * nla_put_failure: 00270 * return -NLE_NOMEM; 00271 * } 00272 * @endcode 00273 * 00274 * @subsection attr_examples Examples 00275 * @par Example 1.1 Constructing a netlink message with attributes. 00276 * @code 00277 * struct nl_msg *build_msg(int ifindex, struct nl_addr *lladdr, int mtu) 00278 * { 00279 * struct nl_msg *msg; 00280 * struct nlattr *info, *vlan; 00281 * struct ifinfomsg ifi = { 00282 * .ifi_family = AF_INET, 00283 * .ifi_index = ifindex, 00284 * }; 00285 * 00286 * // Allocate a new netlink message, type=RTM_SETLINK, flags=NLM_F_ECHO 00287 * if (!(msg = nlmsg_alloc_simple(RTM_SETLINK, NLM_F_ECHO))) 00288 * return NULL; 00289 * 00290 * // Append the family specific header (struct ifinfomsg) 00291 * if (nlmsg_append(msg, &ifi, sizeof(ifi), NLMSG_ALIGNTO) < 0) 00292 * goto nla_put_failure 00293 * 00294 * // Append a 32 bit integer attribute to carry the MTU 00295 * NLA_PUT_U32(msg, IFLA_MTU, mtu); 00296 * 00297 * // Append a unspecific attribute to carry the link layer address 00298 * NLA_PUT_ADDR(msg, IFLA_ADDRESS, lladdr); 00299 * 00300 * // Append a container for nested attributes to carry link information 00301 * if (!(info = nla_nest_start(msg, IFLA_LINKINFO))) 00302 * goto nla_put_failure; 00303 * 00304 * // Put a string attribute into the container 00305 * NLA_PUT_STRING(msg, IFLA_INFO_KIND, "vlan"); 00306 * 00307 * // Append another container inside the open container to carry 00308 * // vlan specific attributes 00309 * if (!(vlan = nla_nest_start(msg, IFLA_INFO_DATA))) 00310 * goto nla_put_failure; 00311 * 00312 * // add vlan specific info attributes here... 00313 * 00314 * // Finish nesting the vlan attributes and close the second container. 00315 * nla_nest_end(msg, vlan); 00316 * 00317 * // Finish nesting the link info attribute and close the first container. 00318 * nla_nest_end(msg, info); 00319 * 00320 * return msg; 00321 * 00322 * // If any of the construction macros fails, we end up here. 00323 * nla_put_failure: 00324 * nlmsg_free(msg); 00325 * return NULL; 00326 * } 00327 * @endcode 00328 * 00329 * @par Example 2.1 Parsing a netlink message with attributes. 00330 * @code 00331 * int parse_message(struct nl_msg *msg) 00332 * { 00333 * // The policy defines two attributes: a 32 bit integer and a container 00334 * // for nested attributes. 00335 * struct nla_policy attr_policy[ATTR_MAX+1] = { 00336 * [ATTR_FOO] = { .type = NLA_U32 }, 00337 * [ATTR_BAR] = { .type = NLA_NESTED }, 00338 * }; 00339 * struct nlattr *attrs[ATTR_MAX+1]; 00340 * int err; 00341 * 00342 * // The nlmsg_parse() function will make sure that the message contains 00343 * // enough payload to hold the header (struct my_hdr), validates any 00344 * // attributes attached to the messages and stores a pointer to each 00345 * // attribute in the attrs[] array accessable by attribute type. 00346 * if ((err = nlmsg_parse(nlmsg_hdr(msg), sizeof(struct my_hdr), attrs, 00347 * ATTR_MAX, attr_policy)) < 0) 00348 * goto errout; 00349 * 00350 * if (attrs[ATTR_FOO]) { 00351 * // It is safe to directly access the attribute payload without 00352 * // any further checks since nlmsg_parse() enforced the policy. 00353 * uint32_t foo = nla_get_u32(attrs[ATTR_FOO]); 00354 * } 00355 * 00356 * if (attrs[ATTR_BAR]) { 00357 * struct nlattr *nested[NESTED_MAX+1]; 00358 * 00359 * // Attributes nested in a container can be parsed the same way 00360 * // as top level attributes. 00361 * if ((err = nla_parse_nested(nested, NESTED_MAX, attrs[ATTR_BAR], 00362 * nested_policy)) < 0) 00363 * goto errout; 00364 * 00365 * // Process nested attributes here. 00366 * } 00367 * 00368 * err = 0; 00369 * errout: 00370 * return err; 00371 * } 00372 * @endcode 00373 * 00374 * @{ 00375 */ 00376 00377 /** 00378 * @name Attribute Size Calculation 00379 * @{ 00380 */ 00381 00382 /** 00383 * Return size of attribute whithout padding. 00384 * @arg payload Payload length of attribute. 00385 * 00386 * @code 00387 * <-------- nla_attr_size(payload) ---------> 00388 * +------------------+- - -+- - - - - - - - - +- - -+ 00389 * | Attribute Header | Pad | Payload | Pad | 00390 * +------------------+- - -+- - - - - - - - - +- - -+ 00391 * @endcode 00392 * 00393 * @return Size of attribute in bytes without padding. 00394 */ 00395 int nla_attr_size(int payload) 00396 { 00397 return NLA_HDRLEN + payload; 00398 } 00399 00400 /** 00401 * Return size of attribute including padding. 00402 * @arg payload Payload length of attribute. 00403 * 00404 * @code 00405 * <----------- nla_total_size(payload) -----------> 00406 * +------------------+- - -+- - - - - - - - - +- - -+ 00407 * | Attribute Header | Pad | Payload | Pad | 00408 * +------------------+- - -+- - - - - - - - - +- - -+ 00409 * @endcode 00410 * 00411 * @return Size of attribute in bytes. 00412 */ 00413 int nla_total_size(int payload) 00414 { 00415 return NLA_ALIGN(nla_attr_size(payload)); 00416 } 00417 00418 /** 00419 * Return length of padding at the tail of the attribute. 00420 * @arg payload Payload length of attribute. 00421 * 00422 * @code 00423 * +------------------+- - -+- - - - - - - - - +- - -+ 00424 * | Attribute Header | Pad | Payload | Pad | 00425 * +------------------+- - -+- - - - - - - - - +- - -+ 00426 * <---> 00427 * @endcode 00428 * 00429 * @return Length of padding in bytes. 00430 */ 00431 int nla_padlen(int payload) 00432 { 00433 return nla_total_size(payload) - nla_attr_size(payload); 00434 } 00435 00436 /** @} */ 00437 00438 /** 00439 * @name Parsing Attributes 00440 * @{ 00441 */ 00442 00443 /** 00444 * Return type of the attribute. 00445 * @arg nla Attribute. 00446 * 00447 * @return Type of attribute. 00448 */ 00449 int nla_type(const struct nlattr *nla) 00450 { 00451 return nla->nla_type & NLA_TYPE_MASK; 00452 } 00453 00454 /** 00455 * Return pointer to the payload section. 00456 * @arg nla Attribute. 00457 * 00458 * @return Pointer to start of payload section. 00459 */ 00460 void *nla_data(const struct nlattr *nla) 00461 { 00462 return (char *) nla + NLA_HDRLEN; 00463 } 00464 00465 /** 00466 * Return length of the payload . 00467 * @arg nla Attribute 00468 * 00469 * @return Length of payload in bytes. 00470 */ 00471 int nla_len(const struct nlattr *nla) 00472 { 00473 return nla->nla_len - NLA_HDRLEN; 00474 } 00475 00476 /** 00477 * Check if the attribute header and payload can be accessed safely. 00478 * @arg nla Attribute of any kind. 00479 * @arg remaining Number of bytes remaining in attribute stream. 00480 * 00481 * Verifies that the header and payload do not exceed the number of 00482 * bytes left in the attribute stream. This function must be called 00483 * before access the attribute header or payload when iterating over 00484 * the attribute stream using nla_next(). 00485 * 00486 * @return True if the attribute can be accessed safely, false otherwise. 00487 */ 00488 int nla_ok(const struct nlattr *nla, int remaining) 00489 { 00490 return remaining >= sizeof(*nla) && 00491 nla->nla_len >= sizeof(*nla) && 00492 nla->nla_len <= remaining; 00493 } 00494 00495 /** 00496 * Return next attribute in a stream of attributes. 00497 * @arg nla Attribute of any kind. 00498 * @arg remaining Variable to count remaining bytes in stream. 00499 * 00500 * Calculates the offset to the next attribute based on the attribute 00501 * given. The attribute provided is assumed to be accessible, the 00502 * caller is responsible to use nla_ok() beforehand. The offset (length 00503 * of specified attribute including padding) is then subtracted from 00504 * the remaining bytes variable and a pointer to the next attribute is 00505 * returned. 00506 * 00507 * nla_next() can be called as long as remainig is >0. 00508 * 00509 * @return Pointer to next attribute. 00510 */ 00511 struct nlattr *nla_next(const struct nlattr *nla, int *remaining) 00512 { 00513 int totlen = NLA_ALIGN(nla->nla_len); 00514 00515 *remaining -= totlen; 00516 return (struct nlattr *) ((char *) nla + totlen); 00517 } 00518 00519 static uint16_t nla_attr_minlen[NLA_TYPE_MAX+1] = { 00520 [NLA_U8] = sizeof(uint8_t), 00521 [NLA_U16] = sizeof(uint16_t), 00522 [NLA_U32] = sizeof(uint32_t), 00523 [NLA_U64] = sizeof(uint64_t), 00524 [NLA_STRING] = 1, 00525 }; 00526 00527 static int validate_nla(struct nlattr *nla, int maxtype, 00528 struct nla_policy *policy) 00529 { 00530 struct nla_policy *pt; 00531 int minlen = 0, type = nla_type(nla); 00532 00533 if (type <= 0 || type > maxtype) 00534 return 0; 00535 00536 pt = &policy[type]; 00537 00538 if (pt->type > NLA_TYPE_MAX) 00539 BUG(); 00540 00541 if (pt->minlen) 00542 minlen = pt->minlen; 00543 else if (pt->type != NLA_UNSPEC) 00544 minlen = nla_attr_minlen[pt->type]; 00545 00546 if (pt->type == NLA_FLAG && nla_len(nla) > 0) 00547 return -NLE_RANGE; 00548 00549 if (nla_len(nla) < minlen) 00550 return -NLE_RANGE; 00551 00552 if (pt->maxlen && nla_len(nla) > pt->maxlen) 00553 return -NLE_RANGE; 00554 00555 if (pt->type == NLA_STRING) { 00556 char *data = nla_data(nla); 00557 if (data[nla_len(nla) - 1] != '\0') 00558 return -NLE_INVAL; 00559 } 00560 00561 return 0; 00562 } 00563 00564 00565 /** 00566 * Create attribute index based on a stream of attributes. 00567 * @arg tb Index array to be filled (maxtype+1 elements). 00568 * @arg maxtype Maximum attribute type expected and accepted. 00569 * @arg head Head of attribute stream. 00570 * @arg len Length of attribute stream. 00571 * @arg policy Attribute validation policy. 00572 * 00573 * Iterates over the stream of attributes and stores a pointer to each 00574 * attribute in the index array using the attribute type as index to 00575 * the array. Attribute with a type greater than the maximum type 00576 * specified will be silently ignored in order to maintain backwards 00577 * compatibility. If \a policy is not NULL, the attribute will be 00578 * validated using the specified policy. 00579 * 00580 * @see nla_validate 00581 * @return 0 on success or a negative error code. 00582 */ 00583 int nla_parse(struct nlattr *tb[], int maxtype, struct nlattr *head, int len, 00584 struct nla_policy *policy) 00585 { 00586 struct nlattr *nla; 00587 int rem, err; 00588 00589 memset(tb, 0, sizeof(struct nlattr *) * (maxtype + 1)); 00590 00591 nla_for_each_attr(nla, head, len, rem) { 00592 int type = nla_type(nla); 00593 00594 if (type == 0) { 00595 fprintf(stderr, "Illegal nla->nla_type == 0\n"); 00596 continue; 00597 } 00598 00599 if (type <= maxtype) { 00600 if (policy) { 00601 err = validate_nla(nla, maxtype, policy); 00602 if (err < 0) 00603 goto errout; 00604 } 00605 00606 tb[type] = nla; 00607 } 00608 } 00609 00610 if (rem > 0) 00611 fprintf(stderr, "netlink: %d bytes leftover after parsing " 00612 "attributes.\n", rem); 00613 00614 err = 0; 00615 errout: 00616 return err; 00617 } 00618 00619 /** 00620 * Validate a stream of attributes. 00621 * @arg head Head of attributes stream. 00622 * @arg len Length of attributes stream. 00623 * @arg maxtype Maximum attribute type expected and accepted. 00624 * @arg policy Validation policy. 00625 * 00626 * Iterates over the stream of attributes and validates each attribute 00627 * one by one using the specified policy. Attributes with a type greater 00628 * than the maximum type specified will be silently ignored in order to 00629 * maintain backwards compatibility. 00630 * 00631 * See \ref attr_datatypes for more details on what kind of validation 00632 * checks are performed on each attribute data type. 00633 * 00634 * @return 0 on success or a negative error code. 00635 */ 00636 int nla_validate(struct nlattr *head, int len, int maxtype, 00637 struct nla_policy *policy) 00638 { 00639 struct nlattr *nla; 00640 int rem, err; 00641 00642 nla_for_each_attr(nla, head, len, rem) { 00643 err = validate_nla(nla, maxtype, policy); 00644 if (err < 0) 00645 goto errout; 00646 } 00647 00648 err = 0; 00649 errout: 00650 return err; 00651 } 00652 00653 /** 00654 * Find a single attribute in a stream of attributes. 00655 * @arg head Head of attributes stream. 00656 * @arg len Length of attributes stream. 00657 * @arg attrtype Attribute type to look for. 00658 * 00659 * Iterates over the stream of attributes and compares each type with 00660 * the type specified. Returns the first attribute which matches the 00661 * type. 00662 * 00663 * @return Pointer to attribute found or NULL. 00664 */ 00665 struct nlattr *nla_find(struct nlattr *head, int len, int attrtype) 00666 { 00667 struct nlattr *nla; 00668 int rem; 00669 00670 nla_for_each_attr(nla, head, len, rem) 00671 if (nla_type(nla) == attrtype) 00672 return nla; 00673 00674 return NULL; 00675 } 00676 00677 /** @} */ 00678 00679 /** 00680 * @name Helper Functions 00681 * @{ 00682 */ 00683 00684 /** 00685 * Copy attribute payload to another memory area. 00686 * @arg dest Pointer to destination memory area. 00687 * @arg src Attribute 00688 * @arg count Number of bytes to copy at most. 00689 * 00690 * Note: The number of bytes copied is limited by the length of 00691 * the attribute payload. 00692 * 00693 * @return The number of bytes copied to dest. 00694 */ 00695 int nla_memcpy(void *dest, struct nlattr *src, int count) 00696 { 00697 int minlen; 00698 00699 if (!src) 00700 return 0; 00701 00702 minlen = min_t(int, count, nla_len(src)); 00703 memcpy(dest, nla_data(src), minlen); 00704 00705 return minlen; 00706 } 00707 00708 /** 00709 * Copy string attribute payload to a buffer. 00710 * @arg dst Pointer to destination buffer. 00711 * @arg nla Attribute of type NLA_STRING. 00712 * @arg dstsize Size of destination buffer in bytes. 00713 * 00714 * Copies at most dstsize - 1 bytes to the destination buffer. 00715 * The result is always a valid NUL terminated string. Unlike 00716 * strlcpy the destination buffer is always padded out. 00717 * 00718 * @return The length of string attribute without the terminating NUL. 00719 */ 00720 size_t nla_strlcpy(char *dst, const struct nlattr *nla, size_t dstsize) 00721 { 00722 size_t srclen = nla_len(nla); 00723 char *src = nla_data(nla); 00724 00725 if (srclen > 0 && src[srclen - 1] == '\0') 00726 srclen--; 00727 00728 if (dstsize > 0) { 00729 size_t len = (srclen >= dstsize) ? dstsize - 1 : srclen; 00730 00731 memset(dst, 0, dstsize); 00732 memcpy(dst, src, len); 00733 } 00734 00735 return srclen; 00736 } 00737 00738 /** 00739 * Compare attribute payload with memory area. 00740 * @arg nla Attribute. 00741 * @arg data Memory area to compare to. 00742 * @arg size Number of bytes to compare. 00743 * 00744 * @see memcmp(3) 00745 * @return An integer less than, equal to, or greater than zero. 00746 */ 00747 int nla_memcmp(const struct nlattr *nla, const void *data, size_t size) 00748 { 00749 int d = nla_len(nla) - size; 00750 00751 if (d == 0) 00752 d = memcmp(nla_data(nla), data, size); 00753 00754 return d; 00755 } 00756 00757 /** 00758 * Compare string attribute payload with string 00759 * @arg nla Attribute of type NLA_STRING. 00760 * @arg str NUL terminated string. 00761 * 00762 * @see strcmp(3) 00763 * @return An integer less than, equal to, or greater than zero. 00764 */ 00765 int nla_strcmp(const struct nlattr *nla, const char *str) 00766 { 00767 int len = strlen(str) + 1; 00768 int d = nla_len(nla) - len; 00769 00770 if (d == 0) 00771 d = memcmp(nla_data(nla), str, len); 00772 00773 return d; 00774 } 00775 00776 /** @} */ 00777 00778 /** 00779 * @name Unspecific Attribute 00780 * @{ 00781 */ 00782 00783 /** 00784 * Reserve space for a attribute. 00785 * @arg msg Netlink Message. 00786 * @arg attrtype Attribute Type. 00787 * @arg attrlen Length of payload. 00788 * 00789 * Reserves room for a attribute in the specified netlink message and 00790 * fills in the attribute header (type, length). Returns NULL if there 00791 * is unsuficient space for the attribute. 00792 * 00793 * Any padding between payload and the start of the next attribute is 00794 * zeroed out. 00795 * 00796 * @return Pointer to start of attribute or NULL on failure. 00797 */ 00798 struct nlattr *nla_reserve(struct nl_msg *msg, int attrtype, int attrlen) 00799 { 00800 struct nlattr *nla; 00801 int tlen; 00802 00803 tlen = NLMSG_ALIGN(msg->nm_nlh->nlmsg_len) + nla_total_size(attrlen); 00804 00805 if ((tlen + msg->nm_nlh->nlmsg_len) > msg->nm_size) 00806 return NULL; 00807 00808 nla = (struct nlattr *) nlmsg_tail(msg->nm_nlh); 00809 nla->nla_type = attrtype; 00810 nla->nla_len = nla_attr_size(attrlen); 00811 00812 if (attrlen) 00813 memset((unsigned char *) nla + nla->nla_len, 0, nla_padlen(attrlen)); 00814 msg->nm_nlh->nlmsg_len = tlen; 00815 00816 NL_DBG(2, "msg %p: attr <%p> %d: Reserved %d (%d) bytes at offset +%td " 00817 "nlmsg_len=%d\n", msg, nla, nla->nla_type, 00818 nla_total_size(attrlen), attrlen, 00819 (void *) nla - nlmsg_data(msg->nm_nlh), 00820 msg->nm_nlh->nlmsg_len); 00821 00822 return nla; 00823 } 00824 00825 /** 00826 * Add a unspecific attribute to netlink message. 00827 * @arg msg Netlink message. 00828 * @arg attrtype Attribute type. 00829 * @arg datalen Length of data to be used as payload. 00830 * @arg data Pointer to data to be used as attribute payload. 00831 * 00832 * Reserves room for a unspecific attribute and copies the provided data 00833 * into the message as payload of the attribute. Returns an error if there 00834 * is insufficient space for the attribute. 00835 * 00836 * @see nla_reserve 00837 * @return 0 on success or a negative error code. 00838 */ 00839 int nla_put(struct nl_msg *msg, int attrtype, int datalen, const void *data) 00840 { 00841 struct nlattr *nla; 00842 00843 nla = nla_reserve(msg, attrtype, datalen); 00844 if (!nla) 00845 return -NLE_NOMEM; 00846 00847 if (datalen > 0) { 00848 memcpy(nla_data(nla), data, datalen); 00849 NL_DBG(2, "msg %p: attr <%p> %d: Wrote %d bytes at offset +%td\n", 00850 msg, nla, nla->nla_type, datalen, 00851 (void *) nla - nlmsg_data(msg->nm_nlh)); 00852 } 00853 00854 return 0; 00855 } 00856 00857 /** 00858 * Add abstract data as unspecific attribute to netlink message. 00859 * @arg msg Netlink message. 00860 * @arg attrtype Attribute type. 00861 * @arg data Abstract data object. 00862 * 00863 * Equivalent to nla_put() except that the length of the payload is 00864 * derived from the abstract data object. 00865 * 00866 * @see nla_put 00867 * @return 0 on success or a negative error code. 00868 */ 00869 int nla_put_data(struct nl_msg *msg, int attrtype, struct nl_data *data) 00870 { 00871 return nla_put(msg, attrtype, nl_data_get_size(data), 00872 nl_data_get(data)); 00873 } 00874 00875 /** 00876 * Add abstract address as unspecific attribute to netlink message. 00877 * @arg msg Netlink message. 00878 * @arg attrtype Attribute type. 00879 * @arg addr Abstract address object. 00880 * 00881 * @see nla_put 00882 * @return 0 on success or a negative error code. 00883 */ 00884 int nla_put_addr(struct nl_msg *msg, int attrtype, struct nl_addr *addr) 00885 { 00886 return nla_put(msg, attrtype, nl_addr_get_len(addr), 00887 nl_addr_get_binary_addr(addr)); 00888 } 00889 00890 /** @} */ 00891 00892 /** 00893 * @name Integer Attributes 00894 */ 00895 00896 /** 00897 * Add 8 bit integer attribute to netlink message. 00898 * @arg msg Netlink message. 00899 * @arg attrtype Attribute type. 00900 * @arg value Numeric value to store as payload. 00901 * 00902 * @see nla_put 00903 * @return 0 on success or a negative error code. 00904 */ 00905 int nla_put_u8(struct nl_msg *msg, int attrtype, uint8_t value) 00906 { 00907 return nla_put(msg, attrtype, sizeof(uint8_t), &value); 00908 } 00909 00910 /** 00911 * Return value of 8 bit integer attribute. 00912 * @arg nla 8 bit integer attribute 00913 * 00914 * @return Payload as 8 bit integer. 00915 */ 00916 uint8_t nla_get_u8(struct nlattr *nla) 00917 { 00918 return *(uint8_t *) nla_data(nla); 00919 } 00920 00921 /** 00922 * Add 16 bit integer attribute to netlink message. 00923 * @arg msg Netlink message. 00924 * @arg attrtype Attribute type. 00925 * @arg value Numeric value to store as payload. 00926 * 00927 * @see nla_put 00928 * @return 0 on success or a negative error code. 00929 */ 00930 int nla_put_u16(struct nl_msg *msg, int attrtype, uint16_t value) 00931 { 00932 return nla_put(msg, attrtype, sizeof(uint16_t), &value); 00933 } 00934 00935 /** 00936 * Return payload of 16 bit integer attribute. 00937 * @arg nla 16 bit integer attribute 00938 * 00939 * @return Payload as 16 bit integer. 00940 */ 00941 uint16_t nla_get_u16(struct nlattr *nla) 00942 { 00943 return *(uint16_t *) nla_data(nla); 00944 } 00945 00946 /** 00947 * Add 32 bit integer attribute to netlink message. 00948 * @arg msg Netlink message. 00949 * @arg attrtype Attribute type. 00950 * @arg value Numeric value to store as payload. 00951 * 00952 * @see nla_put 00953 * @return 0 on success or a negative error code. 00954 */ 00955 int nla_put_u32(struct nl_msg *msg, int attrtype, uint32_t value) 00956 { 00957 return nla_put(msg, attrtype, sizeof(uint32_t), &value); 00958 } 00959 00960 /** 00961 * Return payload of 32 bit integer attribute. 00962 * @arg nla 32 bit integer attribute. 00963 * 00964 * @return Payload as 32 bit integer. 00965 */ 00966 uint32_t nla_get_u32(struct nlattr *nla) 00967 { 00968 return *(uint32_t *) nla_data(nla); 00969 } 00970 00971 /** 00972 * Add 64 bit integer attribute to netlink message. 00973 * @arg msg Netlink message. 00974 * @arg attrtype Attribute type. 00975 * @arg value Numeric value to store as payload. 00976 * 00977 * @see nla_put 00978 * @return 0 on success or a negative error code. 00979 */ 00980 int nla_put_u64(struct nl_msg *msg, int attrtype, uint64_t value) 00981 { 00982 return nla_put(msg, attrtype, sizeof(uint64_t), &value); 00983 } 00984 00985 /** 00986 * Return payload of u64 attribute 00987 * @arg nla u64 netlink attribute 00988 * 00989 * @return Payload as 64 bit integer. 00990 */ 00991 uint64_t nla_get_u64(struct nlattr *nla) 00992 { 00993 uint64_t tmp; 00994 00995 nla_memcpy(&tmp, nla, sizeof(tmp)); 00996 00997 return tmp; 00998 } 00999 01000 /** @} */ 01001 01002 /** 01003 * @name String Attribute 01004 */ 01005 01006 /** 01007 * Add string attribute to netlink message. 01008 * @arg msg Netlink message. 01009 * @arg attrtype Attribute type. 01010 * @arg str NUL terminated string. 01011 * 01012 * @see nla_put 01013 * @return 0 on success or a negative error code. 01014 */ 01015 int nla_put_string(struct nl_msg *msg, int attrtype, const char *str) 01016 { 01017 return nla_put(msg, attrtype, strlen(str) + 1, str); 01018 } 01019 01020 /** 01021 * Return payload of string attribute. 01022 * @arg nla String attribute. 01023 * 01024 * @return Pointer to attribute payload. 01025 */ 01026 char *nla_get_string(struct nlattr *nla) 01027 { 01028 return (char *) nla_data(nla); 01029 } 01030 01031 char *nla_strdup(struct nlattr *nla) 01032 { 01033 return strdup(nla_get_string(nla)); 01034 } 01035 01036 /** @} */ 01037 01038 /** 01039 * @name Flag Attribute 01040 */ 01041 01042 /** 01043 * Add flag netlink attribute to netlink message. 01044 * @arg msg Netlink message. 01045 * @arg attrtype Attribute type. 01046 * 01047 * @see nla_put 01048 * @return 0 on success or a negative error code. 01049 */ 01050 int nla_put_flag(struct nl_msg *msg, int attrtype) 01051 { 01052 return nla_put(msg, attrtype, 0, NULL); 01053 } 01054 01055 /** 01056 * Return true if flag attribute is set. 01057 * @arg nla Flag netlink attribute. 01058 * 01059 * @return True if flag is set, otherwise false. 01060 */ 01061 int nla_get_flag(struct nlattr *nla) 01062 { 01063 return !!nla; 01064 } 01065 01066 /** @} */ 01067 01068 /** 01069 * @name Microseconds Attribute 01070 */ 01071 01072 /** 01073 * Add a msecs netlink attribute to a netlink message 01074 * @arg n netlink message 01075 * @arg attrtype attribute type 01076 * @arg msecs number of msecs 01077 */ 01078 int nla_put_msecs(struct nl_msg *n, int attrtype, unsigned long msecs) 01079 { 01080 return nla_put_u64(n, attrtype, msecs); 01081 } 01082 01083 /** 01084 * Return payload of msecs attribute 01085 * @arg nla msecs netlink attribute 01086 * 01087 * @return the number of milliseconds. 01088 */ 01089 unsigned long nla_get_msecs(struct nlattr *nla) 01090 { 01091 return nla_get_u64(nla); 01092 } 01093 01094 /** @} */ 01095 01096 /** 01097 * @name Nested Attribute 01098 */ 01099 01100 /** 01101 * Add nested attributes to netlink message. 01102 * @arg msg Netlink message. 01103 * @arg attrtype Attribute type. 01104 * @arg nested Message containing attributes to be nested. 01105 * 01106 * Takes the attributes found in the \a nested message and appends them 01107 * to the message \a msg nested in a container of the type \a attrtype. 01108 * The \a nested message may not have a family specific header. 01109 * 01110 * @see nla_put 01111 * @return 0 on success or a negative error code. 01112 */ 01113 int nla_put_nested(struct nl_msg *msg, int attrtype, struct nl_msg *nested) 01114 { 01115 NL_DBG(2, "msg %p: attr <> %d: adding msg %p as nested attribute\n", 01116 msg, attrtype, nested); 01117 01118 return nla_put(msg, attrtype, nlmsg_datalen(nested->nm_nlh), 01119 nlmsg_data(nested->nm_nlh)); 01120 } 01121 01122 01123 /** 01124 * Start a new level of nested attributes. 01125 * @arg msg Netlink message. 01126 * @arg attrtype Attribute type of container. 01127 * 01128 * @return Pointer to container attribute. 01129 */ 01130 struct nlattr *nla_nest_start(struct nl_msg *msg, int attrtype) 01131 { 01132 struct nlattr *start = (struct nlattr *) nlmsg_tail(msg->nm_nlh); 01133 01134 if (nla_put(msg, attrtype, 0, NULL) < 0) 01135 return NULL; 01136 01137 NL_DBG(2, "msg %p: attr <%p> %d: starting nesting\n", 01138 msg, start, start->nla_type); 01139 01140 return start; 01141 } 01142 01143 /** 01144 * Finalize nesting of attributes. 01145 * @arg msg Netlink message. 01146 * @arg start Container attribute as returned from nla_nest_start(). 01147 * 01148 * Corrects the container attribute header to include the appeneded attributes. 01149 * 01150 * @return 0 01151 */ 01152 int nla_nest_end(struct nl_msg *msg, struct nlattr *start) 01153 { 01154 size_t pad; 01155 01156 start->nla_len = (unsigned char *) nlmsg_tail(msg->nm_nlh) - 01157 (unsigned char *) start; 01158 01159 pad = NLMSG_ALIGN(msg->nm_nlh->nlmsg_len) - msg->nm_nlh->nlmsg_len; 01160 if (pad > 0) { 01161 /* 01162 * Data inside attribute does not end at a alignment boundry. 01163 * Pad accordingly and accoun for the additional space in 01164 * the message. nlmsg_reserve() may never fail in this situation, 01165 * the allocate message buffer must be a multiple of NLMSG_ALIGNTO. 01166 */ 01167 if (!nlmsg_reserve(msg, pad, 0)) 01168 BUG(); 01169 01170 NL_DBG(2, "msg %p: attr <%p> %d: added %zu bytes of padding\n", 01171 msg, start, start->nla_type, pad); 01172 } 01173 01174 NL_DBG(2, "msg %p: attr <%p> %d: closing nesting, len=%u\n", 01175 msg, start, start->nla_type, start->nla_len); 01176 01177 return 0; 01178 } 01179 01180 /** 01181 * Create attribute index based on nested attribute 01182 * @arg tb Index array to be filled (maxtype+1 elements). 01183 * @arg maxtype Maximum attribute type expected and accepted. 01184 * @arg nla Nested Attribute. 01185 * @arg policy Attribute validation policy. 01186 * 01187 * Feeds the stream of attributes nested into the specified attribute 01188 * to nla_parse(). 01189 * 01190 * @see nla_parse 01191 * @return 0 on success or a negative error code. 01192 */ 01193 int nla_parse_nested(struct nlattr *tb[], int maxtype, struct nlattr *nla, 01194 struct nla_policy *policy) 01195 { 01196 return nla_parse(tb, maxtype, nla_data(nla), nla_len(nla), policy); 01197 } 01198 01199 /** @} */ 01200 01201 /** @} */