NAME

Linux::Landlock::Direct - Direct, low-level interface to the Linux Landlock API

DESCRIPTION

This module provides a functional interface to the Linux Landlock API. It is a relatively thin wrapper around the Landlock system calls.

See Linux::Landlock for a higher-level OO and exception based interface.

See https://docs.kernel.org/userspace-api/landlock.html for more information about Landlock.

SYNOPSIS

    use Linux::Landlock::Direct qw(:functions :constants set_no_new_privs);

    # create a new ruleset with all supported actions
    my $ruleset_fd = ll_create_ruleset()
      or die "ruleset creation failed: $!\n";
    opendir my $dir, '/tmp';
    # allow read and write access to files in /tmp, truncate is typically also needed, depending on the open call
    ll_add_path_beneath_rule($ruleset_fd,
        $LANDLOCK_RULE{PATH_BENEATH},
        $LANDLOCK_ACCESS_FS{READ_FILE} | $LANDLOCK_ACCESS_FS{WRITE} | $LANDLOCK_ACCESS_FS{TRUNCATE},
        $dir,
    );
    # NO_NEW_PRIVS is required for ll_restrict_self() to work, it can be set by any means, e.g. inherited or
    # set via some other module; this implementation just exists for convenience
    set_no_new_privs();
    # apply the ruleset to the current process and future children. This cannot be undone.
    ll_restrict_self($ruleset_fd);

FUNCTIONS

ll_get_abi_version()

Int, returns the ABI version of the Landlock implementation. Minimum version is 1. Returns -1 on error.

ll_create_fs_ruleset(@actions)

Int (file descriptor), creates a new Landlock ruleset that covers the specified file system actions.

If no actions are specified, all supported actions are covered.

Returns the file descriptor of the new ruleset on success, or undef on error.

ll_create_net_ruleset(@actions)

Int (file descriptor), like "ll_create_fs_ruleset(@actions)", but for network actions.

This requires an ABI version of at least 4. Returns undef on error.

ll_create_ruleset($fs_actions, $net_actions)

Int (file descriptor), creates a new Landlock ruleset that can cover file system and network actions at the same time. Returns undef on error.

ll_add_path_beneath_rule($ruleset_fd, $allowed_access, $parent)

Add a rule of type PATH_BENEATH to the ruleset. $allowed_access is a bitmask of allowed accesses, $parent is the filesystem object the rule applies to.

It can be either a Perl file handle or a bare file descriptor and point to either a directory or a file.

If access rights are not supported by the running kernel, they are silently ignored, in line with the "best effort" approach recommended by the Landlock documentation.

Returns undef on error or the set of applied access rights on success.

ll_add_net_port_rule($ruleset_fd, $allowed_access, $port)

Add a rule of type NET_PORT to the ruleset. $allowed_access is a bitmask of allowed accesses, $port is the port the rule applies to.

This requires an ABI version of at least 4.

If access rights are not supported by the running kernel, they are silently ignored. Returns undef on error or the set of applied access rights on success.

ll_all_fs_access_supported()

Returns a bitmask of all file system access rights that are known to this module and supported by the running kernel.

ll_all_net_access_supported()

Returns a bitmask of all network access rights that are known to this module and supported by the running kernel.

ll_restrict_self($ruleset_fd)

Apply the ruleset to the current process and all future children. This cannot be undone. NO_NEW_PRIVS must have been applied to the current process before calling this function.

set_no_new_privs()

Set the NO_NEW_PRIVS flag for the current process. This is required for "ll_restrict_self($ruleset_fd)" to work. See https://docs.kernel.org/userspace-api/no_new_privs.html for more information.

This is technically not part of Landlock and only added for convenience.

EXPORTS

Nothing is exported by default. The following tags are available:

:functions

All functions, except for set_no_new_privs.

:constants

All constants:

%LANDLOCK_ACCESS_FS

    # ABI version 1
    EXECUTE
    WRITE_FILE
    READ_FILE
    READ_DIR
    REMOVE_DIR
    REMOVE_FILE
    MAKE_CHAR
    MAKE_DIR
    MAKE_REG
    MAKE_SOCK
    MAKE_FIFO
    MAKE_BLOCK
    MAKE_SYM
    # ABI version 2
    REFER
    # ABI version 3
    TRUNCATE

%LANDLOCK_ACCESS_NET

    # ABI version 4
    BIND_TCP
    CONNECT_TCP

%LANDLOCK_RULE

    PATH_BENEATH
    NET_PORT

See https://docs.kernel.org/userspace-api/landlock.html for more information.

set_no_new_privs

The set_no_new_privs helper function.

THREADS

Landlock rules are per thread. So either apply them before spawning other threads or ensure that the rules are applied in each thread.