Re: [PATCH v3 18/33] docs: netlabel: convert docs to ReST and rename to *.rst

Paul Moore
2019-06-12T14:48:27Z

On Sat, Jun 8, 2019 at 10:27 PM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> 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 <mchehab+samsung@kernel.org>
> ---
> .../{cipso_ipv4.txt => cipso_ipv4.rst} | 19 +++++++++++------
> Documentation/netlabel/draft_ietf.rst | 5 +++++
> Documentation/netlabel/index.rst | 21 +++++++++++++++++++
> .../{introduction.txt => introduction.rst} | 16 +++++++++-----
> .../{lsm_interface.txt => lsm_interface.rst} | 16 +++++++++-----
> 5 files changed, 61 insertions(+), 16 deletions(-)
> rename Documentation/netlabel/{cipso_ipv4.txt => cipso_ipv4.rst} (87%)
> create mode 100644 Documentation/netlabel/draft_ietf.rst
> create mode 100644 Documentation/netlabel/index.rst
> rename Documentation/netlabel/{introduction.txt => introduction.rst} (91%)
> rename Documentation/netlabel/{lsm_interface.txt => lsm_interface.rst} (88%)

I'm fairly confident I've already acked this at least once, but here
it is again:

Acked-by: Paul Moore <paul@paul-moore.com>

> diff --git a/Documentation/netlabel/cipso_ipv4.txt b/Documentation/netlabel/cipso_ipv4.rst
> similarity index 87%
> rename from Documentation/netlabel/cipso_ipv4.txt
> rename to Documentation/netlabel/cipso_ipv4.rst
> index a6075481fd60..cbd3f3231221 100644
> --- a/Documentation/netlabel/cipso_ipv4.txt
> +++ b/Documentation/netlabel/cipso_ipv4.rst
> @@ -1,10 +1,13 @@
> +===================================
> NetLabel CIPSO/IPv4 Protocol Engine
> -==============================================================================
> +===================================
> +
> Paul Moore, paul.moore@hp.com
>
> May 17, 2006
>
> - * Overview
> +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
> @@ -13,7 +16,8 @@ draft can be found in this directory
> 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
> +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
> @@ -24,7 +28,8 @@ 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
> +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
> @@ -33,7 +38,8 @@ 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
> +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
> @@ -42,7 +48,8 @@ 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
> +Label Translation Cache
> +=======================
>
> The NetLabel system provides a framework for caching security attribute
> mappings from the network labels to the corresponding LSM identifiers. The
> 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.txt b/Documentation/netlabel/introduction.rst
> similarity index 91%
> rename from Documentation/netlabel/introduction.txt
> rename to Documentation/netlabel/introduction.rst
> index 3caf77bcff0f..9333bbb0adc1 100644
> --- a/Documentation/netlabel/introduction.txt
> +++ b/Documentation/netlabel/introduction.rst
> @@ -1,10 +1,13 @@
> +=====================
> NetLabel Introduction
> -==============================================================================
> +=====================
> +
> Paul Moore, paul.moore@hp.com
>
> August 2, 2006
>
> - * Overview
> +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
> @@ -12,7 +15,8 @@ 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
> +Protocol Engines
> +================
>
> The protocol engines are responsible for both applying and retrieving the
> network packet's security attributes. If any translation between the network
> @@ -24,7 +28,8 @@ the NetLabel kernel security module API described below.
> Detailed information about each NetLabel protocol engine can be found in this
> directory.
>
> - * Communication Layer
> +Communication Layer
> +===================
>
> The communication layer exists to allow NetLabel configuration and monitoring
> from user space. The NetLabel communication layer uses a message based
> @@ -33,7 +38,8 @@ 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
> +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
> diff --git a/Documentation/netlabel/lsm_interface.txt b/Documentation/netlabel/lsm_interface.rst
> similarity index 88%
> rename from Documentation/netlabel/lsm_interface.txt
> rename to Documentation/netlabel/lsm_interface.rst
> index 638c74f7de7f..026fc267f798 100644
> --- a/Documentation/netlabel/lsm_interface.txt
> +++ b/Documentation/netlabel/lsm_interface.rst
> @@ -1,10 +1,13 @@
> +========================================
> NetLabel Linux Security Module Interface
> -==============================================================================
> +========================================
> +
> Paul Moore, paul.moore@hp.com
>
> May 17, 2006
>
> - * Overview
> +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
> @@ -12,7 +15,8 @@ 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
> +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
> @@ -24,7 +28,8 @@ 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
> +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
> @@ -32,7 +37,8 @@ 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
> +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
> --
> 2.21.0
>

--
paul moore