Crate selinux

🛡️ Safe Rust bindings for libselinux

SELinux is a flexible Mandatory Access Control for Linux.

This crate supports libselinux from version 2.8 to 3.8. Later versions might still be compatible. This crate exposes neither deprecated nor undocumented SELinux API functions and types.

⚠️ This crate is specific to Android and some Linux distributions. Building it for other platforms, or for the Linux kernel, results in an empty crate.

This documentation is too brief to cover SELinux. Please refer to the official SELinux documentation, the manual pages of the libselinux native library, and the selinux-sys crate for a more complete picture on how to use this crate.

If you cannot find a feature you are looking for by its name, but you know which libselinux APIs relate to it, then try searching the documentation by that API name.

⚓ Backward compatibility

This crate requires libselinux version 2.8, at least. However, this crate provides some functions that are based on libselinux functions implemented in later versions. When such newer functions are needed, this crate attempts to load them dynamically at runtime. If such functions are implemented by libselinux, then the called crate functions run as expected. If the needed functions are not implemented by libselinux, then an error is returned indicating that the called crate function is unsupported.

🔢 Versioning

This project adheres to Semantic Versioning. The CHANGELOG.md file details notable changes over time.

🛠️ Development

This section is only relevant for developers contributing to this crate, and not for users of this crate.

💡 If you’re developing this crate and feel important information is missing in this section, then please create an issue or a pull request to fix that.

Build system

This crate uses only cargo as a build system. Usual commands are used to perform most operations, e.g., build, test, fmt.

Code is read many times more that written, so this crate’s code is always formatted using cargo fmt.

Operations requiring special handling are crafted as cargo xtask targets. The full list of these special operations can be determined by running:

cargo xtask

Each special operation can be executed by running:

cargo xtask <operation> [parameters...]

For example, to generate coverage information, run:

cargo xtask coverage

Testing

This crate can only be tested on a Linux distribution that has SELinux supported and enabled at multiple levels:

• The Linux kernel must support SELinux, and have it enabled.
• The file system must be correctly configured.
• The user space must have access to SELinux, usually via libselinux.

Red Hat Enterprise Linux-like distributions (e.g., Fedora, CentOS, RockyLinux) are suitable for testing this crate, either on hardware or inside virtual machines, but not in containers.

Given that coverage information requires running tests, that information can only be successfully obtained on a system with SELinux enabled.

Behavior

This crate uses the libselinux API as documented in the manual pages. It tries to avoid assumptions about implementation details as far as possible, even when performance might be improved with such knowledge.

The structures and enumerations defined by this crate assume that their user might, at some point, decide to call raw libselinux APIs (possible using the selinux-sys crate) for features not yet provided by this crate, or for some other reasons. That is the reason why methods such as as_ptr() are implemented by these structures, exposing the raw values that libselinux APIs recognize.

Change log

The change log is useful to get a picture of what is going on with the crate in the recent past.

Modules

avc

Access Vector Cache.

call_back

SELinux call backs.

context_restore

Restore file(s) default SELinux security contexts.

errors

Errors.

label

Labeling files.

path

SELinux paths.

policy

SELinux policies.

utils

Utilities.

Structs

FileAccessMode

File access mode.

LayerColors

Background and foreground colors.

OpaqueSecurityContext

Opaque security context.

RGB

Red, green and blue components of a color.

SecurityClass

SELinux security class.

SecurityContext

SELinux security context.

SecurityContextColors

Colors of a security context.

SecurityContextList

List of security contexts.

Enums

KernelSupport

Support of SELinux in the running kernel.

ProtectionCheckingMode

Protection checked by SELinux on mmap() and mprotect() calls.

SELinuxMode

SELinux enforcing mode.

UndefinedHandling

SELinux handling of undefined object classes and permissions.

Functions

boot_mode

Determine how the system was set up to run SELinux.

current_mode

Determine the current SELinux enforcing mode.

default_type_for_role

Get the default type (domain) for role, and set type to refer to it.

flush_class_cache

Flush the SELinux class cache, e.g., upon a policy reload.

kernel_support

Determine the support of SELinux in the running kernel.

protection_checking_mode

Determine the protection currently checked by SELinux on mmap() and mprotect() calls.

reset_config

Force a reset of the loaded configuration.

se_user_and_level

Get the SELinux user name and level for a given Linux user name.

set_current_mode

Set the current SELinux enforcing mode.

set_dynamic_mapping

Establishes a mapping from a user-provided ordering of object classes and permissions to the numbers actually used by the loaded system policy.

undefined_handling

Return the current SELinux handling of undefined object classes and permissions.