Project:SELinux/CodingStyle

Our coding-style is based on the reference project StyleGuide.

Organization of code in .te files
When a policy module is adapted by Gentoo, but is available in the reference policy, then all changes made for Gentoo specifically (and not yet upstreamed) must be put at the end of the file, inside a  block.
 * This is necessary so that the main file can be easily updated with upstream changes (no patch collisions).
 * The coding style for the main document, and the large  block at the end, are the same. Treat them as two separate files.
 * The only exception to this rule are Gentoo-specific code blocks that are upstreamed (which follow the same convention as other  blocks).

When changes must be made inline (for instance to remove interface calls we do not want) comment out the interface calls and add a comment right above it startin with "Gentoo:", like so:

Gentoo-specific change in the policy

General organization
The type enforcement rules should have the following organization.

First, the declarations are provided. These are, in order:
 * 1) Boolean declarations (using the   block, for base policy)
 * 2) Tunable declarations (using the   blocks, for modular policy)
 * 3) Attribute declarations
 * 4) Type declarations

Introduce sufficient documentation for each declaration, like so:

Example documentation for declarations

Next, the local policy rules are provided:
 * first the "main" domain
 * then in blocks ordered alphabetically by the domain (but ignoring unconfined domains)

Each block must be prepended with a comment like so:

Comment block for a new local policy

The order inside the policy rules is as follows:
 * 1) Self rules, starting with the *capability* and *process* object classes
 * 2) Rules applicable to the objects owned by the module itself, sorted by object type alphabetically
 * 3) Calls to the kernel layer module, first the kernel module itself and then in alphabetical order
 * 4) Calls to the system layer module, in alphabetical order
 * 5) Calls to all other modules, in alphabetical order
 * 6) Build option blocks (using  )
 * 7) Conditional policy blocks (using  )
 * 8) Tunable policy blocks (using  )
 * 9) Optional policy blocks (using  )

Finally, unconfined access rules are added, following the same structure as the local policy rules.

Tunables
Tunables must be documented with the in-line documentation system, like so:

Using in-line documentation for tunables

Always start a boolean with the module name itself.

Please try to use boolean names that match the following use cases, if possible:
 * Support for particular system-provided services (video support, audio support, but also NFS support or Kerberos support) use  in the name, like so:
 * to enable NFS support
 * to enable video support
 * Support for application-provided services (i.e. from within the application managed by the domain) uses  in the name, like so:
 * enables the FTP server support for the  domain
 * enables home directory support in the  domain
 * Support for a specific implementation (usually in functionality-oriented policies) follows the  convention, like so:
 * enables fcron-specific privileges in the cron module
 * enables hiawatha-specific privileges in the apache module
 * Access rights by the domains follows the interface naming if applicable and understandable by end users:
 * to allow the domain to manage all types associated with the  attribute
 * to allow the domain to manage all classes of the  type
 * to allow the domain to read  files
 * Access rights which are grouped functionally have multiple access interface calls and cannot be named after them easily. For these, use the  prefix with a functionally related suffix, like so:
 * to enable the foo domain to connect to all ports
 * to enable the foo domain to connect to the HTTP ports
 * to enable the  domain to relabel files

Attributes
In case of client- and server domains,
 * attribute names should follow the  and   naming conventions, like so:
 * is for domains that (always) are PulseAudio clients
 * the interface to assign the attribute is called, like so:
 * if applicable, the interface to assign privileges is called, like so:
 * if applicable, the interface to assign privileges is called, like so:

In case of server membership domains (i.e. logical grouping of types related to a specific domain),
 * use the  suffix, like so:
 * for all postfix related domain types
 * for all java related domain types
 * if templates are used to assign the attribute, always end the template with, like so:
 * to assign
 * to assign
 * if not through templates (i.e. no types are generated) then use interface names like so:
 * to assign
 * to assign

In case of object type bundling, try to use functionally coherent naming.
 * try not to use the  suffix as that is used for the interfaces assigning the type

Type declarations
Types should be named functionally, starting with the module name, and ending with the  suffix.

The following table shows proper naming for these types.

Organization of code in .if files
Interface files should be organized as follows:
 * 1) Templates
 * 2) Domain related interfaces
 * 3) Role interfaces
 * 4) Run interfaces
 * 5) Domain transition interfaces
 * 6) Execution interfaces
 * 7) Transformation interfaces (which assign attributes to types), sorted alphabetically by primary object type or attribute
 * 8) Access interfaces
 * 9) Alphabetically by primary object type or attribute, then
 * 10) Increasing in access level (getattr, search, setattr, list, read, append, write, rw, create, filetrans, rename, delete, manage, relabelto, relabelfrom, relabel), then
 * 11) Access interface before dontaudit (if a   interface is added)
 * 12) Admin interfaces
 * 13) If multiple components are used, order alphabetically by component, with the "master" admin interface last
 * 14) Unconfined interface

Templates
Templates should always end with  in the name.

Domain related interfaces
A role interface is meant to be assigned to user domains and contain all the necessary privileges to work with and interact with a specific type.
 * The first argument must be the role, and the second argument the userdomain type.

A run interface is meant to be assigned to other domains (which can be user domains) and contains only the necessary privileges to execute and transition to the domain (including role privileges).
 * The first argument must be the domain type, and the second argument the role.
 * The interface must call the  interface

Example run interface

Transformation interfaces
Transformation interfaces generally assign an attribute or a set of privileges to a type.

First the transformation interface that assigns an attribute is listed. This interface is named after the attribute that it assigns, with the  suffix:

Next, the transformation interface that grants all necessary privileges associated with the attribute is mentioned, using the  suffix:

Examples are:
 * assigns the  attribute
 * assigns the  attribute
 * assigns the necessary privileges that a PulseAudio client would need.

Access interfaces
Access interfaces assign privileges to a domain to interact with one or more resources.

Single type access interface
The single type access interface is named like so:

Naming convention for single type access interfaces

In this, the
 * is the name of the module.
 * is the optional modifier (which should be placed below the one without  in it) to support not auditing denials related to the access interface.
 * is the set of privileges, and should be the name as is used in the  and   definitions
 * is the target for the access privilege
 * If it is a regular type which starts with the module name, then it is the type name stripped of the module name and without :
 * to read
 * If it is a regular type which does not start with the module name, "only" contains the module name or is ambiguous with other prefixed types, then it starts with  followed by the type name without  :
 * (no object mentioned otherwise, as the object is )
 * If it is an attribute, the name starts with, is stripped of the module name (if applicable) and is then followed by the attribute name
 * If no class is provided, the name is plural (due to the "all")
 * is an optional class which limits the applicability of the interface to the given class, and is always plural (hence ending with "s")
 * is an optional class which limits the applicability of the interface to the given class, and is always plural (hence ending with "s")

Transition access interface
The transition access interface is named like so:

Naming convention for transition access interfaces

In this, the
 * the  is the type of the parent resource from which a transition is defined.
 * In case of a filetransition, it is the type of the directory in which the file would be created
 * The naming convention is similar as the one for  in the single access interface. The "is ambiguous" part here applies. For instance,   means that it is the "generic log type" (i.e.  ) and not the module log type  that is the parent.
 * the  is the transition type to work on
 * in case of a file transition, it is
 * the  is the type to assign after transition. Its naming convention is similar as the one for   in the single access interface.

Organization of code in .fc files
The organization in the .fc files is as follows:
 * 1) Alphabetically by path, then
 * 2) Increasing in depth, then
 * 3) First regular expressions, and then exact matches