[PATCH Notebook] policy_config_statements.md: How to add a new capability

[PATCH Notebook] policy_config_statements.md: How to add a new capability

[Richard Haines]

Describes the steps required to add a new policy capability to the:
kernel, libsepol, and policy.

Signed-off-by: Richard Haines <richard_c_haines@btinternet.com>
---
Paul: Please note the use of the 'Oxford comma' above. Did you know there
is the "Oxford Comma" song by Vampire Weekend (if you are of a sensitive
disposition, don't listen).

 src/policy_config_statements.md | 125 ++++++++++++++++++++++++++++++++
 1 file changed, 125 insertions(+)

diff --git a/src/policy_config_statements.md b/src/policy_config_statements.md
index d4eee48..1ae7f64 100644
--- a/src/policy_config_statements.md
+++ b/src/policy_config_statements.md
@@ -1,5 +1,12 @@
 # Policy Configuration Statements
 
+- [*policycap*](#policycap)
+  - [Adding A New Policy Capability](#adding-a-new-policy-capability)
+    - [Kernel Updates](#kernel-updates)
+    - [*libsepol* Library Updates](#libsepol-library-updates)
+    - [Reference Policy Updates](#reference-policy-updates)
+    - [CIL Policy Updates](#cil-policy-updates)
+
 ## *policycap*
 
 Policy version 22 introduced the *policycap* statement to allow new
@@ -47,6 +54,124 @@ Conditional Policy Statements
 policycap network_peer_controls;
 ```
 
+## Adding A New Policy Capability
+
+### Kernel Updates
+
+In kernel source update the following three files with the new capability:
+
+***security/selinux/include/policycap_names.h***
+
+Add new entry at end of this list:
+
+```
+/* Policy capability names */
+const char *selinux_policycap_names[__POLICYDB_CAPABILITY_MAX] = {
+	...
+	"genfs_seclabel_symlinks",
+	"new_polcap_name"
+};
+```
+
+***security/selinux/include/policycap.h***
+
+Add new entry at end of this list:
+
+```
+/* Policy capabilities */
+enum {
+	...
+	POLICYDB_CAPABILITY_GENFS_SECLABEL_SYMLINKS,
+	POLICYDB_CAPABILITY_NEW_POLCAP_NAME,
+	__POLICYDB_CAPABILITY_MAX
+};
+```
+
+***security/selinux/include/security.h***
+
+Add a new call to retrieve the loaded policy capability state:
+
+```
+static inline bool selinux_policycap_new_name(void)
+{
+	struct selinux_state *state = &selinux_state;
+
+	return READ_ONCE(state->policycap[POLICYDB_CAPABILITY_NEW_POLCAP_NAME]);
+}
+```
+
+Finally in the updated code that utilises the new policy capability do
+something like this:
+
+```
+if (selinux_policycap_new_name())
+	do this;
+else
+	do that;
+```
+
+### *libsepol* Library Updates
+
+In selinux userspace source update the following two files with the new
+capability:
+
+***selinux/libsepol/src/polcaps.c***
+
+Add new entry at end of this list:
+
+```
+static const char * const polcap_names[] = {
+	...
+	"genfs_seclabel_symlinks",	/* POLICYDB_CAPABILITY_GENFS_SECLABEL_SYMLINKS */
+	"new_polcap_name",		/* POLICYDB_CAPABILITY_NEW_POLCAP_NAME */
+	NULL
+};
+```
+
+***selinux/libsepol/include/sepol/policydb/polcaps.h***
+
+Add new entry at end of this list:
+
+```
+/* Policy capabilities */
+enum {
+	...
+	POLICYDB_CAPABILITY_GENFS_SECLABEL_SYMLINKS,
+	POLICYDB_CAPABILITY_NEW_POLCAP_NAME,
+	__POLICYDB_CAPABILITY_MAX
+};
+```
+
+### Reference Policy Updates
+
+The new policy capability is then added to the Reference Policy file:
+
+***policy/policy_capabilities***
+
+To enable the capability in policy:
+
+```
+# A description of the capability
+policycap new_polcap_name;
+```
+
+To disable the capability comment out the entry:
+
+```
+# A description of the capability
+#policycap new_polcap_name;
+```
+
+### CIL Policy Updates
+
+To enable the capability in policy, add the following entry to a CIL
+source file:
+
+```
+; A description of the capability
+(policycap new_polcap_name)
+```
+
 <!-- %CUTHERE% -->
 
 ---
-- 
2.35.1

Re: [PATCH Notebook] policy_config_statements.md: How to add a new capability

[Paul Moore]

On Thu, Feb 24, 2022 at 8:07 AM Richard Haines
<richard_c_haines@btinternet.com> wrote:
>
> Describes the steps required to add a new policy capability to the:
> kernel, libsepol, and policy.
>
> Signed-off-by: Richard Haines <richard_c_haines@btinternet.com>

Thanks Richard.  I saw the Markdown in your reply to Demi and was
going to ask you about adding it to The Notebook; happily you beat me
to it.

> Paul: Please note the use of the 'Oxford comma' above.

Appreciated, thank you :)

> ... Did you know there
> is the "Oxford Comma" song by Vampire Weekend (if you are of a sensitive
> disposition, don't listen).

Oh, no, I did not know that!  I'm currently "in a meeting" so I can't
listen to it, but I've got the song/video queued up for later :)

> diff --git a/src/policy_config_statements.md b/src/policy_config_statements.md
> index d4eee48..1ae7f64 100644
> --- a/src/policy_config_statements.md
> +++ b/src/policy_config_statements.md
> @@ -1,5 +1,12 @@
>  # Policy Configuration Statements
>
> +- [*policycap*](#policycap)
> +  - [Adding A New Policy Capability](#adding-a-new-policy-capability)
> +    - [Kernel Updates](#kernel-updates)
> +    - [*libsepol* Library Updates](#libsepol-library-updates)
> +    - [Reference Policy Updates](#reference-policy-updates)
> +    - [CIL Policy Updates](#cil-policy-updates)
> +
>  ## *policycap*
>
>  Policy version 22 introduced the *policycap* statement to allow new
> @@ -47,6 +54,124 @@ Conditional Policy Statements
>  policycap network_peer_controls;
>  ```
>
> +## Adding A New Policy Capability
> +
> +### Kernel Updates
> +
> +In kernel source update the following three files with the new capability:
> +
> +***security/selinux/include/policycap_names.h***
> +
> +Add new entry at end of this list:
> +
> +```
> +/* Policy capability names */
> +const char *selinux_policycap_names[__POLICYDB_CAPABILITY_MAX] = {
> +       ...
> +       "genfs_seclabel_symlinks",
> +       "new_polcap_name"
> +};
> +```
> +
> +***security/selinux/include/policycap.h***
> +
> +Add new entry at end of this list:
> +
> +```
> +/* Policy capabilities */
> +enum {
> +       ...
> +       POLICYDB_CAPABILITY_GENFS_SECLABEL_SYMLINKS,
> +       POLICYDB_CAPABILITY_NEW_POLCAP_NAME,
> +       __POLICYDB_CAPABILITY_MAX
> +};
> +```

I worry that "adding a new entry to the end of the list" could be
interpreted as this:

 enum {
   ...
   __POLICYDB_CAPABILITY_MAX,
   POLICYDB_CAPABILITY_MY_NEW_POLCAP
 };

It might be good to specify that new entries should be added
immediately before the CAPABILITY_MAX sentinel.

> +***security/selinux/include/security.h***
> +
> +Add a new call to retrieve the loaded policy capability state:
> +
> +```
> +static inline bool selinux_policycap_new_name(void)
> +{
> +       struct selinux_state *state = &selinux_state;
> +
> +       return READ_ONCE(state->policycap[POLICYDB_CAPABILITY_NEW_POLCAP_NAME]);
> +}
> +```

Instead of providing a code snippet, which will surely become outdated
at some point, perhaps it would be better to simply reference the
existing getter functions in the header file as a copy-n-paste target?

> +Finally in the updated code that utilises the new policy capability do
> +something like this:
> +
> +```
> +if (selinux_policycap_new_name())
> +       do this;
> +else
> +       do that;
> +```
> +
> +### *libsepol* Library Updates
> +
> +In selinux userspace source update the following two files with the new
> +capability:
> +
> +***selinux/libsepol/src/polcaps.c***
> +
> +Add new entry at end of this list:
> +
> +```
> +static const char * const polcap_names[] = {
> +       ...
> +       "genfs_seclabel_symlinks",      /* POLICYDB_CAPABILITY_GENFS_SECLABEL_SYMLINKS */
> +       "new_polcap_name",              /* POLICYDB_CAPABILITY_NEW_POLCAP_NAME */
> +       NULL
> +};
> +```

See above worry, but substitute the NULL sentinel value.

> +***selinux/libsepol/include/sepol/policydb/polcaps.h***
> +
> +Add new entry at end of this list:
> +
> +```
> +/* Policy capabilities */
> +enum {
> +       ...
> +       POLICYDB_CAPABILITY_GENFS_SECLABEL_SYMLINKS,
> +       POLICYDB_CAPABILITY_NEW_POLCAP_NAME,
> +       __POLICYDB_CAPABILITY_MAX
> +};
> +```

Same.

-- 
paul-moore.com

Re: [PATCH Notebook] policy_config_statements.md: How to add a new capability

[Paul Moore]

On Thu, Feb 24, 2022 at 6:33 PM Paul Moore <paul@paul-moore.com> wrote:
> On Thu, Feb 24, 2022 at 8:07 AM Richard Haines
> <richard_c_haines@btinternet.com> wrote:
>
> > ... Did you know there
> > is the "Oxford Comma" song by Vampire Weekend (if you are of a sensitive
> > disposition, don't listen).
>
> Oh, no, I did not know that!  I'm currently "in a meeting" so I can't
> listen to it, but I've got the song/video queued up for later :)

That was worth the listen ... although I still remain convinced that
Oxford commas have value ;)

-- 
paul-moore.com