[RFC,selinux-notebook,05/18] xperm_rules: fully convert to markdown
diff mbox series

Message ID 159650482872.8961.7516871249534865160.stgit@sifl
State Accepted
Headers show
Series
  • markdown conversions and cleanups
Related show

Commit Message

Paul Moore Aug. 4, 2020, 1:33 a.m. UTC
Signed-off-by: Paul Moore <paul@paul-moore.com>
---
 src/xperm_rules.md |  138 ++++++++++++++++++++++++----------------------------
 1 file changed, 64 insertions(+), 74 deletions(-)

Comments

Richard Haines Aug. 4, 2020, 4:14 p.m. UTC | #1
On Mon, 2020-08-03 at 21:33 -0400, Paul Moore wrote:
> Signed-off-by: Paul Moore <paul@paul-moore.com>
> ---
>  src/xperm_rules.md |  138 ++++++++++++++++++++++++----------------
> ------------
>  1 file changed, 64 insertions(+), 74 deletions(-)
> 
> diff --git a/src/xperm_rules.md b/src/xperm_rules.md
> index 48beb41..21878ea 100644
> --- a/src/xperm_rules.md
> +++ b/src/xperm_rules.md
> @@ -2,8 +2,8 @@
>  
>  There are three extended AV rules implemented from Policy version 30
>  with the target platform 'selinux' that expand the permission sets
> from
> -a fixed 32 bits to permission sets in 256 bit increments:
> `allowxperm`,
> -`dontauditxperm`, `auditallowxperm` and `neverallowxperm`.
> +a fixed 32 bits to permission sets in 256 bit increments:
> *allowxperm*,
> +*dontauditxperm*, *auditallowxperm* and *neverallowxperm*.
>  
>  The rules for extended permissions are subject to the 'operation'
> they
>  perform with Policy version 30 and kernels from 4.3 supporting ioctl
> @@ -16,66 +16,59 @@ libsepol 2.7 minimum is required).
>  
>  **Where:**
>  
> -<table>
> -<tbody>
> -<tr>
> -<td><code>rule_name</code></td>
> -<td>The applicable <code>allowxperm</code>,
> <code>dontauditxperm</code>, <code>auditallowxperm</code> or
> <code>neverallowxperm</code> rule keyword.</td>
> -</tr>
> -<tr>
> -<td><p><code>source_type</code></p>
> -<p><code>target_type</code></p></td>
> -<td><p>One or more source / target <code>type</code>,
> <code>typealias</code> or <code>attribute</code> identifiers.
> Multiple entries consist of a space separated list enclosed in braces
> '{}'. Entries can be excluded from the list by using the negative
> operator '-'.</p>
> -<p>The target_type can have the <code>self</code> keyword instead of
> <code>type</code>, <code>typealias</code> or <code>attribute</code>
> identifiers. This means that the <code>target_type</code> is the same
> as the <code>source_type</code>.</p></td>
> -</tr>
> -<tr>
> -<td><code>class</code></td>
> -<td>One or more object classes. Multiple entries consist of a space
> separated list enclosed in braces '{}'.</td>
> -</tr>
> -<tr>
> -<td><code>operation<code></td>
> -<td>A key word defining the operation to be implemented by the rule.
> Currently only the <code>ioctl</code> operation is supported by the
> kernel policy language and kernel as described in the  <a
> href="#ioctl-operation-rules"><code>ioctl</code> Operation Rules</a>
> section.</td>
> -</tr>
> -<tr>
> -<td><code>xperm_set</code></td>
> -<td><p>One or more extended permissions represented by numeric
> values (i.e. <code>0x8900</code> or <code>35072</code>). The usage is
> dependent on the specified <em>operation</em>.</p>
> -<p>Multiple entries consist of a space separated list enclosed in
> braces '{}'.</p>
> -<p>The complement operator '~' is used to specify all permissions
> except those explicitly listed.</p>
> -<p>The range operator '-' is used to specify all permissions within
> the <code>low – high</code> range.</p>
> -<p>An example is shown in the <a href="#ioctl-operation-
> rules"><code>ioctl</code> Operation Rules</a> section.</p></td>
> -</tr>
> -</tbody>
> -</table>
> +*rule_name*
> +
> +The applicable *allowxperm*, *dontauditxperm*, *auditallowxperm*
> +or *neverallowxperm* rule keyword.
> +
> +*source_type*
> +
> +One or more source / target *type*, *typealias* or *attribute*
> identifiers.
> +Multiple entries consist of a space separated list enclosed in
> braces \'{}\'.
> +Entries can be excluded from the list by using the negative operator
> \'-\'.
> +
> +*target_type*
> +
> +The target_type can have the *self* keyword instead of *type*,
> *typealias* or
> +*attribute* identifiers. This means that the *target_type* is the
> same as the
> +*source_type*.
> +
> +*class*
> +
> +One or more object classes. Multiple entries consist of a space
> separated list
> +enclosed in braces \'{}\'.

