18c2ecf20Sopenharmony_ci======================================== 28c2ecf20Sopenharmony_ciNetLabel Linux Security Module Interface 38c2ecf20Sopenharmony_ci======================================== 48c2ecf20Sopenharmony_ci 58c2ecf20Sopenharmony_ciPaul Moore, paul.moore@hp.com 68c2ecf20Sopenharmony_ci 78c2ecf20Sopenharmony_ciMay 17, 2006 88c2ecf20Sopenharmony_ci 98c2ecf20Sopenharmony_ciOverview 108c2ecf20Sopenharmony_ci======== 118c2ecf20Sopenharmony_ci 128c2ecf20Sopenharmony_ciNetLabel is a mechanism which can set and retrieve security attributes from 138c2ecf20Sopenharmony_cinetwork packets. It is intended to be used by LSM developers who want to make 148c2ecf20Sopenharmony_ciuse of a common code base for several different packet labeling protocols. 158c2ecf20Sopenharmony_ciThe NetLabel security module API is defined in 'include/net/netlabel.h' but a 168c2ecf20Sopenharmony_cibrief overview is given below. 178c2ecf20Sopenharmony_ci 188c2ecf20Sopenharmony_ciNetLabel Security Attributes 198c2ecf20Sopenharmony_ci============================ 208c2ecf20Sopenharmony_ci 218c2ecf20Sopenharmony_ciSince NetLabel supports multiple different packet labeling protocols and LSMs 228c2ecf20Sopenharmony_ciit uses the concept of security attributes to refer to the packet's security 238c2ecf20Sopenharmony_cilabels. The NetLabel security attributes are defined by the 248c2ecf20Sopenharmony_ci'netlbl_lsm_secattr' structure in the NetLabel header file. Internally the 258c2ecf20Sopenharmony_ciNetLabel subsystem converts the security attributes to and from the correct 268c2ecf20Sopenharmony_cilow-level packet label depending on the NetLabel build time and run time 278c2ecf20Sopenharmony_ciconfiguration. It is up to the LSM developer to translate the NetLabel 288c2ecf20Sopenharmony_cisecurity attributes into whatever security identifiers are in use for their 298c2ecf20Sopenharmony_ciparticular LSM. 308c2ecf20Sopenharmony_ci 318c2ecf20Sopenharmony_ciNetLabel LSM Protocol Operations 328c2ecf20Sopenharmony_ci================================ 338c2ecf20Sopenharmony_ci 348c2ecf20Sopenharmony_ciThese are the functions which allow the LSM developer to manipulate the labels 358c2ecf20Sopenharmony_cion outgoing packets as well as read the labels on incoming packets. Functions 368c2ecf20Sopenharmony_ciexist to operate both on sockets as well as the sk_buffs directly. These high 378c2ecf20Sopenharmony_cilevel functions are translated into low level protocol operations based on how 388c2ecf20Sopenharmony_cithe administrator has configured the NetLabel subsystem. 398c2ecf20Sopenharmony_ci 408c2ecf20Sopenharmony_ciNetLabel Label Mapping Cache Operations 418c2ecf20Sopenharmony_ci======================================= 428c2ecf20Sopenharmony_ci 438c2ecf20Sopenharmony_ciDepending on the exact configuration, translation between the network packet 448c2ecf20Sopenharmony_cilabel and the internal LSM security identifier can be time consuming. The 458c2ecf20Sopenharmony_ciNetLabel label mapping cache is a caching mechanism which can be used to 468c2ecf20Sopenharmony_cisidestep much of this overhead once a mapping has been established. Once the 478c2ecf20Sopenharmony_ciLSM has received a packet, used NetLabel to decode its security attributes, 488c2ecf20Sopenharmony_ciand translated the security attributes into a LSM internal identifier the LSM 498c2ecf20Sopenharmony_cican use the NetLabel caching functions to associate the LSM internal 508c2ecf20Sopenharmony_ciidentifier with the network packet's label. This means that in the future 518c2ecf20Sopenharmony_ciwhen a incoming packet matches a cached value not only are the internal 528c2ecf20Sopenharmony_ciNetLabel translation mechanisms bypassed but the LSM translation mechanisms are 538c2ecf20Sopenharmony_cibypassed as well which should result in a significant reduction in overhead. 54