From 712b7ed63b51ad8befaa0ace2da6e240370837ba Mon Sep 17 00:00:00 2001 From: Vit Mojzis Date: Jul 26 2019 11:06:35 +0000 Subject: Update based on comments from the packaging committee - Reformat using semantic line breaks - Rephrase boolean description - Fix minor syntactic issues (please "fixup" this commit before accepting the pull request) --- diff --git a/guidelines/modules/ROOT/pages/SELinuxIndependentPolicy.adoc b/guidelines/modules/ROOT/pages/SELinuxIndependentPolicy.adoc index 719053f..f781928 100644 --- a/guidelines/modules/ROOT/pages/SELinuxIndependentPolicy.adoc +++ b/guidelines/modules/ROOT/pages/SELinuxIndependentPolicy.adoc @@ -1,33 +1,36 @@ -=SELinux Independent Policy Guidelines += SELinux Independent Policy Guidelines [#creating-own-product-policies] == Creating Own Product Policies -In Fedora, there is a lot of applications and daemons which require -customized SELinux security policy. The former approach with providing -all policies only as a part of the system has been enhanced by the -option to create own product policy. +In Fedora, there is a lot of applications and daemons +which require customized SELinux security policy. +The former approach with providing all policies only as a part of the system +has been enhanced by the option to create custom product policy. -With the possibility to create own product policy, required changes in a -policy can be implemented immediately, so the product package maintainer -does not need to wait for another SELinux policy package release. In -other words, a product SELinux policy is always synchronized with a -product. +With the possibility to create custom product policy, +required changes in a policy can be released immediately, +so the product package maintainer does not need to wait +for another SELinux policy package release. +In other words, +a product SELinux policy is always synchronized +with the corresponding product (package). -This chapter is dedicated to shipping an own SELinux security module as -a subpackage for a daemon or an application. +This chapter is dedicated to shipping custom SELinux security module +as a subpackage for a daemon or an application. [#independent-selinux-policy] == Independent SELinux Policy -While considering own product policy, a product maintainer has two -options: +While considering custom product policy, +a product maintainer has two options: -* Write own SELinux policy from scratch and ask SELinux team for policy -review. Note that a guide how to write an SELinux policy from the -scratch is not a part of this chapter (See `sepolicy generate` tool) . -* Extract an SELinux policy from a distribution policy package. The Git -repository with distribution policies is located on +* Write his own SELinux policy from scratch +and ask SELinux team for policy review. +Note that a guide how to write an SELinux policy from scratch +is not a part of this chapter (See `sepolicy generate` tool). +* Extract an SELinux policy from a distribution policy package. +The Git repository with distribution policies is located on https://github.com/fedora-selinux/selinux-policy[github.com/fedora-selinux/selinux-policy and https://github.com/fedora-selinux/selinux-policy-contrib. @@ -38,20 +41,19 @@ https://github.com/fedora-selinux/selinux-policy-contrib. [#agreement-workflow] === Agreement workflow -Before you start with shipping own product policies, let the SELinux -team know about your intentions. To do this, use Fedora mailing list or -contact SELinux policy maintainer: +Before you start with shipping custom product policies, +let the SELinux team know about your intentions. +To do this, use Fedora mailing list or contact SELinux policy maintainer: -* mailto:selinux-policy-owner@fedoraproject.org[SELinux Policy -maintainer] +* mailto:selinux-policy-owner@fedoraproject.org[SELinux Policy maintainer] * selinux@lists.fedoraproject.org [#git-repository-setup] === Git Repository setup -A product maintainer should prepare a Git repository for SELinux policy -sources (i.e. .\{te|fc|if} files). It's recommended, to set up separate -Git repository for the policy. +A product maintainer should prepare a Git repository for SELinux policy sources +(i.e. .\{te|fc|if} files). +It's recommended to set up separate Git repository for the policy. .... # Create directory to contain the project @@ -67,16 +69,20 @@ $ git push -u origin master Corresponding policy module can than be extracted from https://github.com/fedora-selinux/selinux-policy-contrib[selinux-policy-contrib repository]. -If there is no policy for the product, new policy should be created in -this step and added to the repository. +If there is no policy for the product, +new policy should be created in this step and added to the repository. -When the custom policy is ready, the product maintainer should create a -Makefile, attach a license file and make sure the policy compiles -properly. See <> +When the custom policy is ready, +the product maintainer should create a Makefile, +attach a license file and make sure the policy compiles properly. +See +<>. -The final step of the extraction process is removing the product policy -from the distribution Git repository. This should be done when the -independent SELinux subpackage for the product is ready. See +The final step of the extraction process +is removing the product policy from the distribution Git repository. +This should be done +when the independent SELinux subpackage for the product is ready. +See <>. [#preparing-sources-for-the-policy-git-repository] @@ -86,12 +92,14 @@ independent SELinux subpackage for the product is ready. See === License A Git repository should not contain only SELinux policy source files, -but also a `license`. For more information how to add an open source -license in your repository, see the -https://help.github.com/articles/adding-a-license-to-a-repository/[Adding -a license to a repository] article on the GitHub Help. Distribution -policies have GPL license, so any policy extracted from Distribution -policy must have GPL compatible license. +but also a `license`. +For more information how to add an open source license in your repository, +see the +https://help.github.com/articles/adding-a-license-to-a-repository/[Adding a license to a repository] +article on the GitHub Help. +Distribution policies have GPL license, +so any policy extracted from Distribution policy +must have a GPL compatible license. [#makefile] === Makefile @@ -162,7 +170,7 @@ Makefile myapp.fc myapp.if myapp.te COPYING [#compiling-custom-policy] === Compiling custom policy -To compile an own and already-prepared policy, use the `make` command: +To compile finished policy, use the `make` command: .... $ make @@ -189,12 +197,13 @@ $ tar -czf myapp-selinux.tar.gz myapp-selinux/ [#using-custom-interfaces] === Using custom interfaces -The interface file of the custom policy module is *not* installed in the -system because it would conflict with the interface file of the -distribution module. Therefore any changes to it will not have effect on -other policy modules. In order to use custom interfaces it is necessary -to create new interface file with unique name (ipp-.if) and include it -in the new package as follows: +The interface file of the custom policy module +is *not* installed in the system +because it would conflict with the interface file of the distribution module. +Therefore any changes to it will not have effect on other policy modules. +In order to use custom interfaces +it is necessary to create new interface file with unique name (ipp-.if) +and include it in the new package as follows: .... %install @@ -205,14 +214,15 @@ install -p -m 644 ipp-%{modulename}.if %{buildroot}%{_datadir}/selinux/devel/inc %{_datadir}/selinux/devel/include/%{moduletype}/ipp-%{modulename}.if .... -All custom interfaces _must_ be prefixed with "ipp_" not to be confused -with distribution interfaces. +All custom interfaces _must_ be prefixed with "ipp_" +not to be confused with distribution interfaces. -Changes to interfaces of the original module can only be delivered via -distribution selinux-policy-* packages. If such a change is necessary, -please contact the SELinux team, or submit a pull request. Please bear -in mind that such changes will influence other policy modules that use -given interface. +Changes to interfaces of the original module +can only be delivered via distribution selinux-policy-* packages. +If such a change is necessary, please contact the SELinux team, +or submit a pull request. +Please bear in mind that such changes will influence other policy modules +that use given interface. [#custom-policy-modules-and-distribution-policy] === Custom policy modules and distribution policy @@ -220,9 +230,9 @@ given interface. It's important to note that distribution policies _should not_ use interfaces from removable policy modules. -When using types from custom policy modules _stub_ interfaces should be -used instead of directly requiring given type. Stub interface is defined -and used in distribution module as follows. +When using types from custom policy modules +_stub_ interfaces should be used instead of directly requiring given type. +Stub interface is defined and used in distribution module as follows. .... $ cat distribution_module.if @@ -259,14 +269,14 @@ optional_policy(` .... As with any type defined outside of _SELinux policy base modules_, -_optional_policy_ block must be used when using types from removable -modules in distribution policy. +_optional_policy_ block must be used +when using types from removable modules in distribution policy. [#creating-the-spec-file] == Creating the Spec File -When a Git repository with SELinux policy sources is ready, create your -product .spec file (rpmbuild configuration file). +When a Git repository with SELinux policy sources is ready, +create your product .spec file (rpmbuild configuration file). [#the-preamble] === The Preamble @@ -328,8 +338,9 @@ After this step, a product policy is installed on your system. [#the-post-section] === The %post Section -Next step is loading a product policy into the kernel in the RPM -post-install process. This step also contains the post-uninstall process +Next step is loading a product policy into the kernel +in the RPM post-install process. +This step also contains the post-uninstall process to remove a product policy properly during a product uninstallation. .... @@ -348,9 +359,9 @@ fi [#the-files-section] === The %files Section -The end of the .spec file contains the `%files` section. This section -declares which files and directories are owned by the package. Last part -of spec file is changelog. +The end of the .spec file contains the `%files` section. +This section declares which files and directories are owned by the package. +The last part of the spec file is changelog. .... %files @@ -366,34 +377,34 @@ of spec file is changelog. [#adding-dependency-to-the-spec-file-of-corresponding-package] === Adding dependency to the spec file of corresponding package -The *-selinux package should only be required on SELinux enabled -systems. Therefore the following rich dependency syntax should be used: +The *-selinux package should only be required on SELinux enabled systems. +Therefore the following rich dependency syntax should be used: .... Requires: (%{name}-selinux if selinux-policy-%{selinuxtype}) .... -This ensures that the *-selinux package and all it's dependencies are -not pulled into containers and other systems that do not use SELinux. +This ensures that the *-selinux package and all it's dependencies +are not pulled into containers and other systems that do not use SELinux. [#selinux-policy-module-priorities] === SELinux Policy module priorities -Policy modules can be installed with different priorities. When -multiples modules of the same name exist in the system, only the module -with the highest priority takes effect. +Policy modules can be installed with different priorities. +When multiple modules of the same name exist in the system, +only the module with the highest priority takes effect. -Distribution policy modules are installed with priority of 100. When -shipping custom policy, it should always be shipped with priority of 200 -to override distribution policy. This value is contained inside the -_selinux_modules_install_ macro and should not be changed. +Distribution policy modules are installed with priority of 100. +Custom policy should always be shipped with priority of 200 +to override distribution policy. +This value is contained inside the _selinux_modules_install_ macro +and should not be changed. -Note that _semodule_ installs policy modules with priority of 400 by -default. +Note that _semodule_ installs policy modules with priority of 400 by default. See -https://plautrba.fedorapeople.org/selinux-modules-and-priority.html/[SELinux -modules and priority] for more details about module priority. +https://plautrba.fedorapeople.org/selinux-modules-and-priority.html[SELinux modules and priority] +for more details about module priority. [#building-a-package-with-an-selinux-product-policy] == Building a Package with an SELinux Product Policy @@ -402,15 +413,16 @@ modules and priority] for more details about module priority. === Setting Booleans During an Product Policy Installation In some cases, it is necessary to enable or disable some booleans -defined in a system security policy. This change should be done during -an installation of an SELinux product package and it should also follow -a couple of rules. +defined in a system security policy. +This change should be done during the installation phase +of the SELinux product package and it should also follow a couple of rules. To change system booleans, use the following steps: -* Find a boolean that fits your needs best. Try to avoid generic -booleans, which allow many things and their change could bring security -holes to the system. +* Find a boolean that fits your needs best. +Try to avoid generic booleans, which allow many things +and their change could bring security holes to the system. + * Specify booleans in the following format in the .spec file: + .... @@ -419,9 +431,11 @@ holes to the system. %global selinuxbooleans booleanname=1 booleanname2=0 .... -* It is necessary to use special macro _%selinux_set_booleans during_ -"%post" phase of rpmbuild to make sure that the specified boolean values -are set.See following example: +* It is necessary to use special macro _%selinux_set_booleans +during "%post" phase of rpmbuild +to make sure that the specified boolean values are set. + +See the following example: + .... %post @@ -434,27 +448,25 @@ are set.See following example: .... -Usage of booleans in a .spec file follows these rules: +The boolean macros mentioned above behave as follows: + +* The value of each boolean set using "%selinux_set_booleans" is recorded +and will be reset to the original value when "%selinux_unset_booleans" is called -* If a boolean mentioned in the product .spec file is not set by user -previously, it will be changed in the %post install phase and during the -%post uninstall phase will be reverted. -* If a boolean mentioned in the product .spec file was set by user -previously, it will be changed to a value from this file. However, -during the uninstallation of a product SELinux subpackage, it will not -be reverted. +* Number of calls to "%selinux_set_booleans" and "%selinux_unset_booleans" +has to match in order for this mechanism to work properly [#port-labeling] === Port Labeling -If your product policy does not define port labels (such as -"product_port_t"), you can skip this section. +If your product policy does not define port labels (such as "product_port_t"), +you can skip this section. -You should assign a port number and a port type for every port label. -Assigning a port label should be done in %post install phase. For -example, for the TCP 1111 port, the -`semanage port -a -t product_port_t -p tcp 1111` command should be added -to the if statement in the .spec file: +You should assign a port number and a port type to every port label. +Assigning a port label should be done in %post install phase. +For example, for the TCP 1111 port, the +`semanage port -a -t product_port_t -p tcp 1111` +command should be added to the if statement in the .spec file: .... if %{_sbindir}/selinuxenabled ; then @@ -467,13 +479,15 @@ following: .... -a Add a record of the specified object type --t SELinux type for the object from product policy +-t SELinux type for the port -p Protocol for the specified port (tcp|udp) .... -For the %post uninstall phase, the port assignment should be removed. To -do this, add the `semanage port -d -t ` command in your .spec -file, for example: +For the %post uninstall phase, the port assignment should be removed. +To do this, add the +`semanage port -d -t ` +command in your .spec file. +For example: .... if %{_sbindir}/selinuxenabled ; then @@ -481,13 +495,14 @@ if %{_sbindir}/selinuxenabled ; then fi .... -[#removing-an-own-product-policy-from-the-system-policy] -== Removing an Own Product Policy from the System Policy +[#removing-your-product-policy-from-the-system-policy] +== Removing your Product Policy from the System Policy -When your own product SELinux subpackage is ready for a release, contact -the SELinux policy maintainer. He should remove a product policy from -the SELinux distribution policy and update the package. A product -maintainer should add dependency for the selinux-policy package: +When your own product SELinux subpackage is ready for a release, +contact the SELinux policy maintainer. +He should remove the product policy from the SELinux distribution policy +and update the package. +You should then add a dependency on the new selinux-policy package: .... # Version of selinux-policy when product policy was removed @@ -495,9 +510,10 @@ maintainer should add dependency for the selinux-policy package: Requires: selinux-policy >= %{selinux_policyver} .... -If the released policy was not part of the distribution policy, there is -no need to add version dependency to your .spec file. +If the released policy was not part of the distribution policy, +there is no need to add a version dependency to your .spec file. -Now is your SELinux subpackage ready to release. It is recommended to -create a group update together with selinux-policy package to ensure -that the updating process will be successful. +Now your SELinux subpackage is ready for release. +It is recommended to create a group update +together with selinux-policy package +to ensure that the updating process will be successful.