From: Mauro Carvalho Chehab Date: Wed, 12 Jun 2019 17:52:52 +0000 (-0300) Subject: docs: netlabel: convert docs to ReST and rename to *.rst X-Git-Url: http://git.lede-project.org./?a=commitdiff_plain;h=593733ab80ac2c607acc1fc3fbaba5031d38253a;p=openwrt%2Fstaging%2Fblogic.git docs: netlabel: convert docs to ReST and rename to *.rst Convert netlabel documentation to ReST. This was trivial: just add proper title markups. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab Acked-by: Paul Moore Signed-off-by: Jonathan Corbet --- diff --git a/Documentation/netlabel/cipso_ipv4.rst b/Documentation/netlabel/cipso_ipv4.rst new file mode 100644 index 000000000000..cbd3f3231221 --- /dev/null +++ b/Documentation/netlabel/cipso_ipv4.rst @@ -0,0 +1,56 @@ +=================================== +NetLabel CIPSO/IPv4 Protocol Engine +=================================== + +Paul Moore, paul.moore@hp.com + +May 17, 2006 + +Overview +======== + +The NetLabel CIPSO/IPv4 protocol engine is based on the IETF Commercial +IP Security Option (CIPSO) draft from July 16, 1992. A copy of this +draft can be found in this directory +(draft-ietf-cipso-ipsecurity-01.txt). While the IETF draft never made +it to an RFC standard it has become a de-facto standard for labeled +networking and is used in many trusted operating systems. + +Outbound Packet Processing +========================== + +The CIPSO/IPv4 protocol engine applies the CIPSO IP option to packets by +adding the CIPSO label to the socket. This causes all packets leaving the +system through the socket to have the CIPSO IP option applied. The socket's +CIPSO label can be changed at any point in time, however, it is recommended +that it is set upon the socket's creation. The LSM can set the socket's CIPSO +label by using the NetLabel security module API; if the NetLabel "domain" is +configured to use CIPSO for packet labeling then a CIPSO IP option will be +generated and attached to the socket. + +Inbound Packet Processing +========================= + +The CIPSO/IPv4 protocol engine validates every CIPSO IP option it finds at the +IP layer without any special handling required by the LSM. However, in order +to decode and translate the CIPSO label on the packet the LSM must use the +NetLabel security module API to extract the security attributes of the packet. +This is typically done at the socket layer using the 'socket_sock_rcv_skb()' +LSM hook. + +Label Translation +================= + +The CIPSO/IPv4 protocol engine contains a mechanism to translate CIPSO security +attributes such as sensitivity level and category to values which are +appropriate for the host. These mappings are defined as part of a CIPSO +Domain Of Interpretation (DOI) definition and are configured through the +NetLabel user space communication layer. Each DOI definition can have a +different security attribute mapping table. + +Label Translation Cache +======================= + +The NetLabel system provides a framework for caching security attribute +mappings from the network labels to the corresponding LSM identifiers. The +CIPSO/IPv4 protocol engine supports this caching mechanism. diff --git a/Documentation/netlabel/cipso_ipv4.txt b/Documentation/netlabel/cipso_ipv4.txt deleted file mode 100644 index a6075481fd60..000000000000 --- a/Documentation/netlabel/cipso_ipv4.txt +++ /dev/null @@ -1,49 +0,0 @@ -NetLabel CIPSO/IPv4 Protocol Engine -============================================================================== -Paul Moore, paul.moore@hp.com - -May 17, 2006 - - * Overview - -The NetLabel CIPSO/IPv4 protocol engine is based on the IETF Commercial -IP Security Option (CIPSO) draft from July 16, 1992. A copy of this -draft can be found in this directory -(draft-ietf-cipso-ipsecurity-01.txt). While the IETF draft never made -it to an RFC standard it has become a de-facto standard for labeled -networking and is used in many trusted operating systems. - - * Outbound Packet Processing - -The CIPSO/IPv4 protocol engine applies the CIPSO IP option to packets by -adding the CIPSO label to the socket. This causes all packets leaving the -system through the socket to have the CIPSO IP option applied. The socket's -CIPSO label can be changed at any point in time, however, it is recommended -that it is set upon the socket's creation. The LSM can set the socket's CIPSO -label by using the NetLabel security module API; if the NetLabel "domain" is -configured to use CIPSO for packet labeling then a CIPSO IP option will be -generated and attached to the socket. - - * Inbound Packet Processing - -The CIPSO/IPv4 protocol engine validates every CIPSO IP option it finds at the -IP layer without any special handling required by the LSM. However, in order -to decode and translate the CIPSO label on the packet the LSM must use the -NetLabel security module API to extract the security attributes of the packet. -This is typically done at the socket layer using the 'socket_sock_rcv_skb()' -LSM hook. - - * Label Translation - -The CIPSO/IPv4 protocol engine contains a mechanism to translate CIPSO security -attributes such as sensitivity level and category to values which are -appropriate for the host. These mappings are defined as part of a CIPSO -Domain Of Interpretation (DOI) definition and are configured through the -NetLabel user space communication layer. Each DOI definition can have a -different security attribute mapping table. - - * Label Translation Cache - -The NetLabel system provides a framework for caching security attribute -mappings from the network labels to the corresponding LSM identifiers. The -CIPSO/IPv4 protocol engine supports this caching mechanism. diff --git a/Documentation/netlabel/draft_ietf.rst b/Documentation/netlabel/draft_ietf.rst new file mode 100644 index 000000000000..5ed39ab8234b --- /dev/null +++ b/Documentation/netlabel/draft_ietf.rst @@ -0,0 +1,5 @@ +Draft IETF CIPSO IP Security +---------------------------- + + .. include:: draft-ietf-cipso-ipsecurity-01.txt + :literal: diff --git a/Documentation/netlabel/index.rst b/Documentation/netlabel/index.rst new file mode 100644 index 000000000000..47f1e0e5acd1 --- /dev/null +++ b/Documentation/netlabel/index.rst @@ -0,0 +1,21 @@ +:orphan: + +======== +NetLabel +======== + +.. toctree:: + :maxdepth: 1 + + introduction + cipso_ipv4 + lsm_interface + + draft_ietf + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/netlabel/introduction.rst b/Documentation/netlabel/introduction.rst new file mode 100644 index 000000000000..9333bbb0adc1 --- /dev/null +++ b/Documentation/netlabel/introduction.rst @@ -0,0 +1,52 @@ +===================== +NetLabel Introduction +===================== + +Paul Moore, paul.moore@hp.com + +August 2, 2006 + +Overview +======== + +NetLabel is a mechanism which can be used by kernel security modules to attach +security attributes to outgoing network packets generated from user space +applications and read security attributes from incoming network packets. It +is composed of three main components, the protocol engines, the communication +layer, and the kernel security module API. + +Protocol Engines +================ + +The protocol engines are responsible for both applying and retrieving the +network packet's security attributes. If any translation between the network +security attributes and those on the host are required then the protocol +engine will handle those tasks as well. Other kernel subsystems should +refrain from calling the protocol engines directly, instead they should use +the NetLabel kernel security module API described below. + +Detailed information about each NetLabel protocol engine can be found in this +directory. + +Communication Layer +=================== + +The communication layer exists to allow NetLabel configuration and monitoring +from user space. The NetLabel communication layer uses a message based +protocol built on top of the Generic NETLINK transport mechanism. The exact +formatting of these NetLabel messages as well as the Generic NETLINK family +names can be found in the 'net/netlabel/' directory as comments in the +header files as well as in 'include/net/netlabel.h'. + +Security Module API +=================== + +The purpose of the NetLabel security module API is to provide a protocol +independent interface to the underlying NetLabel protocol engines. In addition +to protocol independence, the security module API is designed to be completely +LSM independent which should allow multiple LSMs to leverage the same code +base. + +Detailed information about the NetLabel security module API can be found in the +'include/net/netlabel.h' header file as well as the 'lsm_interface.txt' file +found in this directory. diff --git a/Documentation/netlabel/introduction.txt b/Documentation/netlabel/introduction.txt deleted file mode 100644 index 3caf77bcff0f..000000000000 --- a/Documentation/netlabel/introduction.txt +++ /dev/null @@ -1,46 +0,0 @@ -NetLabel Introduction -============================================================================== -Paul Moore, paul.moore@hp.com - -August 2, 2006 - - * Overview - -NetLabel is a mechanism which can be used by kernel security modules to attach -security attributes to outgoing network packets generated from user space -applications and read security attributes from incoming network packets. It -is composed of three main components, the protocol engines, the communication -layer, and the kernel security module API. - - * Protocol Engines - -The protocol engines are responsible for both applying and retrieving the -network packet's security attributes. If any translation between the network -security attributes and those on the host are required then the protocol -engine will handle those tasks as well. Other kernel subsystems should -refrain from calling the protocol engines directly, instead they should use -the NetLabel kernel security module API described below. - -Detailed information about each NetLabel protocol engine can be found in this -directory. - - * Communication Layer - -The communication layer exists to allow NetLabel configuration and monitoring -from user space. The NetLabel communication layer uses a message based -protocol built on top of the Generic NETLINK transport mechanism. The exact -formatting of these NetLabel messages as well as the Generic NETLINK family -names can be found in the 'net/netlabel/' directory as comments in the -header files as well as in 'include/net/netlabel.h'. - - * Security Module API - -The purpose of the NetLabel security module API is to provide a protocol -independent interface to the underlying NetLabel protocol engines. In addition -to protocol independence, the security module API is designed to be completely -LSM independent which should allow multiple LSMs to leverage the same code -base. - -Detailed information about the NetLabel security module API can be found in the -'include/net/netlabel.h' header file as well as the 'lsm_interface.txt' file -found in this directory. diff --git a/Documentation/netlabel/lsm_interface.rst b/Documentation/netlabel/lsm_interface.rst new file mode 100644 index 000000000000..026fc267f798 --- /dev/null +++ b/Documentation/netlabel/lsm_interface.rst @@ -0,0 +1,53 @@ +======================================== +NetLabel Linux Security Module Interface +======================================== + +Paul Moore, paul.moore@hp.com + +May 17, 2006 + +Overview +======== + +NetLabel is a mechanism which can set and retrieve security attributes from +network packets. It is intended to be used by LSM developers who want to make +use of a common code base for several different packet labeling protocols. +The NetLabel security module API is defined in 'include/net/netlabel.h' but a +brief overview is given below. + +NetLabel Security Attributes +============================ + +Since NetLabel supports multiple different packet labeling protocols and LSMs +it uses the concept of security attributes to refer to the packet's security +labels. The NetLabel security attributes are defined by the +'netlbl_lsm_secattr' structure in the NetLabel header file. Internally the +NetLabel subsystem converts the security attributes to and from the correct +low-level packet label depending on the NetLabel build time and run time +configuration. It is up to the LSM developer to translate the NetLabel +security attributes into whatever security identifiers are in use for their +particular LSM. + +NetLabel LSM Protocol Operations +================================ + +These are the functions which allow the LSM developer to manipulate the labels +on outgoing packets as well as read the labels on incoming packets. Functions +exist to operate both on sockets as well as the sk_buffs directly. These high +level functions are translated into low level protocol operations based on how +the administrator has configured the NetLabel subsystem. + +NetLabel Label Mapping Cache Operations +======================================= + +Depending on the exact configuration, translation between the network packet +label and the internal LSM security identifier can be time consuming. The +NetLabel label mapping cache is a caching mechanism which can be used to +sidestep much of this overhead once a mapping has been established. Once the +LSM has received a packet, used NetLabel to decode its security attributes, +and translated the security attributes into a LSM internal identifier the LSM +can use the NetLabel caching functions to associate the LSM internal +identifier with the network packet's label. This means that in the future +when a incoming packet matches a cached value not only are the internal +NetLabel translation mechanisms bypassed but the LSM translation mechanisms are +bypassed as well which should result in a significant reduction in overhead. diff --git a/Documentation/netlabel/lsm_interface.txt b/Documentation/netlabel/lsm_interface.txt deleted file mode 100644 index 638c74f7de7f..000000000000 --- a/Documentation/netlabel/lsm_interface.txt +++ /dev/null @@ -1,47 +0,0 @@ -NetLabel Linux Security Module Interface -============================================================================== -Paul Moore, paul.moore@hp.com - -May 17, 2006 - - * Overview - -NetLabel is a mechanism which can set and retrieve security attributes from -network packets. It is intended to be used by LSM developers who want to make -use of a common code base for several different packet labeling protocols. -The NetLabel security module API is defined in 'include/net/netlabel.h' but a -brief overview is given below. - - * NetLabel Security Attributes - -Since NetLabel supports multiple different packet labeling protocols and LSMs -it uses the concept of security attributes to refer to the packet's security -labels. The NetLabel security attributes are defined by the -'netlbl_lsm_secattr' structure in the NetLabel header file. Internally the -NetLabel subsystem converts the security attributes to and from the correct -low-level packet label depending on the NetLabel build time and run time -configuration. It is up to the LSM developer to translate the NetLabel -security attributes into whatever security identifiers are in use for their -particular LSM. - - * NetLabel LSM Protocol Operations - -These are the functions which allow the LSM developer to manipulate the labels -on outgoing packets as well as read the labels on incoming packets. Functions -exist to operate both on sockets as well as the sk_buffs directly. These high -level functions are translated into low level protocol operations based on how -the administrator has configured the NetLabel subsystem. - - * NetLabel Label Mapping Cache Operations - -Depending on the exact configuration, translation between the network packet -label and the internal LSM security identifier can be time consuming. The -NetLabel label mapping cache is a caching mechanism which can be used to -sidestep much of this overhead once a mapping has been established. Once the -LSM has received a packet, used NetLabel to decode its security attributes, -and translated the security attributes into a LSM internal identifier the LSM -can use the NetLabel caching functions to associate the LSM internal -identifier with the network packet's label. This means that in the future -when a incoming packet matches a cached value not only are the internal -NetLabel translation mechanisms bypassed but the LSM translation mechanisms are -bypassed as well which should result in a significant reduction in overhead.