[PATCH 06/13] objects: Convert to markdown

[Richard Haines <richard_c_haines@btinternet.com>]

Add a TOC to aid navigation and convert to markdown.

Signed-off-by: Richard Haines <richard_c_haines@btinternet.com>
---
 src/objects.md | 185 +++++++++++++++++++++++++------------------------
 1 file changed, 95 insertions(+), 90 deletions(-)

diff --git a/src/objects.md b/src/objects.md
index 09c77f3..8762cb9 100644
--- a/src/objects.md
+++ b/src/objects.md
@@ -1,5 +1,13 @@
 # Objects
 
+- [Object Classes and Permissions](#object-classes-and-permissions)
+- [Allowing a Process Access to Resources](#allowing-a-process-access-to-resources)
+- [Labeling Objects](#labeling-objects)
+  - [Labeling Extended Attribute Filesystems](#labeling-extended-attribute-filesystems)
+    - [Copying and Moving Files](#copying-and-moving-files)
+- [Labeling Subjects](#labeling-subjects)
+- [Object Reuse](#object-reuse)
+
 Within SELinux an object is a resource such as files, sockets, pipes or
 network interfaces that are accessed via processes (also known as
 subjects). These objects are classified according to the resource they
@@ -11,8 +19,8 @@ in the following sections.
 ## Object Classes and Permissions
 
 Each object consists of a class identifier that defines its purpose
-(e.g. file, socket) along with a set of permissions (Also known in SELinux
-as Access Vectors (AV)) that describe what services the object can handle
+(e.g. file, socket) along with a set of permissions (also known as Access
+Vectors (AV)) that describe what services the object can handle
 (read, write, send etc.).
 When an object is instantiated it will be allocated a name (e.g. a file
 could be called config or a socket my_connection) and a security
@@ -23,7 +31,7 @@ context (e.g. *system_u:object_r:selinux_config_t*) as shown in
 
 **Figure 5: Object Class = 'file' and permissions** - *the policy rules would
 define those permissions allowed for each process that needs access to
-the */etc/selinux/config* file.*
+the /etc/selinux/config file.*
 
 The objective of the policy is to enable the user of the object (the
 subject) access to the minimum permissions needed to complete the task
@@ -45,9 +53,9 @@ permissions are described in
 
 This is a simple example that attempts to explain two points:
 
-1.  How a process is given permission to use an objects resource.
-2.  By using the *process* object class, show that a process can be
-    described as a process or object.
+1. How a process is given permission to use an objects resource.
+2. By using the *process* object class, show that a process can be
+   described as a process or object.
 
 An SELinux policy contains many rules and statements, the majority of
 which are *allow* rules that (simply) allows processes to be given
@@ -66,36 +74,35 @@ allow        unconfined_t    ext_gateway_t :  process  transition;
 
 Where:
 
-<table>
-<tbody>
-<tr>
-<td>allow</td>
-<td>The SELinux language allow rule.</td>
-</tr>
-<tr>
-<td>unconfined_t</td>
-<td>The source domain (or subject) identifier - in this case the shell that wants to exec the gateway application.</td>
-</tr>
-<tr>
-<td>ext_gateway_t</td>
-<td>The target object identifier - the object instance of the gateway application process. </td>
-</tr>
-<tr>
-<td>process</td>
-<td>The target object class - the *process* object class.</td>
-</tr>
-<tr>
-<td>transition</td>
-<td>The permission granted to the source domain on the targets object - in this case the *unconfined_t* domain has transition permission on the *ext_gateway_t* *process* object.</td>
-</tr>
-</tbody>
-</table>
+*allow*
+
+- The SELinux language *allow* rule.
+
+*unconfined_t*
+
+- The source domain (or subject) identifier - in this case the shell that
+  wants to *exec* the gateway application.
+
+*ext_gateway_t*
+
+- The target object identifier - the object instance of the gateway
+  application process.
+
+*process*
+
+- The target object class - the *process* object class.
+
+*transition*
+
+- The permission granted to the source domain on the targets object - in this
+  case the *unconfined_t* domain has transition permission on the
+  *ext_gateway_t process* object.
 
 ![](./images/6-allow-rule.png)
 
 **Figure 6: The *allow* rule** - *Showing that the subject (the processes
-running in the *unconfined_t* domain) has been given the transition
-permission on the *ext_gateway_t* *process* object.*
+running in the unconfined_t domain) has been given the transition
+permission on the ext_gateway_t process object.*
 
 It should be noted that there is more to a domain transition than
 described above, for a more detailed explanation, see the
@@ -108,28 +115,28 @@ objects is managed by the system and generally unseen by the users
 (until labeling goes wrong !!). As processes and objects are created and
 destroyed, they either:
 
-1.  Inherit their labels from the parent process or object. The policy
-    default user, type, role and range statements can be used to
-	change the behavior as discussed in the [**Default Rules**](default_rules.md#default-object-rules)
-    section.
-2.  The policy type, role and range transition statements allow a
-    different label to be assigned as discussed in the
-    [**Domain and Object Transitions**](domain_object_transitions.md#domain-and-object-transitions)
-    section.
-3.  SELinux-aware applications can assign a new label (with the
-    policy's approval of course) using the **libselinux** API
-    functions. The `process setfscreate` permission can be used to
-    allow subjects to create files with a new label programmatically
-    using the ***setfscreatecon**(3)* function, overriding default
-    rules and transition statements.
-4.  An object manager (OM) can enforce a default label that can either
-    be built into the OM or obtained via a configuration file (such as
-    those used by
-    [**SELinux X-Windows Support**](x_windows.md#x-windows-selinux-support).
-5.  Use an '[**initial security identifier**](sid_statement.md#security-id-sid-statement)'
-    (or initial SID). These are defined in all policies and are used to either
-    set an initial context during the boot process, or if an object requires
-    a default (i.e. the object does not already have a valid context).
+1. Inherit their labels from the parent process or object. The policy
+   default user, type, role and range statements can be used to
+   change the behavior as discussed in the [**Default Rules**](default_rules.md#default-object-rules)
+   section.
+2. The policy type, role and range transition statements allow a
+   different label to be assigned as discussed in the
+   [**Domain and Object Transitions**](domain_object_transitions.md#domain-and-object-transitions)
+   section.
+3. SELinux-aware applications can assign a new label (with the
+   policy's approval of course) using the **libselinux** API
+   functions. The *process { setfscreate }* permission can be used to
+   allow subjects to create files with a new label programmatically
+   using the ***setfscreatecon**(3)* function, overriding default
+   rules and transition statements.
+4. An object manager (OM) can enforce a default label that can either
+   be built into the OM or obtained via a configuration file (such as
+   those used by
+   [**SELinux X-Windows Support**](x_windows.md#x-windows-selinux-support).
+5. Use an '[**initial security identifier**](sid_statement.md#security-id-sid-statement)'
+   (or initial SID). These are defined in all policies and are used to either
+   set an initial context during the boot process, or if an object requires
+   a default (i.e. the object does not already have a valid context).
 
 The [**Computing Security Contexts**](computing_security_contexts.md#computing-security-contexts)
 section gives detail on how some of the kernel based objects are computed.
@@ -149,26 +156,24 @@ section.
 ### Labeling Extended Attribute Filesystems
 
 The labeling of file systems that implement extended
-attributes<a href="#fno1" class="footnote-ref" id="fnobj1"><strong><sup>1</sup></strong></a>
-is supported by SELinux using:
-
-1.  The *fs_use_xattr* statement within the policy to identify what
-    filesystems use extended attributes. This statement is used to
-    inform the security server how to label the filesystem.
-2.  A 'file contexts' file that defines what the initial contexts should
-    be for each file and directory within the filesystem. The format of
-    this file and how it is built from source policy is described in the
-    [**Policy Store Configuration Files - Building the File Labeling Support Files**](policy_store_config_files.md#building-the-file-labeling-support-files)<a href="#fno2" class="footnote-ref" id="fnobj2"><strong><sup>2</sup></strong></a>
-    section.
-
-3.  A method to initialise the filesystem with these extended
-    attributes. This is achieved by SELinux utilities such as
-    ***fixfiles**(8)* and ***setfiles**(8)*. There are also commands such as
-    ***chcon**(1)*, ***restorecon**(8)* and ***restorecond**(8)* that can be
-    used to relabel files.
+attributes[^fn_objs_1] is supported by SELinux using:
+
+1. The *fs_use_xattr* statement within the policy to identify what
+   filesystems use extended attributes. This statement is used to
+   inform the security server how to label the filesystem.
+2. A 'file contexts' file that defines what the initial contexts should
+   be for each file and directory within the filesystem. The format of
+   this file and how it is built from source policy is described in the
+   [**Policy Store Configuration Files - Building the File Labeling Support Files**](policy_store_config_files.md#building-the-file-labeling-support-files)[^fn_objs_2]
+   section.
+3. A method to initialise the filesystem with these extended
+   attributes. This is achieved by SELinux utilities such as
+   ***fixfiles**(8)* and ***setfiles**(8)*. There are also commands such as
+   ***chcon**(1)*, ***restorecon**(8)* and ***restorecond**(8)* that can be
+   used to relabel files.
 
 Extended attributes containing the SELinux context of a file can be
-viewed by the ls -Z or ***getfattr**(1)* commands as follows:
+viewed by the *ls -Z* or ***getfattr**(1)* commands as follows:
 
 ```
 ls -Z myfile
@@ -191,8 +196,8 @@ Assuming that the correct permissions have been granted by the policy,
 the effects on the security context of a file when copied or moved
 differ as follows:
 
--   copy a file - takes on label of new directory.
--   move a file - retains the label of the file.
+- copy a file - takes on label of new directory.
+- move a file - retains the label of the file.
 
 However, if the ***restorecond**(8)* daemon is running and the
 [**restorecond.conf**](global_config_files.md#etcselinuxrestorecond.conf)
@@ -262,26 +267,26 @@ discussed in the
 The policy language supports a number of statements to assign components
 to security contexts such as:
 
-*user*, *role* and *type* statements.
+- *user*, *role* and *type* statements.
 
-and manage their scope:
+and to manage their scope:
 
-*role_allow* and *constrain*
+- *role_allow* and *constrain*
 
-and manage their transition:
+and to manage their transition:
 
-*type_transition*, *role_transition* and *range_transition*
+- *type_transition*, *role_transition* and *range_transition*
 
 SELinux-aware applications can assign a new label (with the policy's
 approval of course) using the **libselinux** API functions. The
-`process setexec`, `process setkeycreate` and `process setsockcreate`
+*process { setexec setkeycreate setsockcreate }*
 permissions can be used to allow subjects to label processes,
 kernel keyrings, and sockets programmatically using the
 ***setexec**(3)*, ***setkeycreatecon**(3)* and
 ***setsockcreatecon**(3)* functions respectively, overriding
 transition statements.
 
-The `kernel` **initial security identifier** is used to associate
+The *kernel* **initial security identifier** is used to associate
 a specified label with kernel objects, including kernel threads
 (both those that are created during initialization but also kernel
 threads created later), kernel-private sockets and synthetic objects
@@ -293,7 +298,7 @@ either a policy-defined transition or an explicit setcon or
 setexeccon+execve, but that's just the typical default inheritance
 from creating task behavior for processes.
 
-The context associated with the `unlabeled`
+The context associated with the *unlabeled*
 **initial security identifier** is used as the fallback context for
 both subjects and objects when their label is invalidated by a policy
 reload (their SID is unchanged but the SID is transparently remapped
@@ -302,7 +307,7 @@ for various objects e.g. inodes, superblocks, etc until they reach a
 point where a more specific label can be determined e.g. from an
 xattr or from policy.
 
-### Object Reuse
+## Object Reuse
 
 As GNU / Linux runs it creates instances of objects and manages the
 information they contain (read, write, modify etc.) under the control of
@@ -319,13 +324,13 @@ process itself should clear or shred the information before releasing
 the object (which can be difficult in some cases unless the source code
 is available).
 
-<section class="footnotes">
-<ol>
-<li id="fno1"><p>These file systems store the security context in an attribute
-associated with the file.<a href="#fnobj1" class="footnote-back">↩</a></p></li>
-<li id="fno2"><p>Note that this file contains the contexts of all files in all extended attribute filesystems for the policy. However within a modular policy (and/or CIL modules) each module describes its own file context information, that is then used to build this file.<a href="#fnobj2" class="footnote-back">↩</a></p></li>
-</ol>
-</section>
+[^fn_objs_1]: These file systems store the security context in an attribute
+associated with the file.
+
+[^fn_objs_2]: Note that this file contains the contexts of all files in all
+extended attribute filesystems for the policy. However within a modular policy
+(and/or CIL modules) each module describes its own file context information,
+that is then used to build this file.
 
 <!-- %CUTHERE% -->
 
-- 
2.26.2