Installation

At the command line:

$ pip install oslo.privsep

Usage

oslo.privsep lets you define in your code specific functions that will run in predefined privilege contexts. This lets you run functions with more (or less) privileges than the rest of the code. Privsep functions live in a specific privsep submodule (for example, nova.privsep for nova).

Defining a context

Contexts are defined in the privsep/__init__.py file. For example, this defines a sys_admin_pctxt with CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH, CAP_FOWNER, CAP_NET_ADMIN, and CAP_SYS_ADMIN rights (equivalent to sudo rights):

from oslo_privsep import capabilities
from oslo_privsep import priv_context
sys_admin_pctxt = priv_context.PrivContext(


    'nova',


    cfg_section='nova_sys_admin',


    pypath=__name__ + '.sys_admin_pctxt',


    capabilities=[capabilities.CAP_CHOWN,


                  capabilities.CAP_DAC_OVERRIDE,


                  capabilities.CAP_DAC_READ_SEARCH,


                  capabilities.CAP_FOWNER,


                  capabilities.CAP_NET_ADMIN,


                  capabilities.CAP_SYS_ADMIN],
)

Defining a context with timeout

It is possible to initialize PrivContext with timeout:

from oslo_privsep import capabilities
from oslo_privsep import priv_context
dhcp_release_cmd = priv_context.PrivContext(


    __name__,


    cfg_section='privsep_dhcp_release',


    pypath=__name__ + '.dhcp_release_cmd',


    capabilities=[caps.CAP_SYS_ADMIN,


                  caps.CAP_NET_ADMIN],


    timeout=5
)

PrivsepTimeout is raised if timeout is reached.

WARNING:

Defining a privileged function

Functions are defined in files under the privsep/ subdirectory, for example in a privsep/motd.py file for functions touching the MOTD file. They make use of a decorator pointing to the context we defined above:

import nova.privsep
@nova.privsep.sys_admin_pctxt.entrypoint
def update_motd(message):


    with open('/etc/motd', 'w') as f:


        f.write(message)

Privileged functions must be as simple, specialized and narrow as possible, so as to prevent further escalation. In this example, update_motd(message) is narrow: it only allows the service to overwrite the MOTD file. If a more generic update_file(filename, content) was created, it could be used to overwrite any file in the filesystem, allowing easy escalation to root rights. That would defeat the whole purpose of oslo.privsep.

Defining a privileged function with timeout

It is possible to use entrypoint_with_timeout decorator:

from oslo_privsep import daemon
from neutron import privileged
@privileged.default.entrypoint_with_timeout(timeout=5)
def get_link_devices(namespace, **kwargs):


    try:


        with get_iproute(namespace) as ip:


            return make_serializable(ip.get_links(**kwargs))


    except OSError as e:


        if e.errno == errno.ENOENT:


            raise NetworkNamespaceNotFound(netns_name=namespace)


        raise


    except daemon.FailedToDropPrivileges:


        raise


    except daemon.PrivsepTimeout:


        raise

PrivsepTimeout is raised if timeout is reached.

WARNING:

Using a privileged function

To use the privileged function in the regular code, you can just call it:

import nova.privsep.motd
...
nova.privsep.motd.update_motd('This node is currently idle')

It is better to import the complete path (import nova.privsep.motd) rather than the motd name (from nova.privsep import motd) so that it is easier to spot that the function runs in a different privileged context.

For more details, you can read the following blog post:

Converting from rootwrap to privsep

oslo.rootwrap is a precursor of oslo.privsep to allow code to run commands under sudo if they match a predefined filter. For example, you could define a filter that would allow you to run chmod as root using the following filter:

chmod: CommandFilter, chmod, root

Beyond the bad performance of calling full commands in order to accomplish simple tasks, rootwrap also led to bad security: it was difficult to filter commands in a way that would not easily allow privilege escalation.

Replacing rootwrap filters with privsep functions is easy. The chmod filter above can be replaced with a function that calls os.chmod(). However a straight 1:1 filter:function replacement generally results in functions that are still too broad for good security. It is better to replace each chmod rootwrap call with a narrow privsep function that will limit it to specific files.

Sometimes it is necessary to refactor the calling code: the rootwrap design discouraged the creation of new filters and therefore often resulted in the creation of overly-broad calling functions.

As an example, this patch series is work-in-progress to transition Nova from rootwrap to privsep.

For more details, you can read the following blog post:

Contributor Guide

Contributing

If you would like to contribute to the development of oslo's libraries, first you must take a look to this page:

If you would like to contribute to the development of OpenStack, you must follow the steps in this page:

If you already have a good understanding of how the system works and your OpenStack accounts are set up, you can skip to the development workflow section of this documentation to learn how changes to OpenStack should be submitted for review via the Gerrit tool:

Pull requests submitted through GitHub will be ignored.

Bugs should be filed on Launchpad, not GitHub:

CHANGES

3.1.0

3.0.1

3.0.0

2.8.0

2.7.0

2.6.2

2.6.1

2.6.0

2.5.0

2.4.0

2.3.0

2.2.1

2.2.0

2.1.1

2.1.0

2.0.0

1.34.0

1.33.3

1.33.2

1.33.1

1.33.0

1.32.1

1.32.0

1.31.1

1.31.0

1.30.1

1.29.0

1.28.0

1.26.0

1.25.0

1.24.0

1.23.0

1.22.0

1.21.1

1.21.0

1.20.0

1.19.0

1.18.0

1.17.0

1.16.0

1.15.0

1.14.0

1.13.0

1.12.0

1.11.0

1.10.0

1.9.0

1.8.0

1.7.0

1.6.0

1.5.0

1.3.0

1.2.0

1.1.0

1.0.0

0.3.0

0.2.0

0.1.0

API

oslo_privsep

oslo_privsep package

Subpackages

oslo_privsep.functional package

Submodules

oslo_privsep.functional.test_daemon module

Module contents

Submodules

oslo_privsep.capabilities module

oslo_privsep.comm module

Serialization/Deserialization for privsep.

The wire format is a stream of msgpack objects encoding primitive python datatypes. Msgpack 'raw' is assumed to be a valid utf8 string (msgpack 2.0 'bin' type is used for bytes). Python lists are converted to tuples during serialization/deserialization.

oslo_privsep.daemon module

Privilege separation ("privsep") daemon.

To ease transition this supports 2 alternative methods of starting the daemon, all resulting in a helper process running with elevated privileges and open socket(s) to the original process:

The privsep daemon exits when the communication channel is closed, (which usually occurs when the unprivileged process exits).

oslo_privsep.priv_context module

oslo_privsep.version module

Module contents