I've had a rethink on this and wonder if it would be clearer if the
descriptions were a bullet list:

*class*

- One or more object classes. Multiple ...


> +
> +*operation*
> +
> +A key word defining the operation to be implemented by the rule.
> Currently only
> +the *ioctl* operation is supported by the kernel policy language and
> kernel as
> +described in the [*ioctl* Operation Rules](#ioctl-operation-rules)
> section.
> +
> +*xperm_set*
> +
> +One or more extended permissions represented by numeric values (i.e.
> *0x8900*
> +or *35072*). The usage is dependent on the specified *operation*.
> Multiple
> +entries consist of a space separated list enclosed in braces \'{}\'.
> The
> +complement operator \'\~\' is used to specify all permissions except
> those
> +explicitly listed. The range operator \'-\' is used to specify all
> permissions
> +within the *low – high* range. An example is shown in the
> +[*ioctl* Operation Rules](#ioctl-operation-rules) section.
>  
>  **The statement is valid in:**
>  
> -<table style="text-align:center">
> -<tbody>
> -<tr style="background-color:#D3D3D3;">
> -<td><strong>Monolithic Policy</strong></td>
> -<td><strong>Base Policy</strong></td>
> -<td><strong>Module Policy</strong></td>
> -</tr>
> -<tr>
> -<td>Yes</td>
> -<td>Yes</td>
> -<td>Yes</td>
> -</tr>
> -<tr style="background-color:#D3D3D3;">
> -<td><strong>Conditional Policy <code>if</code>
> Statement</strong></td>
> -<td><strong><code>optional</code> Statement</strong></td>
> -<td><strong><code>require</code> Statement</strong></td>
> -</tr>
> -<tr>
> -<td>No</td>
> -<td>No</td>
> -<td>No</td>
> -</tr>
> -</tbody>
> -</table>
> -<br>
> -
> -### `ioctl` Operation Rules
> +Policy Type
> +
> +| Monolithic Policy       | Base Policy             | Module
> Policy           |
> +| ----------------------- | ----------------------- | --------------
> --------- |
> +| Yes                     | Yes                     |
> Yes                     |
> +
> +Conditional Policy Statements
> +
> +| *if* statement          | *optional* Statement    | *require*
> Statement     |
> +| ----------------------- | ----------------------- | --------------
> --------- |
> +| No                      | No                      |
> No                      |
> +
> +### *ioctl* Operation Rules
>  
>  Use cases and implementation details for ioctl command whitelisting
> are
>  described in detail at
> @@ -85,14 +78,14 @@ policy format changes shown in the example below
> with a brief overview
>  the final upstream kernel patch).
>  
>  Ioctl calls are generally used to get or set device options. Policy
> -versions &lt; 30 only controls whether an `ioctl` permission is
> allowed
> -or not, for example this rule allows the object class `tcp_socket`
> the
> -`ioctl` permission:
> +versions &lt; 30 only controls whether an *ioctl* permission is
> allowed
> +or not, for example this rule allows the object class *tcp_socket*
> the
> +*ioctl* permission:
>  
>  `allow src_t tgt_t : tcp_socket ioctl;`
>  
>  From Policy version 30 it is possible to control ***ioctl**(2)*
> -'*request*' parameters provided the `ioctl` permission is also
> allowed,
> +'*request*' parameters provided the *ioctl* permission is also
> allowed,
>  for example:
>  
>  ```
> @@ -101,14 +94,14 @@ allow src_t tgt_t : tcp_socket ioctl;
>  allowxperm src_t tgt_t : tcp_socket ioctl ~0x8927;
>  ```
>  
> -The `allowxperm` rule states that all ioctl request parameters are
> +The *allowxperm* rule states that all ioctl request parameters are
>  allowed for the source/target/class with the exception of the value
> -`0x8927` that (using *include/linux/sockios.h*) is
> **SIOCGIFHWADDR**, or
> +*0x8927* that (using *include/linux/sockios.h*) is
> **SIOCGIFHWADDR**, or
>  'get hardware address'.
>  
>  An example audit log entry denying an ioctl request to add a routing
> -table entry (**SIOCADDRT** - `ioctlcmd=890b`) for *goldfish_setup*
> on a
> -`udp_socket` is:
> +table entry (**SIOCADDRT** - *ioctlcmd=890b*) for *goldfish_setup*
> on a
> +*udp_socket* is:
>  
>  ```
>  type=1400 audit(1437408413.860:6): avc: denied { ioctl } for pid=81
> @@ -121,18 +114,15 @@ Notes:
>  
>  1.  Important: The ioctl operation is not 'deny all' ioctl requests
>      (hence whitelisting). It is targeted at the specific
> -    source/target/class set of ioctl commands. As no other
> `allowxperm`
> +    source/target/class set of ioctl commands. As no other
> *allowxperm*
>      rules have been defined in the example, all other ioctl calls
> may
>      continue to use any valid request parameters (provided there are
> -    `allow` rules for the `ioctl` permission).
> +    *allow* rules for the *ioctl* permission).
>  2.  As the ***ioctl**(2)* function requires a file descriptor, its
> -    context must match the process context otherwise the `fd { use
> }`
> +    context must match the process context otherwise the *fd { use
> }*
>      class/permission is required.
>  3.  To deny all ioctl requests for a specific source/target/class
> the
> -    `xperm_set` should be set to `0` or `0x0`.
> -
> -
> -<br>
> +    *xperm_set* should be set to *0* or *0x0*.
>  
>  <!-- %CUTHERE% -->
>  
>
Paul Moore Aug. 6, 2020, 2:34 a.m. UTC | #2
On Tue, Aug 4, 2020 at 12:14 PM Richard Haines
<richard_c_haines@btinternet.com> wrote:
> On Mon, 2020-08-03 at 21:33 -0400, Paul Moore wrote:

...

> > +*rule_name*
> > +
> > +The applicable *allowxperm*, *dontauditxperm*, *auditallowxperm*
> > +or *neverallowxperm* rule keyword.
> > +
> > +*source_type*
> > +
> > +One or more source / target *type*, *typealias* or *attribute*
> > identifiers.
> > +Multiple entries consist of a space separated list enclosed in
> > braces \'{}\'.
> > +Entries can be excluded from the list by using the negative operator
> > \'-\'.
> > +
> > +*target_type*
> > +
> > +The target_type can have the *self* keyword instead of *type*,
> > *typealias* or
> > +*attribute* identifiers. This means that the *target_type* is the
> > same as the
> > +*source_type*.
> > +
> > +*class*
> > +
> > +One or more object classes. Multiple entries consist of a space
> > separated list
> > +enclosed in braces \'{}\'.
>
> I've had a rethink on this and wonder if it would be clearer if the
> descriptions were a bullet list:
>
> *class*
>
> - One or more object classes. Multiple ...

Ooops.  I forgot about this comment in my inbox when I merged the
patchset; although I guess even if we go with the bulleted list having
the table in markdown first should make this easier.

I guess we could give it a try and see how it looks?  My only concern
is that sometimes a list with only one item can look a bit "off".  Or
an I misunderstanding what you are proposing?
Richard Haines Aug. 6, 2020, 10:07 a.m. UTC | #3
On Wed, 2020-08-05 at 22:34 -0400, Paul Moore wrote:
> On Tue, Aug 4, 2020 at 12:14 PM Richard Haines
> <richard_c_haines@btinternet.com> wrote:
> > On Mon, 2020-08-03 at 21:33 -0400, Paul Moore wrote:
> 
> ...
> 
> > > +*rule_name*
> > > +
> > > +The applicable *allowxperm*, *dontauditxperm*, *auditallowxperm*
> > > +or *neverallowxperm* rule keyword.
> > > +
> > > +*source_type*
> > > +
> > > +One or more source / target *type*, *typealias* or *attribute*
> > > identifiers.
> > > +Multiple entries consist of a space separated list enclosed in
> > > braces \'{}\'.
> > > +Entries can be excluded from the list by using the negative
> > > operator
> > > \'-\'.
> > > +
> > > +*target_type*
> > > +
> > > +The target_type can have the *self* keyword instead of *type*,
> > > *typealias* or
> > > +*attribute* identifiers. This means that the *target_type* is
> > > the
> > > same as the
> > > +*source_type*.
> > > +
> > > +*class*
> > > +
> > > +One or more object classes. Multiple entries consist of a space
> > > separated list
> > > +enclosed in braces \'{}\'.
> > 
> > I've had a rethink on this and wonder if it would be clearer if the
> > descriptions were a bullet list:
> > 
> > *class*
> > 
> > - One or more object classes. Multiple ...
> 
> Ooops.  I forgot about this comment in my inbox when I merged the
> patchset; although I guess even if we go with the bulleted list
> having
> the table in markdown first should make this easier.
> 
> I guess we could give it a try and see how it looks?  My only concern
> is that sometimes a list with only one item can look a bit "off".  Or
> an I misunderstanding what you are proposing?

I've posted the SE Android section as an RFC patch that converts HTML
tables to lists. See what you think.

I sent the Reference Policy updates yesterday but it never made it to
the list as I didn't realise it was over 100K, still I guess you had
your copy.

>
Paul Moore Aug. 6, 2020, 9:49 p.m. UTC | #4
On Thu, Aug 6, 2020 at 6:07 AM Richard Haines
<richard_c_haines@btinternet.com> wrote:
> On Wed, 2020-08-05 at 22:34 -0400, Paul Moore wrote:
> > On Tue, Aug 4, 2020 at 12:14 PM Richard Haines
> > <richard_c_haines@btinternet.com> wrote:
> > > On Mon, 2020-08-03 at 21:33 -0400, Paul Moore wrote:
> >
> > ...
> >
> > > > +*rule_name*
> > > > +
> > > > +The applicable *allowxperm*, *dontauditxperm*, *auditallowxperm*
> > > > +or *neverallowxperm* rule keyword.
> > > > +
> > > > +*source_type*
> > > > +
> > > > +One or more source / target *type*, *typealias* or *attribute*
> > > > identifiers.
> > > > +Multiple entries consist of a space separated list enclosed in
> > > > braces \'{}\'.
> > > > +Entries can be excluded from the list by using the negative
> > > > operator
> > > > \'-\'.
> > > > +
> > > > +*target_type*
> > > > +
> > > > +The target_type can have the *self* keyword instead of *type*,
> > > > *typealias* or
> > > > +*attribute* identifiers. This means that the *target_type* is
> > > > the
> > > > same as the
> > > > +*source_type*.
> > > > +
> > > > +*class*
> > > > +
> > > > +One or more object classes. Multiple entries consist of a space
> > > > separated list
> > > > +enclosed in braces \'{}\'.
> > >
> > > I've had a rethink on this and wonder if it would be clearer if the
> > > descriptions were a bullet list:
> > >
> > > *class*
> > >
> > > - One or more object classes. Multiple ...
> >
> > Ooops.  I forgot about this comment in my inbox when I merged the
> > patchset; although I guess even if we go with the bulleted list
> > having
> > the table in markdown first should make this easier.
> >
> > I guess we could give it a try and see how it looks?  My only concern
> > is that sometimes a list with only one item can look a bit "off".  Or
> > an I misunderstanding what you are proposing?
>
> I've posted the SE Android section as an RFC patch that converts HTML
> tables to lists. See what you think.

Okay, I'll take a look.  I'm inclined to merge it regardless just
because it does the HTML->MD conversion.  Once we get it fully into
markdown, especially the tables, it should be easier to edit for
consistency, style, etc.

> I sent the Reference Policy updates yesterday but it never made it to
> the list as I didn't realise it was over 100K, still I guess you had
> your copy.

Yes, I just ran out of energy last night when I was working my way
through the other patches.  Hopefully I'll get through the rest
today/tomorrow.

Patch
diff mbox series

diff --git a/src/xperm_rules.md b/src/xperm_rules.md
index 48beb41..21878ea 100644
--- a/src/xperm_rules.md
+++ b/src/xperm_rules.md
@@ -2,8 +2,8 @@ 
 
 There are three extended AV rules implemented from Policy version 30
 with the target platform 'selinux' that expand the permission sets from
-a fixed 32 bits to permission sets in 256 bit increments: `allowxperm`,
-`dontauditxperm`, `auditallowxperm` and `neverallowxperm`.
+a fixed 32 bits to permission sets in 256 bit increments: *allowxperm*,
+*dontauditxperm*, *auditallowxperm* and *neverallowxperm*.
 
 The rules for extended permissions are subject to the 'operation' they
 perform with Policy version 30 and kernels from 4.3 supporting ioctl
@@ -16,66 +16,59 @@  libsepol 2.7 minimum is required).
 
 **Where:**
 
-<table>
-<tbody>
-<tr>
-<td><code>rule_name</code></td>
-<td>The applicable <code>allowxperm</code>, <code>dontauditxperm</code>, <code>auditallowxperm</code> or <code>neverallowxperm</code> rule keyword.</td>
-</tr>
-<tr>
-<td><p><code>source_type</code></p>
-<p><code>target_type</code></p></td>
-<td><p>One or more source / target <code>type</code>, <code>typealias</code> or <code>attribute</code> identifiers. Multiple entries consist of a space separated list enclosed in braces '{}'. Entries can be excluded from the list by using the negative operator '-'.</p>
-<p>The target_type can have the <code>self</code> keyword instead of <code>type</code>, <code>typealias</code> or <code>attribute</code> identifiers. This means that the <code>target_type</code> is the same as the <code>source_type</code>.</p></td>
-</tr>
-<tr>
-<td><code>class</code></td>
-<td>One or more object classes. Multiple entries consist of a space separated list enclosed in braces '{}'.</td>
-</tr>
-<tr>
-<td><code>operation<code></td>
-<td>A key word defining the operation to be implemented by the rule. Currently only the <code>ioctl</code> operation is supported by the kernel policy language and kernel as described in the  <a href="#ioctl-operation-rules"><code>ioctl</code> Operation Rules</a> section.</td>
-</tr>
-<tr>
-<td><code>xperm_set</code></td>
-<td><p>One or more extended permissions represented by numeric values (i.e. <code>0x8900</code> or <code>35072</code>). The usage is dependent on the specified <em>operation</em>.</p>
-<p>Multiple entries consist of a space separated list enclosed in braces '{}'.</p>
-<p>The complement operator '~' is used to specify all permissions except those explicitly listed.</p>
-<p>The range operator '-' is used to specify all permissions within the <code>low – high</code> range.</p>
-<p>An example is shown in the <a href="#ioctl-operation-rules"><code>ioctl</code> Operation Rules</a> section.</p></td>
-</tr>
-</tbody>
-</table>
+*rule_name*
+
+The applicable *allowxperm*, *dontauditxperm*, *auditallowxperm*
+or *neverallowxperm* rule keyword.
+
+*source_type*
+
+One or more source / target *type*, *typealias* or *attribute* identifiers.
+Multiple entries consist of a space separated list enclosed in braces \'{}\'.
+Entries can be excluded from the list by using the negative operator \'-\'.
+
+*target_type*
+
+The target_type can have the *self* keyword instead of *type*, *typealias* or
+*attribute* identifiers. This means that the *target_type* is the same as the
+*source_type*.
+
+*class*
+
+One or more object classes. Multiple entries consist of a space separated list
+enclosed in braces \'{}\'.
+
+*operation*
+
+A key word defining the operation to be implemented by the rule. Currently only
+the *ioctl* operation is supported by the kernel policy language and kernel as
+described in the [*ioctl* Operation Rules](#ioctl-operation-rules) section.
+
+*xperm_set*
+
+One or more extended permissions represented by numeric values (i.e. *0x8900*
+or *35072*). The usage is dependent on the specified *operation*. Multiple
+entries consist of a space separated list enclosed in braces \'{}\'. The
+complement operator \'\~\' is used to specify all permissions except those
+explicitly listed. The range operator \'-\' is used to specify all permissions
+within the *low – high* range. An example is shown in the
+[*ioctl* Operation Rules](#ioctl-operation-rules) section.
 
 **The statement is valid in:**
 
-<table style="text-align:center">
-<tbody>
-<tr style="background-color:#D3D3D3;">
-<td><strong>Monolithic Policy</strong></td>
-<td><strong>Base Policy</strong></td>
-<td><strong>Module Policy</strong></td>
-</tr>
-<tr>
-<td>Yes</td>
-<td>Yes</td>
-<td>Yes</td>
-</tr>
-<tr style="background-color:#D3D3D3;">
-<td><strong>Conditional Policy <code>if</code> Statement</strong></td>
-<td><strong><code>optional</code> Statement</strong></td>
-<td><strong><code>require</code> Statement</strong></td>
-</tr>
-<tr>
-<td>No</td>
-<td>No</td>
-<td>No</td>
-</tr>
-</tbody>
-</table>
-<br>
-
-### `ioctl` Operation Rules
+Policy Type
+
+| Monolithic Policy       | Base Policy             | Module Policy           |
+| ----------------------- | ----------------------- | ----------------------- |
+| Yes                     | Yes                     | Yes                     |
+
+Conditional Policy Statements
+
+| *if* statement          | *optional* Statement    | *require* Statement     |
+| ----------------------- | ----------------------- | ----------------------- |
+| No                      | No                      | No                      |
+
+### *ioctl* Operation Rules
 
 Use cases and implementation details for ioctl command whitelisting are
 described in detail at
@@ -85,14 +78,14 @@  policy format changes shown in the example below with a brief overview
 the final upstream kernel patch).
 
 Ioctl calls are generally used to get or set device options. Policy
-versions &lt; 30 only controls whether an `ioctl` permission is allowed
-or not, for example this rule allows the object class `tcp_socket` the
-`ioctl` permission:
+versions &lt; 30 only controls whether an *ioctl* permission is allowed
+or not, for example this rule allows the object class *tcp_socket* the
+*ioctl* permission:
 
 `allow src_t tgt_t : tcp_socket ioctl;`
 
 From Policy version 30 it is possible to control ***ioctl**(2)*
-'*request*' parameters provided the `ioctl` permission is also allowed,
+'*request*' parameters provided the *ioctl* permission is also allowed,
 for example:
 
 ```
@@ -101,14 +94,14 @@  allow src_t tgt_t : tcp_socket ioctl;
 allowxperm src_t tgt_t : tcp_socket ioctl ~0x8927;
 ```
 
-The `allowxperm` rule states that all ioctl request parameters are
+The *allowxperm* rule states that all ioctl request parameters are
 allowed for the source/target/class with the exception of the value
-`0x8927` that (using *include/linux/sockios.h*) is **SIOCGIFHWADDR**, or
+*0x8927* that (using *include/linux/sockios.h*) is **SIOCGIFHWADDR**, or
 'get hardware address'.
 
 An example audit log entry denying an ioctl request to add a routing
-table entry (**SIOCADDRT** - `ioctlcmd=890b`) for *goldfish_setup* on a
-`udp_socket` is:
+table entry (**SIOCADDRT** - *ioctlcmd=890b*) for *goldfish_setup* on a
+*udp_socket* is:
 
 ```
 type=1400 audit(1437408413.860:6): avc: denied { ioctl } for pid=81
@@ -121,18 +114,15 @@  Notes:
 
 1.  Important: The ioctl operation is not 'deny all' ioctl requests
     (hence whitelisting). It is targeted at the specific
-    source/target/class set of ioctl commands. As no other `allowxperm`
+    source/target/class set of ioctl commands. As no other *allowxperm*
     rules have been defined in the example, all other ioctl calls may
     continue to use any valid request parameters (provided there are
-    `allow` rules for the `ioctl` permission).
+    *allow* rules for the *ioctl* permission).
 2.  As the ***ioctl**(2)* function requires a file descriptor, its
-    context must match the process context otherwise the `fd { use }`
+    context must match the process context otherwise the *fd { use }*
     class/permission is required.
 3.  To deny all ioctl requests for a specific source/target/class the
-    `xperm_set` should be set to `0` or `0x0`.
-
-
-<br>
+    *xperm_set* should be set to *0* or *0x0*.
 
 <!-- %CUTHERE% -->