1*4882a593Smuzhiyun======================================== 2*4882a593SmuzhiyunNetLabel Linux Security Module Interface 3*4882a593Smuzhiyun======================================== 4*4882a593Smuzhiyun 5*4882a593SmuzhiyunPaul Moore, paul.moore@hp.com 6*4882a593Smuzhiyun 7*4882a593SmuzhiyunMay 17, 2006 8*4882a593Smuzhiyun 9*4882a593SmuzhiyunOverview 10*4882a593Smuzhiyun======== 11*4882a593Smuzhiyun 12*4882a593SmuzhiyunNetLabel is a mechanism which can set and retrieve security attributes from 13*4882a593Smuzhiyunnetwork packets. It is intended to be used by LSM developers who want to make 14*4882a593Smuzhiyunuse of a common code base for several different packet labeling protocols. 15*4882a593SmuzhiyunThe NetLabel security module API is defined in 'include/net/netlabel.h' but a 16*4882a593Smuzhiyunbrief overview is given below. 17*4882a593Smuzhiyun 18*4882a593SmuzhiyunNetLabel Security Attributes 19*4882a593Smuzhiyun============================ 20*4882a593Smuzhiyun 21*4882a593SmuzhiyunSince NetLabel supports multiple different packet labeling protocols and LSMs 22*4882a593Smuzhiyunit uses the concept of security attributes to refer to the packet's security 23*4882a593Smuzhiyunlabels. The NetLabel security attributes are defined by the 24*4882a593Smuzhiyun'netlbl_lsm_secattr' structure in the NetLabel header file. Internally the 25*4882a593SmuzhiyunNetLabel subsystem converts the security attributes to and from the correct 26*4882a593Smuzhiyunlow-level packet label depending on the NetLabel build time and run time 27*4882a593Smuzhiyunconfiguration. It is up to the LSM developer to translate the NetLabel 28*4882a593Smuzhiyunsecurity attributes into whatever security identifiers are in use for their 29*4882a593Smuzhiyunparticular LSM. 30*4882a593Smuzhiyun 31*4882a593SmuzhiyunNetLabel LSM Protocol Operations 32*4882a593Smuzhiyun================================ 33*4882a593Smuzhiyun 34*4882a593SmuzhiyunThese are the functions which allow the LSM developer to manipulate the labels 35*4882a593Smuzhiyunon outgoing packets as well as read the labels on incoming packets. Functions 36*4882a593Smuzhiyunexist to operate both on sockets as well as the sk_buffs directly. These high 37*4882a593Smuzhiyunlevel functions are translated into low level protocol operations based on how 38*4882a593Smuzhiyunthe administrator has configured the NetLabel subsystem. 39*4882a593Smuzhiyun 40*4882a593SmuzhiyunNetLabel Label Mapping Cache Operations 41*4882a593Smuzhiyun======================================= 42*4882a593Smuzhiyun 43*4882a593SmuzhiyunDepending on the exact configuration, translation between the network packet 44*4882a593Smuzhiyunlabel and the internal LSM security identifier can be time consuming. The 45*4882a593SmuzhiyunNetLabel label mapping cache is a caching mechanism which can be used to 46*4882a593Smuzhiyunsidestep much of this overhead once a mapping has been established. Once the 47*4882a593SmuzhiyunLSM has received a packet, used NetLabel to decode its security attributes, 48*4882a593Smuzhiyunand translated the security attributes into a LSM internal identifier the LSM 49*4882a593Smuzhiyuncan use the NetLabel caching functions to associate the LSM internal 50*4882a593Smuzhiyunidentifier with the network packet's label. This means that in the future 51*4882a593Smuzhiyunwhen a incoming packet matches a cached value not only are the internal 52*4882a593SmuzhiyunNetLabel translation mechanisms bypassed but the LSM translation mechanisms are 53*4882a593Smuzhiyunbypassed as well which should result in a significant reduction in overhead. 54