Library support for WiFi - an overview -------------------------------------- #ident "@(#)lib-wifi.txt 1.3 06/06/22 SMI" 1. Introduction --------------- As part of implementing wireless support for dladm, a new library libwladm, used for managing wireless links, will be introduced; and new APIs will be added to libdladm for managing link properties and secure objects. This document aims to provide an overview of the new interfaces and some insights into the reasoning behind their design. For details regarding their usage, please refer the interface specifications[1]. 2. libwladm ----------- The libwladm library provides an API for administering wireless links. While we could have folded this API directly into libdladm, we chose not to because of: 1. Consistency: dladm currently makes use of distinct libraries for distinct technology areas -- e.g., liblaadm is provided for link aggregation administration. Architecturally, this also provides a clean separation between interface and functionality, and we believe wireless support should be implemented similarly. 2. Opportunity for wider use: our competitors today (Linux, Windows) provide some form of API for managing WLANs. While libwladm is not currently functionally rich enough to be made public, it can certainly form the basis of the API that we do make public in the future. A note on the nomenclature: The 'wl' in 'libwladm' stands for Wireless LAN. We could have called it libwifiadm but chose not to. The reason is that most of libwladm's interfaces are media independent and it makes sense, in terms of code reuse, for the support of future WLAN types to be based on the same codebase rather than a different one. The interfaces in libwladm can be categorized into three groups: 1. Wireless Operations: This group contains the core functionality of this library. It provides interfaces for scanning WLANs, connecting to and disconnecting from WLANs, and enumerating and querying attributes of wireless links. These interfaces roughly correspond to the commands discussed in [2]. The implementation depends on the wifi_ioctl.h interface [3], which is supported by all Solaris wireless drivers. 2. Wireless Link Property Support: This group provides interfaces for enumerating, setting and getting link properties. Only properties recognized by the library may be set or gotten. The implementation also depends on wifi_ioctl.h[3]. A more thorough discussion of link properties can be found in section 3.1 below. 3. Wireless String Conversion Routines: This group provides interfaces for simplifying options parsing and results displaying. For example, wladm_str2xyz() would convert a string to the data type wladm_xyz_t; and wladm_xyz2str() would do the reverse. These are useful in that they allow the library to evolve independently of the application (in this case, dladm). If these aren't provided, dladm would have to encode/decode wladm data types itself, which would in turn restrict the amount of independent changes that can be made in libwladm. 3. libdladm ----------- The libdladm library was introduced as part of the Nemo project [4]. It is used for managing data links and is intended to be general purpose and media-independent. Its interfaces are currently private to dladm and are limited in functionality; only the enumeration of data links and retrieval of their attributes are supported. This project will add link properties and secure objects support to libdladm. This is in keeping with libdladm's generality and media-independence. 3.1 Link properties ------------------- In this section we will discuss how we arrived at the decision to implement link property support within libdladm. Below are the primary architectural options we considered: a) No change to libdladm The *-linkprop subcommands described in [2] can be implemented without changing libdladm. The *-linkprop commands can be made to directly invoke the libwladm's wladm_*_linkprop() interfaces. The issue with this design is that it lacks extensibility. dladm would have to be modified every time we add link property support for a new link type. Ideally, dladm should not need to be aware of which link type it is operating on. Another issue is the implementation of persistent properties: without centralizing the persistence logic within libdladm, each link-specific library would have to implement persistence itself and maintain its own configuration repository. b) Replacing ndd Link properties can be implemented as a replacement for ndd. This is the most general approach and is in fact one of our long term goals. The issue with this approach is that a set of generic ndd-like ioctls will need to be introduced and all drivers supporting link properties will have to implement them. Currently only wifi drivers support link properties and ioctls [3] are used to get/set these properties. Substantial changes to the drivers will be needed to have them support generic ioctls. Also, if we do take this approach, there is no guarantee we will accommodate all needs of future link types. Rather than overengineering our design now, we feel that it's less risky to leave the wifi ioctls alone. This leads to our third alternative, which is discussed below. c) Layered design Like option a) above, we rely on libwladm to deal with link-specific aspects of link properties. Unlike a), dladm would make use of libdladm's own *_linkprop() interfaces for manipulating link properties. These libdladm interfaces would internally invoke wladm_*_linkprop() from libwladm and would have logic for handling persistence. This design is extensible in that if a new link type is to be supported, we would only need to modify libdladm to detect this new link type and invoke the *_linkprop() interfaces corresponding to this link type. Persistence would be handled for free and dladm would need no changes. This last point - no changes to the application - will become important when applications other than dladm start using libdladm. Also note that this design does not preclude option b) from being realized. In fact, the attractiveness of this design is that it allows a slow migration to b) without disturbing any applications. 3.2 Secure Objects ------------------ As discussed in [2], secure objects are introduced for facilitating the management of sensitive information such as keys. In the context of WiFi, secure objects enable a non-privileged user to access a secured network without knowing the values of the network's encryption keys. It is important to note that while security objects could play a larger role in Solaris, this is, in the short term, not our intention. The inclusion of secure objects within libdladm reflects this decision. For now, secure objects are provided for supporting network devices only. Initial support will include the ability to set, get, delete, and enumerate secure objects. Objects are byte arrays with a fixed maximum size and, for now, must belong to the WEP class. For set, optional create-if-not-exists semantics is provided. Internally, the implementation relies on 3 ioctls exported by the dld driver for maintaining secure objects within the kernel. dladm makes use of secure objects for implementing WEP support for the connect-wifi command [2]. Upon obtaining the user-specified key names, dladm would obtain the key values from the kernel and refeed these values back to wladm_connect(). This step could potentially be skipped if there exists a way for a wireless driver to translate key names into key values. From the kernel's standpoint, this is doable and would only require dld to expose certain entry points to kernel consumers. The issue is that, because of backward compatibility with wificonfig, the wifi driver ioctl [3] for connection- initiation cannot be modified to behave this way. We will revisit this issue again in the future when we EOL wificonfig and settle on a system-wide wireless driver ioctl interface. 4. Future Work -------------- 4.1 libwladm ------------ Currently, dladm would fail if one attempts to display the key names associated with a link. To fix this would require changing the set-wepkey ioctl such that the key names would get passed along with the key values into the kernel. Such a change would unfortunately break backward compatibility with wificonfig. An alternative would be to introduce another ioctl for setting just the key names. This would work, but in order to minimize driver changes, we feel that it would be better to wait until all wifi drivers are ported to the common wifi framework. The ioctl can then be added to the framework and be usable by all drivers. 4.2 libdladm ------------ A number of people have asked for the ability do set-linkprop on a non-wireless link. Their requests are mostly related to setting a single integer variable within a driver. With our current design, implementing this should be fairly simple and would only involve changes to libdladm and the addition/modification of some ioctl interfaces. 5. References ------------- [1] libdladm/libwladm Interface Specifications: libdladm.txt and libwladm.txt [in materials] [2] Extending dladm for WiFi: An Administrative Overview: dladm-wifi.pdf [in materials] [3] PSARC/2003/722 WiFi PCMCIA Driver Productization http://sac.sfbay.sun.com/Archives/CaseLog/arc/PSARC/2003/722/ [4] PSARC/2004/571 Nemo - a.k.a. GLDv3 http://sac.sfbay.sun.com/Archives/CaseLog/arc/PSARC/2004/571/