libnl  3.2.7
attr.c
1 /*
2  * lib/attr.c Netlink Attributes
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation version 2.1
7  * of the License.
8  *
9  * Copyright (c) 2003-2008 Thomas Graf <tgraf@suug.ch>
10  */
11 
12 #include <netlink-local.h>
13 #include <netlink/netlink.h>
14 #include <netlink/utils.h>
15 #include <netlink/addr.h>
16 #include <netlink/attr.h>
17 #include <netlink/msg.h>
18 #include <linux/socket.h>
19 
20 /**
21  * @ingroup msg
22  * @defgroup attr Attributes
23  * Netlink Attributes Construction/Parsing Interface
24  *
25  * \section attr_sec Netlink Attributes
26  * Netlink attributes allow for data chunks of arbitary length to be
27  * attached to a netlink message. Each attribute is encoded with a
28  * type and length field, both 16 bits, stored in the attribute header
29  * preceding the attribute data. The main advantage of using attributes
30  * over packing everything into the family header is that the interface
31  * stays extendable as new attributes can supersede old attributes while
32  * remaining backwards compatible. Also attributes can be defined optional
33  * thus avoiding the transmission of unnecessary empty data blocks.
34  * Special nested attributes allow for more complex data structures to
35  * be transmitted, e.g. trees, lists, etc.
36  *
37  * While not required, netlink attributes typically follow the family
38  * header of a netlink message and must be properly aligned to NLA_ALIGNTO:
39  * @code
40  * +----------------+- - -+---------------+- - -+------------+- - -+
41  * | Netlink Header | Pad | Family Header | Pad | Attributes | Pad |
42  * +----------------+- - -+---------------+- - -+------------+- - -+
43  * @endcode
44  *
45  * The actual attributes are chained together each separately aligned to
46  * NLA_ALIGNTO. The position of an attribute is defined based on the
47  * length field of the preceding attributes:
48  * @code
49  * +-------------+- - -+-------------+- - -+------
50  * | Attribute 1 | Pad | Attribute 2 | Pad | ...
51  * +-------------+- - -+-------------+- - -+------
52  * nla_next(attr1)------^
53  * @endcode
54  *
55  * The attribute itself consists of the attribute header followed by
56  * the actual payload also aligned to NLA_ALIGNTO. The function nla_data()
57  * returns a pointer to the start of the payload while nla_len() returns
58  * the length of the payload in bytes.
59  *
60  * \b Note: Be aware, NLA_ALIGNTO equals to 4 bytes, therefore it is not
61  * safe to dereference any 64 bit data types directly.
62  *
63  * @code
64  * <----------- nla_total_size(payload) ----------->
65  * <-------- nla_attr_size(payload) --------->
66  * +------------------+- - -+- - - - - - - - - +- - -+
67  * | Attribute Header | Pad | Payload | Pad |
68  * +------------------+- - -+- - - - - - - - - +- - -+
69  * nla_data(nla)-------------^
70  * <- nla_len(nla) ->
71  * @endcode
72  *
73  * @subsection attr_datatypes Attribute Data Types
74  * A number of basic data types are supported to simplify access and
75  * validation of netlink attributes. This data type information is
76  * not encoded in the attribute, both the kernel and userspace part
77  * are required to share this information on their own.
78  *
79  * One of the major advantages of these basic types is the automatic
80  * validation of each attribute based on an attribute policy. The
81  * validation covers most of the checks required to safely use
82  * attributes and thus keeps the individual sanity check to a minimum.
83  *
84  * Never access attribute payload without ensuring basic validation
85  * first, attributes may:
86  * - not be present even though required
87  * - contain less actual payload than expected
88  * - fake a attribute length which exceeds the end of the message
89  * - contain unterminated character strings
90  *
91  * Policies are defined as array of the struct nla_policy. The array is
92  * indexed with the attribute type, therefore the array must be sized
93  * accordingly.
94  * @code
95  * static struct nla_policy my_policy[ATTR_MAX+1] = {
96  * [ATTR_FOO] = { .type = ..., .minlen = ..., .maxlen = ... },
97  * };
98  *
99  * err = nla_validate(attrs, attrlen, ATTR_MAX, &my_policy);
100  * @endcode
101  *
102  * Some basic validations are performed on every attribute, regardless of type.
103  * - If the attribute type exceeds the maximum attribute type specified or
104  * the attribute type is lesser-or-equal than zero, the attribute will
105  * be silently ignored.
106  * - If the payload length falls below the \a minlen value the attribute
107  * will be rejected.
108  * - If \a maxlen is non-zero and the payload length exceeds the \a maxlen
109  * value the attribute will be rejected.
110  *
111  *
112  * @par Unspecific Attribute (NLA_UNSPEC)
113  * This is the standard type if no type is specified. It is used for
114  * binary data of arbitary length. Typically this attribute carries
115  * a binary structure or a stream of bytes.
116  * @par
117  * @code
118  * // In this example, we will assume a binary structure requires to
119  * // be transmitted. The definition of the structure will typically
120  * // go into a header file available to both the kernel and userspace
121  * // side.
122  * //
123  * // Note: Be careful when putting 64 bit data types into a structure.
124  * // The attribute payload is only aligned to 4 bytes, dereferencing
125  * // the member may fail.
126  * struct my_struct {
127  * int a;
128  * int b;
129  * };
130  *
131  * // The validation function will not enforce an exact length match to
132  * // allow structures to grow as required. Note: While it is allowed
133  * // to add members to the end of the structure, changing the order or
134  * // inserting members in the middle of the structure will break your
135  * // binary interface.
136  * static struct nla_policy my_policy[ATTR_MAX+1] = {
137  * [ATTR_MY_STRICT] = { .type = NLA_UNSPEC,
138  * .minlen = sizeof(struct my_struct) },
139  *
140  * // The binary structure is appened to the message using nla_put()
141  * struct my_struct foo = { .a = 1, .b = 2 };
142  * nla_put(msg, ATTR_MY_STRUCT, sizeof(foo), &foo);
143  *
144  * // On the receiving side, a pointer to the structure pointing inside
145  * // the message payload is returned by nla_get().
146  * if (attrs[ATTR_MY_STRUCT])
147  * struct my_struct *foo = nla_get(attrs[ATTR_MY_STRUCT]);
148  * @endcode
149  *
150  * @par Integers (NLA_U8, NLA_U16, NLA_U32, NLA_U64)
151  * Integers come in different sizes from 8 bit to 64 bit. However, since the
152  * payload length is aligned to 4 bytes, integers smaller than 32 bit are
153  * only useful to enforce the maximum range of values.
154  * @par
155  * \b Note: There is no difference made between signed and unsigned integers.
156  * The validation only enforces the minimal payload length required to store
157  * an integer of specified type.
158  * @par
159  * @code
160  * // Even though possible, it does not make sense to specify .minlen or
161  * // .maxlen for integer types. The data types implies the corresponding
162  * // minimal payload length.
163  * static struct nla_policy my_policy[ATTR_MAX+1] = {
164  * [ATTR_FOO] = { .type = NLA_U32 },
165  *
166  * // Numeric values can be appended directly using the respective
167  * // nla_put_uxxx() function
168  * nla_put_u32(msg, ATTR_FOO, 123);
169  *
170  * // Same for the receiving side.
171  * if (attrs[ATTR_FOO])
172  * uint32_t foo = nla_get_u32(attrs[ATTR_FOO]);
173  * @endcode
174  *
175  * @par Character string (NLA_STRING)
176  * This data type represents a NUL terminated character string of variable
177  * length. For binary data streams the type NLA_UNSPEC is recommended.
178  * @par
179  * @code
180  * // Enforce a NUL terminated character string of at most 4 characters
181  * // including the NUL termination.
182  * static struct nla_policy my_policy[ATTR_MAX+1] = {
183  * [ATTR_BAR] = { .type = NLA_STRING, maxlen = 4 },
184  *
185  * // nla_put_string() creates a string attribute of the necessary length
186  * // and appends it to the message including the NUL termination.
187  * nla_put_string(msg, ATTR_BAR, "some text");
188  *
189  * // It is safe to use the returned character string directly if the
190  * // attribute has been validated as the validation enforces the proper
191  * // termination of the string.
192  * if (attrs[ATTR_BAR])
193  * char *text = nla_get_string(attrs[ATTR_BAR]);
194  * @endcode
195  *
196  * @par Flag (NLA_FLAG)
197  * This attribute type may be used to indicate the presence of a flag. The
198  * attribute is only valid if the payload length is zero. The presence of
199  * the attribute header indicates the presence of the flag.
200  * @par
201  * @code
202  * // This attribute type is special as .minlen and .maxlen have no effect.
203  * static struct nla_policy my_policy[ATTR_MAX+1] = {
204  * [ATTR_FLAG] = { .type = NLA_FLAG },
205  *
206  * // nla_put_flag() appends a zero sized attribute to the message.
207  * nla_put_flag(msg, ATTR_FLAG);
208  *
209  * // There is no need for a receival function, the presence is the value.
210  * if (attrs[ATTR_FLAG])
211  * // flag is present
212  * @endcode
213  *
214  * @par Micro Seconds (NLA_MSECS)
215  *
216  * @par Nested Attribute (NLA_NESTED)
217  * Attributes can be nested and put into a container to create groups, lists
218  * or to construct trees of attributes. Nested attributes are often used to
219  * pass attributes to a subsystem where the top layer has no knowledge of the
220  * configuration possibilities of each subsystem.
221  * @par
222  * \b Note: When validating the attributes using nlmsg_validate() or
223  * nlmsg_parse() it will only affect the top level attributes. Each
224  * level of nested attributes must be validated seperately using
225  * nla_parse_nested() or nla_validate().
226  * @par
227  * @code
228  * // The minimal length policy may be used to enforce the presence of at
229  * // least one attribute.
230  * static struct nla_policy my_policy[ATTR_MAX+1] = {
231  * [ATTR_OPTS] = { .type = NLA_NESTED, minlen = NLA_HDRLEN },
232  *
233  * // Nested attributes are constructed by enclosing the attributes
234  * // to be nested with calls to nla_nest_start() respetively nla_nest_end().
235  * struct nlattr *opts = nla_nest_start(msg, ATTR_OPTS);
236  * nla_put_u32(msg, ATTR_FOO, 123);
237  * nla_put_string(msg, ATTR_BAR, "some text");
238  * nla_nest_end(msg, opts);
239  *
240  * // Various methods exist to parse nested attributes, the easiest being
241  * // nla_parse_nested() which also allows validation in the same step.
242  * if (attrs[ATTR_OPTS]) {
243  * struct nlattr *nested[ATTR_MAX+1];
244  *
245  * nla_parse_nested(nested, ATTR_MAX, attrs[ATTR_OPTS], &policy);
246  *
247  * if (nested[ATTR_FOO])
248  * uint32_t foo = nla_get_u32(nested[ATTR_FOO]);
249  * }
250  * @endcode
251  *
252  * @subsection attr_exceptions Exception Based Attribute Construction
253  * Often a large number of attributes are added to a message in a single
254  * function. In order to simplify error handling, a second set of
255  * construction functions exist which jump to a error label when they
256  * fail instead of returning an error code. This second set consists
257  * of macros which are named after their error code based counterpart
258  * except that the name is written all uppercase.
259  *
260  * All of the macros jump to the target \c nla_put_failure if they fail.
261  * @code
262  * void my_func(struct nl_msg *msg)
263  * {
264  * NLA_PUT_U32(msg, ATTR_FOO, 10);
265  * NLA_PUT_STRING(msg, ATTR_BAR, "bar");
266  *
267  * return 0;
268  *
269  * nla_put_failure:
270  * return -NLE_NOMEM;
271  * }
272  * @endcode
273  *
274  * @subsection attr_examples Examples
275  * @par Example 1.1 Constructing a netlink message with attributes.
276  * @code
277  * struct nl_msg *build_msg(int ifindex, struct nl_addr *lladdr, int mtu)
278  * {
279  * struct nl_msg *msg;
280  * struct nlattr *info, *vlan;
281  * struct ifinfomsg ifi = {
282  * .ifi_family = AF_INET,
283  * .ifi_index = ifindex,
284  * };
285  *
286  * // Allocate a new netlink message, type=RTM_SETLINK, flags=NLM_F_ECHO
287  * if (!(msg = nlmsg_alloc_simple(RTM_SETLINK, NLM_F_ECHO)))
288  * return NULL;
289  *
290  * // Append the family specific header (struct ifinfomsg)
291  * if (nlmsg_append(msg, &ifi, sizeof(ifi), NLMSG_ALIGNTO) < 0)
292  * goto nla_put_failure
293  *
294  * // Append a 32 bit integer attribute to carry the MTU
295  * NLA_PUT_U32(msg, IFLA_MTU, mtu);
296  *
297  * // Append a unspecific attribute to carry the link layer address
298  * NLA_PUT_ADDR(msg, IFLA_ADDRESS, lladdr);
299  *
300  * // Append a container for nested attributes to carry link information
301  * if (!(info = nla_nest_start(msg, IFLA_LINKINFO)))
302  * goto nla_put_failure;
303  *
304  * // Put a string attribute into the container
305  * NLA_PUT_STRING(msg, IFLA_INFO_KIND, "vlan");
306  *
307  * // Append another container inside the open container to carry
308  * // vlan specific attributes
309  * if (!(vlan = nla_nest_start(msg, IFLA_INFO_DATA)))
310  * goto nla_put_failure;
311  *
312  * // add vlan specific info attributes here...
313  *
314  * // Finish nesting the vlan attributes and close the second container.
315  * nla_nest_end(msg, vlan);
316  *
317  * // Finish nesting the link info attribute and close the first container.
318  * nla_nest_end(msg, info);
319  *
320  * return msg;
321  *
322  * // If any of the construction macros fails, we end up here.
323  * nla_put_failure:
324  * nlmsg_free(msg);
325  * return NULL;
326  * }
327  * @endcode
328  *
329  * @par Example 2.1 Parsing a netlink message with attributes.
330  * @code
331  * int parse_message(struct nl_msg *msg)
332  * {
333  * // The policy defines two attributes: a 32 bit integer and a container
334  * // for nested attributes.
335  * struct nla_policy attr_policy[ATTR_MAX+1] = {
336  * [ATTR_FOO] = { .type = NLA_U32 },
337  * [ATTR_BAR] = { .type = NLA_NESTED },
338  * };
339  * struct nlattr *attrs[ATTR_MAX+1];
340  * int err;
341  *
342  * // The nlmsg_parse() function will make sure that the message contains
343  * // enough payload to hold the header (struct my_hdr), validates any
344  * // attributes attached to the messages and stores a pointer to each
345  * // attribute in the attrs[] array accessable by attribute type.
346  * if ((err = nlmsg_parse(nlmsg_hdr(msg), sizeof(struct my_hdr), attrs,
347  * ATTR_MAX, attr_policy)) < 0)
348  * goto errout;
349  *
350  * if (attrs[ATTR_FOO]) {
351  * // It is safe to directly access the attribute payload without
352  * // any further checks since nlmsg_parse() enforced the policy.
353  * uint32_t foo = nla_get_u32(attrs[ATTR_FOO]);
354  * }
355  *
356  * if (attrs[ATTR_BAR]) {
357  * struct nlattr *nested[NESTED_MAX+1];
358  *
359  * // Attributes nested in a container can be parsed the same way
360  * // as top level attributes.
361  * if ((err = nla_parse_nested(nested, NESTED_MAX, attrs[ATTR_BAR],
362  * nested_policy)) < 0)
363  * goto errout;
364  *
365  * // Process nested attributes here.
366  * }
367  *
368  * err = 0;
369  * errout:
370  * return err;
371  * }
372  * @endcode
373  *
374  * @{
375  */
376 
377 /**
378  * @name Attribute Size Calculation
379  * @{
380  */
381 
382 /**
383  * Return size of attribute whithout padding.
384  * @arg payload Payload length of attribute.
385  *
386  * @code
387  * <-------- nla_attr_size(payload) --------->
388  * +------------------+- - -+- - - - - - - - - +- - -+
389  * | Attribute Header | Pad | Payload | Pad |
390  * +------------------+- - -+- - - - - - - - - +- - -+
391  * @endcode
392  *
393  * @return Size of attribute in bytes without padding.
394  */
395 int nla_attr_size(int payload)
396 {
397  return NLA_HDRLEN + payload;
398 }
399 
400 /**
401  * Return size of attribute including padding.
402  * @arg payload Payload length of attribute.
403  *
404  * @code
405  * <----------- nla_total_size(payload) ----------->
406  * +------------------+- - -+- - - - - - - - - +- - -+
407  * | Attribute Header | Pad | Payload | Pad |
408  * +------------------+- - -+- - - - - - - - - +- - -+
409  * @endcode
410  *
411  * @return Size of attribute in bytes.
412  */
413 int nla_total_size(int payload)
414 {
415  return NLA_ALIGN(nla_attr_size(payload));
416 }
417 
418 /**
419  * Return length of padding at the tail of the attribute.
420  * @arg payload Payload length of attribute.
421  *
422  * @code
423  * +------------------+- - -+- - - - - - - - - +- - -+
424  * | Attribute Header | Pad | Payload | Pad |
425  * +------------------+- - -+- - - - - - - - - +- - -+
426  * <--->
427  * @endcode
428  *
429  * @return Length of padding in bytes.
430  */
431 int nla_padlen(int payload)
432 {
433  return nla_total_size(payload) - nla_attr_size(payload);
434 }
435 
436 /** @} */
437 
438 /**
439  * @name Parsing Attributes
440  * @{
441  */
442 
443 /**
444  * Return type of the attribute.
445  * @arg nla Attribute.
446  *
447  * @return Type of attribute.
448  */
449 int nla_type(const struct nlattr *nla)
450 {
451  return nla->nla_type & NLA_TYPE_MASK;
452 }
453 
454 /**
455  * Return pointer to the payload section.
456  * @arg nla Attribute.
457  *
458  * @return Pointer to start of payload section.
459  */
460 void *nla_data(const struct nlattr *nla)
461 {
462  return (char *) nla + NLA_HDRLEN;
463 }
464 
465 /**
466  * Return length of the payload .
467  * @arg nla Attribute
468  *
469  * @return Length of payload in bytes.
470  */
471 int nla_len(const struct nlattr *nla)
472 {
473  return nla->nla_len - NLA_HDRLEN;
474 }
475 
476 /**
477  * Check if the attribute header and payload can be accessed safely.
478  * @arg nla Attribute of any kind.
479  * @arg remaining Number of bytes remaining in attribute stream.
480  *
481  * Verifies that the header and payload do not exceed the number of
482  * bytes left in the attribute stream. This function must be called
483  * before access the attribute header or payload when iterating over
484  * the attribute stream using nla_next().
485  *
486  * @return True if the attribute can be accessed safely, false otherwise.
487  */
488 int nla_ok(const struct nlattr *nla, int remaining)
489 {
490  return remaining >= sizeof(*nla) &&
491  nla->nla_len >= sizeof(*nla) &&
492  nla->nla_len <= remaining;
493 }
494 
495 /**
496  * Return next attribute in a stream of attributes.
497  * @arg nla Attribute of any kind.
498  * @arg remaining Variable to count remaining bytes in stream.
499  *
500  * Calculates the offset to the next attribute based on the attribute
501  * given. The attribute provided is assumed to be accessible, the
502  * caller is responsible to use nla_ok() beforehand. The offset (length
503  * of specified attribute including padding) is then subtracted from
504  * the remaining bytes variable and a pointer to the next attribute is
505  * returned.
506  *
507  * nla_next() can be called as long as remainig is >0.
508  *
509  * @return Pointer to next attribute.
510  */
511 struct nlattr *nla_next(const struct nlattr *nla, int *remaining)
512 {
513  int totlen = NLA_ALIGN(nla->nla_len);
514 
515  *remaining -= totlen;
516  return (struct nlattr *) ((char *) nla + totlen);
517 }
518 
519 static uint16_t nla_attr_minlen[NLA_TYPE_MAX+1] = {
520  [NLA_U8] = sizeof(uint8_t),
521  [NLA_U16] = sizeof(uint16_t),
522  [NLA_U32] = sizeof(uint32_t),
523  [NLA_U64] = sizeof(uint64_t),
524  [NLA_STRING] = 1,
525 };
526 
527 static int validate_nla(struct nlattr *nla, int maxtype,
528  struct nla_policy *policy)
529 {
530  struct nla_policy *pt;
531  int minlen = 0, type = nla_type(nla);
532 
533  if (type <= 0 || type > maxtype)
534  return 0;
535 
536  pt = &policy[type];
537 
538  if (pt->type > NLA_TYPE_MAX)
539  BUG();
540 
541  if (pt->minlen)
542  minlen = pt->minlen;
543  else if (pt->type != NLA_UNSPEC)
544  minlen = nla_attr_minlen[pt->type];
545 
546  if (pt->type == NLA_FLAG && nla_len(nla) > 0)
547  return -NLE_RANGE;
548 
549  if (nla_len(nla) < minlen)
550  return -NLE_RANGE;
551 
552  if (pt->maxlen && nla_len(nla) > pt->maxlen)
553  return -NLE_RANGE;
554 
555  if (pt->type == NLA_STRING) {
556  char *data = nla_data(nla);
557  if (data[nla_len(nla) - 1] != '\0')
558  return -NLE_INVAL;
559  }
560 
561  return 0;
562 }
563 
564 
565 /**
566  * Create attribute index based on a stream of attributes.
567  * @arg tb Index array to be filled (maxtype+1 elements).
568  * @arg maxtype Maximum attribute type expected and accepted.
569  * @arg head Head of attribute stream.
570  * @arg len Length of attribute stream.
571  * @arg policy Attribute validation policy.
572  *
573  * Iterates over the stream of attributes and stores a pointer to each
574  * attribute in the index array using the attribute type as index to
575  * the array. Attribute with a type greater than the maximum type
576  * specified will be silently ignored in order to maintain backwards
577  * compatibility. If \a policy is not NULL, the attribute will be
578  * validated using the specified policy.
579  *
580  * @see nla_validate
581  * @return 0 on success or a negative error code.
582  */
583 int nla_parse(struct nlattr *tb[], int maxtype, struct nlattr *head, int len,
584  struct nla_policy *policy)
585 {
586  struct nlattr *nla;
587  int rem, err;
588 
589  memset(tb, 0, sizeof(struct nlattr *) * (maxtype + 1));
590 
591  nla_for_each_attr(nla, head, len, rem) {
592  int type = nla_type(nla);
593 
594  if (type == 0) {
595  fprintf(stderr, "Illegal nla->nla_type == 0\n");
596  continue;
597  }
598 
599  if (type <= maxtype) {
600  if (policy) {
601  err = validate_nla(nla, maxtype, policy);
602  if (err < 0)
603  goto errout;
604  }
605 
606  tb[type] = nla;
607  }
608  }
609 
610  if (rem > 0)
611  fprintf(stderr, "netlink: %d bytes leftover after parsing "
612  "attributes.\n", rem);
613 
614  err = 0;
615 errout:
616  return err;
617 }
618 
619 /**
620  * Validate a stream of attributes.
621  * @arg head Head of attributes stream.
622  * @arg len Length of attributes stream.
623  * @arg maxtype Maximum attribute type expected and accepted.
624  * @arg policy Validation policy.
625  *
626  * Iterates over the stream of attributes and validates each attribute
627  * one by one using the specified policy. Attributes with a type greater
628  * than the maximum type specified will be silently ignored in order to
629  * maintain backwards compatibility.
630  *
631  * See \ref attr_datatypes for more details on what kind of validation
632  * checks are performed on each attribute data type.
633  *
634  * @return 0 on success or a negative error code.
635  */
636 int nla_validate(struct nlattr *head, int len, int maxtype,
637  struct nla_policy *policy)
638 {
639  struct nlattr *nla;
640  int rem, err;
641 
642  nla_for_each_attr(nla, head, len, rem) {
643  err = validate_nla(nla, maxtype, policy);
644  if (err < 0)
645  goto errout;
646  }
647 
648  err = 0;
649 errout:
650  return err;
651 }
652 
653 /**
654  * Find a single attribute in a stream of attributes.
655  * @arg head Head of attributes stream.
656  * @arg len Length of attributes stream.
657  * @arg attrtype Attribute type to look for.
658  *
659  * Iterates over the stream of attributes and compares each type with
660  * the type specified. Returns the first attribute which matches the
661  * type.
662  *
663  * @return Pointer to attribute found or NULL.
664  */
665 struct nlattr *nla_find(struct nlattr *head, int len, int attrtype)
666 {
667  struct nlattr *nla;
668  int rem;
669 
670  nla_for_each_attr(nla, head, len, rem)
671  if (nla_type(nla) == attrtype)
672  return nla;
673 
674  return NULL;
675 }
676 
677 /** @} */
678 
679 /**
680  * @name Helper Functions
681  * @{
682  */
683 
684 /**
685  * Copy attribute payload to another memory area.
686  * @arg dest Pointer to destination memory area.
687  * @arg src Attribute
688  * @arg count Number of bytes to copy at most.
689  *
690  * Note: The number of bytes copied is limited by the length of
691  * the attribute payload.
692  *
693  * @return The number of bytes copied to dest.
694  */
695 int nla_memcpy(void *dest, struct nlattr *src, int count)
696 {
697  int minlen;
698 
699  if (!src)
700  return 0;
701 
702  minlen = min_t(int, count, nla_len(src));
703  memcpy(dest, nla_data(src), minlen);
704 
705  return minlen;
706 }
707 
708 /**
709  * Copy string attribute payload to a buffer.
710  * @arg dst Pointer to destination buffer.
711  * @arg nla Attribute of type NLA_STRING.
712  * @arg dstsize Size of destination buffer in bytes.
713  *
714  * Copies at most dstsize - 1 bytes to the destination buffer.
715  * The result is always a valid NUL terminated string. Unlike
716  * strlcpy the destination buffer is always padded out.
717  *
718  * @return The length of string attribute without the terminating NUL.
719  */
720 size_t nla_strlcpy(char *dst, const struct nlattr *nla, size_t dstsize)
721 {
722  size_t srclen = nla_len(nla);
723  char *src = nla_data(nla);
724 
725  if (srclen > 0 && src[srclen - 1] == '\0')
726  srclen--;
727 
728  if (dstsize > 0) {
729  size_t len = (srclen >= dstsize) ? dstsize - 1 : srclen;
730 
731  memset(dst, 0, dstsize);
732  memcpy(dst, src, len);
733  }
734 
735  return srclen;
736 }
737 
738 /**
739  * Compare attribute payload with memory area.
740  * @arg nla Attribute.
741  * @arg data Memory area to compare to.
742  * @arg size Number of bytes to compare.
743  *
744  * @see memcmp(3)
745  * @return An integer less than, equal to, or greater than zero.
746  */
747 int nla_memcmp(const struct nlattr *nla, const void *data, size_t size)
748 {
749  int d = nla_len(nla) - size;
750 
751  if (d == 0)
752  d = memcmp(nla_data(nla), data, size);
753 
754  return d;
755 }
756 
757 /**
758  * Compare string attribute payload with string
759  * @arg nla Attribute of type NLA_STRING.
760  * @arg str NUL terminated string.
761  *
762  * @see strcmp(3)
763  * @return An integer less than, equal to, or greater than zero.
764  */
765 int nla_strcmp(const struct nlattr *nla, const char *str)
766 {
767  int len = strlen(str) + 1;
768  int d = nla_len(nla) - len;
769 
770  if (d == 0)
771  d = memcmp(nla_data(nla), str, len);
772 
773  return d;
774 }
775 
776 /** @} */
777 
778 /**
779  * @name Unspecific Attribute
780  * @{
781  */
782 
783 /**
784  * Reserve space for a attribute.
785  * @arg msg Netlink Message.
786  * @arg attrtype Attribute Type.
787  * @arg attrlen Length of payload.
788  *
789  * Reserves room for a attribute in the specified netlink message and
790  * fills in the attribute header (type, length). Returns NULL if there
791  * is unsuficient space for the attribute.
792  *
793  * Any padding between payload and the start of the next attribute is
794  * zeroed out.
795  *
796  * @return Pointer to start of attribute or NULL on failure.
797  */
798 struct nlattr *nla_reserve(struct nl_msg *msg, int attrtype, int attrlen)
799 {
800  struct nlattr *nla;
801  int tlen;
802 
803  tlen = NLMSG_ALIGN(msg->nm_nlh->nlmsg_len) + nla_total_size(attrlen);
804 
805  if ((tlen + msg->nm_nlh->nlmsg_len) > msg->nm_size)
806  return NULL;
807 
808  nla = (struct nlattr *) nlmsg_tail(msg->nm_nlh);
809  nla->nla_type = attrtype;
810  nla->nla_len = nla_attr_size(attrlen);
811 
812  if (attrlen)
813  memset((unsigned char *) nla + nla->nla_len, 0, nla_padlen(attrlen));
814  msg->nm_nlh->nlmsg_len = tlen;
815 
816  NL_DBG(2, "msg %p: attr <%p> %d: Reserved %d (%d) bytes at offset +%td "
817  "nlmsg_len=%d\n", msg, nla, nla->nla_type,
818  nla_total_size(attrlen), attrlen,
819  (void *) nla - nlmsg_data(msg->nm_nlh),
820  msg->nm_nlh->nlmsg_len);
821 
822  return nla;
823 }
824 
825 /**
826  * Add a unspecific attribute to netlink message.
827  * @arg msg Netlink message.
828  * @arg attrtype Attribute type.
829  * @arg datalen Length of data to be used as payload.
830  * @arg data Pointer to data to be used as attribute payload.
831  *
832  * Reserves room for a unspecific attribute and copies the provided data
833  * into the message as payload of the attribute. Returns an error if there
834  * is insufficient space for the attribute.
835  *
836  * @see nla_reserve
837  * @return 0 on success or a negative error code.
838  */
839 int nla_put(struct nl_msg *msg, int attrtype, int datalen, const void *data)
840 {
841  struct nlattr *nla;
842 
843  nla = nla_reserve(msg, attrtype, datalen);
844  if (!nla)
845  return -NLE_NOMEM;
846 
847  if (datalen > 0) {
848  memcpy(nla_data(nla), data, datalen);
849  NL_DBG(2, "msg %p: attr <%p> %d: Wrote %d bytes at offset +%td\n",
850  msg, nla, nla->nla_type, datalen,
851  (void *) nla - nlmsg_data(msg->nm_nlh));
852  }
853 
854  return 0;
855 }
856 
857 /**
858  * Add abstract data as unspecific attribute to netlink message.
859  * @arg msg Netlink message.
860  * @arg attrtype Attribute type.
861  * @arg data Abstract data object.
862  *
863  * Equivalent to nla_put() except that the length of the payload is
864  * derived from the abstract data object.
865  *
866  * @see nla_put
867  * @return 0 on success or a negative error code.
868  */
869 int nla_put_data(struct nl_msg *msg, int attrtype, struct nl_data *data)
870 {
871  return nla_put(msg, attrtype, nl_data_get_size(data),
872  nl_data_get(data));
873 }
874 
875 /**
876  * Add abstract address as unspecific attribute to netlink message.
877  * @arg msg Netlink message.
878  * @arg attrtype Attribute type.
879  * @arg addr Abstract address object.
880  *
881  * @see nla_put
882  * @return 0 on success or a negative error code.
883  */
884 int nla_put_addr(struct nl_msg *msg, int attrtype, struct nl_addr *addr)
885 {
886  return nla_put(msg, attrtype, nl_addr_get_len(addr),
888 }
889 
890 /** @} */
891 
892 /**
893  * @name Integer Attributes
894  */
895 
896 /**
897  * Add 8 bit integer attribute to netlink message.
898  * @arg msg Netlink message.
899  * @arg attrtype Attribute type.
900  * @arg value Numeric value to store as payload.
901  *
902  * @see nla_put
903  * @return 0 on success or a negative error code.
904  */
905 int nla_put_u8(struct nl_msg *msg, int attrtype, uint8_t value)
906 {
907  return nla_put(msg, attrtype, sizeof(uint8_t), &value);
908 }
909 
910 /**
911  * Return value of 8 bit integer attribute.
912  * @arg nla 8 bit integer attribute
913  *
914  * @return Payload as 8 bit integer.
915  */
916 uint8_t nla_get_u8(struct nlattr *nla)
917 {
918  return *(uint8_t *) nla_data(nla);
919 }
920 
921 /**
922  * Add 16 bit integer attribute to netlink message.
923  * @arg msg Netlink message.
924  * @arg attrtype Attribute type.
925  * @arg value Numeric value to store as payload.
926  *
927  * @see nla_put
928  * @return 0 on success or a negative error code.
929  */
930 int nla_put_u16(struct nl_msg *msg, int attrtype, uint16_t value)
931 {
932  return nla_put(msg, attrtype, sizeof(uint16_t), &value);
933 }
934 
935 /**
936  * Return payload of 16 bit integer attribute.
937  * @arg nla 16 bit integer attribute
938  *
939  * @return Payload as 16 bit integer.
940  */
941 uint16_t nla_get_u16(struct nlattr *nla)
942 {
943  return *(uint16_t *) nla_data(nla);
944 }
945 
946 /**
947  * Add 32 bit integer attribute to netlink message.
948  * @arg msg Netlink message.
949  * @arg attrtype Attribute type.
950  * @arg value Numeric value to store as payload.
951  *
952  * @see nla_put
953  * @return 0 on success or a negative error code.
954  */
955 int nla_put_u32(struct nl_msg *msg, int attrtype, uint32_t value)
956 {
957  return nla_put(msg, attrtype, sizeof(uint32_t), &value);
958 }
959 
960 /**
961  * Return payload of 32 bit integer attribute.
962  * @arg nla 32 bit integer attribute.
963  *
964  * @return Payload as 32 bit integer.
965  */
966 uint32_t nla_get_u32(struct nlattr *nla)
967 {
968  return *(uint32_t *) nla_data(nla);
969 }
970 
971 /**
972  * Add 64 bit integer attribute to netlink message.
973  * @arg msg Netlink message.
974  * @arg attrtype Attribute type.
975  * @arg value Numeric value to store as payload.
976  *
977  * @see nla_put
978  * @return 0 on success or a negative error code.
979  */
980 int nla_put_u64(struct nl_msg *msg, int attrtype, uint64_t value)
981 {
982  return nla_put(msg, attrtype, sizeof(uint64_t), &value);
983 }
984 
985 /**
986  * Return payload of u64 attribute
987  * @arg nla u64 netlink attribute
988  *
989  * @return Payload as 64 bit integer.
990  */
991 uint64_t nla_get_u64(struct nlattr *nla)
992 {
993  uint64_t tmp;
994 
995  nla_memcpy(&tmp, nla, sizeof(tmp));
996 
997  return tmp;
998 }
999 
1000 /** @} */
1001 
1002 /**
1003  * @name String Attribute
1004  */
1005 
1006 /**
1007  * Add string attribute to netlink message.
1008  * @arg msg Netlink message.
1009  * @arg attrtype Attribute type.
1010  * @arg str NUL terminated string.
1011  *
1012  * @see nla_put
1013  * @return 0 on success or a negative error code.
1014  */
1015 int nla_put_string(struct nl_msg *msg, int attrtype, const char *str)
1016 {
1017  return nla_put(msg, attrtype, strlen(str) + 1, str);
1018 }
1019 
1020 /**
1021  * Return payload of string attribute.
1022  * @arg nla String attribute.
1023  *
1024  * @return Pointer to attribute payload.
1025  */
1026 char *nla_get_string(struct nlattr *nla)
1027 {
1028  return (char *) nla_data(nla);
1029 }
1030 
1031 char *nla_strdup(struct nlattr *nla)
1032 {
1033  return strdup(nla_get_string(nla));
1034 }
1035 
1036 /** @} */
1037 
1038 /**
1039  * @name Flag Attribute
1040  */
1041 
1042 /**
1043  * Add flag netlink attribute to netlink message.
1044  * @arg msg Netlink message.
1045  * @arg attrtype Attribute type.
1046  *
1047  * @see nla_put
1048  * @return 0 on success or a negative error code.
1049  */
1050 int nla_put_flag(struct nl_msg *msg, int attrtype)
1051 {
1052  return nla_put(msg, attrtype, 0, NULL);
1053 }
1054 
1055 /**
1056  * Return true if flag attribute is set.
1057  * @arg nla Flag netlink attribute.
1058  *
1059  * @return True if flag is set, otherwise false.
1060  */
1061 int nla_get_flag(struct nlattr *nla)
1062 {
1063  return !!nla;
1064 }
1065 
1066 /** @} */
1067 
1068 /**
1069  * @name Microseconds Attribute
1070  */
1071 
1072 /**
1073  * Add a msecs netlink attribute to a netlink message
1074  * @arg n netlink message
1075  * @arg attrtype attribute type
1076  * @arg msecs number of msecs
1077  */
1078 int nla_put_msecs(struct nl_msg *n, int attrtype, unsigned long msecs)
1079 {
1080  return nla_put_u64(n, attrtype, msecs);
1081 }
1082 
1083 /**
1084  * Return payload of msecs attribute
1085  * @arg nla msecs netlink attribute
1086  *
1087  * @return the number of milliseconds.
1088  */
1089 unsigned long nla_get_msecs(struct nlattr *nla)
1090 {
1091  return nla_get_u64(nla);
1092 }
1093 
1094 /** @} */
1095 
1096 /**
1097  * @name Nested Attribute
1098  */
1099 
1100 /**
1101  * Add nested attributes to netlink message.
1102  * @arg msg Netlink message.
1103  * @arg attrtype Attribute type.
1104  * @arg nested Message containing attributes to be nested.
1105  *
1106  * Takes the attributes found in the \a nested message and appends them
1107  * to the message \a msg nested in a container of the type \a attrtype.
1108  * The \a nested message may not have a family specific header.
1109  *
1110  * @see nla_put
1111  * @return 0 on success or a negative error code.
1112  */
1113 int nla_put_nested(struct nl_msg *msg, int attrtype, struct nl_msg *nested)
1114 {
1115  NL_DBG(2, "msg %p: attr <> %d: adding msg %p as nested attribute\n",
1116  msg, attrtype, nested);
1117 
1118  return nla_put(msg, attrtype, nlmsg_datalen(nested->nm_nlh),
1119  nlmsg_data(nested->nm_nlh));
1120 }
1121 
1122 
1123 /**
1124  * Start a new level of nested attributes.
1125  * @arg msg Netlink message.
1126  * @arg attrtype Attribute type of container.
1127  *
1128  * @return Pointer to container attribute.
1129  */
1130 struct nlattr *nla_nest_start(struct nl_msg *msg, int attrtype)
1131 {
1132  struct nlattr *start = (struct nlattr *) nlmsg_tail(msg->nm_nlh);
1133 
1134  if (nla_put(msg, attrtype, 0, NULL) < 0)
1135  return NULL;
1136 
1137  NL_DBG(2, "msg %p: attr <%p> %d: starting nesting\n",
1138  msg, start, start->nla_type);
1139 
1140  return start;
1141 }
1142 
1143 /**
1144  * Finalize nesting of attributes.
1145  * @arg msg Netlink message.
1146  * @arg start Container attribute as returned from nla_nest_start().
1147  *
1148  * Corrects the container attribute header to include the appeneded attributes.
1149  *
1150  * @return 0
1151  */
1152 int nla_nest_end(struct nl_msg *msg, struct nlattr *start)
1153 {
1154  size_t pad, len;
1155 
1156  len = (void *) nlmsg_tail(msg->nm_nlh) - (void *) start;
1157 
1158  if (len == NLA_HDRLEN) {
1159  /*
1160  * Kernel can't handle empty nested attributes, trim the
1161  * attribute header again
1162  */
1163  msg->nm_nlh->nlmsg_len -= NLA_HDRLEN;
1164  memset(nlmsg_tail(msg->nm_nlh), 0, NLA_HDRLEN);
1165 
1166  return 0;
1167  }
1168 
1169  start->nla_len = len;
1170 
1171  pad = NLMSG_ALIGN(msg->nm_nlh->nlmsg_len) - msg->nm_nlh->nlmsg_len;
1172  if (pad > 0) {
1173  /*
1174  * Data inside attribute does not end at a alignment boundry.
1175  * Pad accordingly and accoun for the additional space in
1176  * the message. nlmsg_reserve() may never fail in this situation,
1177  * the allocate message buffer must be a multiple of NLMSG_ALIGNTO.
1178  */
1179  if (!nlmsg_reserve(msg, pad, 0))
1180  BUG();
1181 
1182  NL_DBG(2, "msg %p: attr <%p> %d: added %zu bytes of padding\n",
1183  msg, start, start->nla_type, pad);
1184  }
1185 
1186  NL_DBG(2, "msg %p: attr <%p> %d: closing nesting, len=%u\n",
1187  msg, start, start->nla_type, start->nla_len);
1188 
1189  return 0;
1190 }
1191 
1192 /**
1193  * Create attribute index based on nested attribute
1194  * @arg tb Index array to be filled (maxtype+1 elements).
1195  * @arg maxtype Maximum attribute type expected and accepted.
1196  * @arg nla Nested Attribute.
1197  * @arg policy Attribute validation policy.
1198  *
1199  * Feeds the stream of attributes nested into the specified attribute
1200  * to nla_parse().
1201  *
1202  * @see nla_parse
1203  * @return 0 on success or a negative error code.
1204  */
1205 int nla_parse_nested(struct nlattr *tb[], int maxtype, struct nlattr *nla,
1206  struct nla_policy *policy)
1207 {
1208  return nla_parse(tb, maxtype, nla_data(nla), nla_len(nla), policy);
1209 }
1210 
1211 /** @} */
1212 
1213 /** @} */