← Back to branch summary

~kyle-ireland/opencompute/Checkbox-Port-CentOS

« back to all changes in this revision

Viewing changes to plainbox/docs/dev/trusted-launcher.rst

  • Committer: Tarmac
  • Author(s): Sylvain Pineau
  • Date: 2013-05-14 20:34:04 UTC
  • mfrom: (2116.4.1 launchpad/launcher-doc)
  • Revision ID: tarmac-20130514203404-ka98wos28lkr317e
"[r=roadmr][bug=][author=sylvain-pineau] docs: dev: Added the checkbox-trusted-launcher documentation."

Show diffs side-by-side

added added

removed removed

Lines of Context:
plainbox/docs/dev/trusted-launcher.rst
 
1
Running jobs as root
 
2
====================
 
3
 
 
4
:term:`PlainBox` is started without any privilege.
 
5
But several tests need to start commands requiring privileges.
 
6
 
 
7
Such tests will call a trusted launcher, a standalone script
 
8
which does not depend on the :term:`PlainBox` core modules.
 
9
`polkit <http://www.freedesktop.org/wiki/Software/polkit>`_
 
10
will control access to system resources.
 
11
The trusted launcher has to be started using
 
12
`pkexec <http://www.freedesktop.org/software/polkit/docs/0.105/pkexec.1.html>`_
 
13
so that the related policy file works as expected.
 
14
 
 
15
To avoid a security hole that allows anyone to run anything as root,
 
16
the launcher can only run jobs installed in a system-wide directory.
 
17
This way we are not weaken the trust system as root access is required
 
18
to install both components (the trusted runner and jobs).
 
19
The :term:`PlainBox` process will send an identifier which is matched by a well-known
 
20
list in the trusted launcher. This identifier is the job hash:
 
21
 
 
22
.. code-block:: bash
 
23
 
 
24
    $ pkexec trusted-launcher JOB-HASH
 
25
 
 
26
See :meth:`plainbox.impl.secure.checkbox_trusted_launcher.BaseJob.get_checksum()` for details about job hashes.
 
27
 
 
28
Using Polkit
 
29
^^^^^^^^^^^^
 
30
 
 
31
Available authentication methods 
 
32
--------------------------------
 
33
 
 
34
.. note::
 
35
 
 
36
    Only applicable to the package version of PlainBox
 
37
 
 
38
PlainBox comes with two authentication methods but both aim to retain the
 
39
granted privileges for the life of the :term:`PlainBox` process.
 
40
 
 
41
*   The first method will ask the password only once and show the following
 
42
    agent on desktop systems (a text-based agent is available for servers):
 
43
 
 
44
    .. code-block:: text
 
45
    
 
46
        +-----------------------------------------------------------------------------+
 
47
        | [X]                            Authenticate                                 |
 
48
        +-----------------------------------------------------------------------------+
 
49
        |                                                                             |
 
50
        | [Icon] Please enter your password. Some tests require root access to run    |
 
51
        |        properly. Your password will never be stored and will never be       |
 
52
        |        submitted with test results.                                         |
 
53
        |                                                                             |
 
54
        |        An application is attempting to perform an action that requires      |
 
55
        |        privileges.                                                          |
 
56
        |        Authentication as the super user is required to perform this action. |
 
57
        |                                                                             |
 
58
        |        Password: [________________________________________________________] |
 
59
        |                                                                             |
 
60
        | [V] Details:                                                                |
 
61
        |  Action: org.freedesktop.policykit.pkexec.run-plainbox-job                  |
 
62
        |  Vendor: PlainBox                                                           |
 
63
        |                                                                             |
 
64
        |                                                     [Cancel] [Authenticate] |
 
65
        +-----------------------------------------------------------------------------+
 
66
 
 
67
    The following policy file has to be installed in :file:`/usr/share/polkit-1/actions/`
 
68
    on Ubuntu systems.
 
69
    Asking the password just one time and keeps the authentication for forthcoming
 
70
    calls is provided by the **allow_active** element and the **auth_admin_keep** value.
 
71
    
 
72
    Check the `polkit actions <http://www.freedesktop.org/software/polkit/docs/0.105/polkit.8.html#polkit-declaring-actions>`_
 
73
    documentation for details about the other parameters.
 
74
 
 
75
    .. code-block:: xml
 
76
    
 
77
        <?xml version="1.0" encoding="UTF-8"?>
 
78
        <!DOCTYPE policyconfig PUBLIC
 
79
         "-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"
 
80
         "http://www.freedesktop.org/standards/PolicyKit/1/policyconfig.dtd">
 
81
        <policyconfig>
 
82
        
 
83
          <vendor>PlainBox</vendor>
 
84
          <vendor_url>https://launchpad.net/checkbox</vendor_url>
 
85
          <icon_name>checkbox</icon_name>
 
86
        
 
87
          <action id="org.freedesktop.policykit.pkexec.run-plainbox-job">
 
88
            <description>Run Job command</description>
 
89
            <message>Authentication is required to run a job command.</message>
 
90
            <defaults>
 
91
              <allow_any>no</allow_any>
 
92
              <allow_inactive>no</allow_inactive>
 
93
              <allow_active>auth_admin_keep</allow_active>
 
94
            </defaults>
 
95
            <annotate key="org.freedesktop.policykit.exec.path">/usr/bin/checkbox-trusted-launcher</annotate>
 
96
            <annotate key="org.freedesktop.policykit.exec.allow_gui">TRUE</annotate>
 
97
          </action>
 
98
        
 
99
        </policyconfig>
 
100
 
 
101
*  The second method is only intended to be used in headless mode (like `SRU`).
 
102
   The only difference with the above method is that **allow_active** will be set to **yes**.
 
103
 
 
104
.. note::
 
105
 
 
106
    The two policy files are available in the PlainBox :file:`contrib/` directory.
 
107
 
 
108
Environment settings with pkexec 
 
109
--------------------------------
 
110
 
 
111
`pkexec <http://www.freedesktop.org/software/polkit/docs/0.105/pkexec.1.html>`_ 
 
112
allows an authorized user to execute a command as another user.
 
113
But the environment that ``command`` will run it, will be set to a minimal known
 
114
and safe environment in order to avoid injecting code through ``LD_LIBRARY_PATH``
 
115
or similar mechanisms.
 
116
 
 
117
However, some jobs commands require specific enviroment variables such as the
 
118
name of an access point for a wireless test. Those kind of variables must be
 
119
available to the trusted launcher.
 
120
To do so, the enviromment mapping is sent to the launcher like key/value pairs
 
121
are sent to the env(1) command:
 
122
 
 
123
.. code-block:: bash
 
124
 
 
125
    $ pkexec trusted-launcher JOB-HASH [NAME=VALUE [NAME=VALUE ...]]
 
126
 
 
127
Each NAME will be set to VALUE in the environment given that they are known
 
128
and defined in the :ref:`JobDefinition.environ <environ>` parameter.
 
129
 
 
130
Checkbox trusted launcher
 
131
^^^^^^^^^^^^^^^^^^^^^^^^^
 
132
 
 
133
The checkbox trusted launcher is the minimal code needed to be able to run a
 
134
:term:`CheckBox` job command.
 
135
 
 
136
It offers base classes for the following core subclasses:
 
137
 
 
138
* :class:`plainbox.impl.rfc822.RFC822Record`
 
139
* :class:`plainbox.impl.job.JobDefinition`
 
140
 
 
141
The only duplicated code is the RFC822 parser, where all logging features have
 
142
been removed.
 
143
 
 
144
The :class:`plainbox.impl.secure.checkbox_trusted_launcher.Runner` class just
 
145
executes the command process with :py:func:`os.execve`.
 
146
 
 
147
Internally the checkbox trusted launcher looks for jobs in the system locations defined in 
 
148
:attr:`plainbox.impl.secure.checkbox_trusted_launcher.Runner.CHECKBOXES` which defaults to :file:`/usr/share/checkbox*`.
 
149
This way the launcher can match all :term:`CheckBox` variants, like ``checkbox-oem(-.*)?``
 
150
 
 
151
Usage
 
152
-----
 
153
 
 
154
.. code-block:: text
 
155
 
 
156
    checkbox-trusted-launcher [-h] (--hash HASH | --warmup)
 
157
                              [--via LOCAL-JOB-HASH]
 
158
                              [NAME=VALUE [NAME=VALUE ...]]
 
159
    
 
160
    positional arguments:
 
161
      NAME=VALUE            Set each NAME to VALUE in the string environment
 
162
    
 
163
    optional arguments:
 
164
      -h, --help            show this help message and exit
 
165
      --hash HASH           job hash to match
 
166
      --warmup              Return immediately, only useful when used with
 
167
                            pkexec(1)
 
168
      --via LOCAL-JOB-HASH  Local job hash to use to match the generated job
 
169
 
 
170
.. note::
 
171
 
 
172
    Check all job hashes with ``plainbox special -J``
 
173
 
 
174
As stated in the polkit chapter, only a trusted subset of the environment mapping
 
175
will be set using :py:func:`os.execve` to run the command.
 
176
Only the variables defined in the job environ property are allowed to avoid
 
177
compromising the root environment.
 
178
Needed modifications like adding ``CHECKBOX_SHARE`` and new paths to scripts are
 
179
managed by the checkbox-trusted-launcher.
 
180
 
 
181
Authentication on PlainBox startup
 
182
----------------------------------
 
183
 
 
184
To avoid prompting the password at the first test requiring privileges, :term:`PlainBox`
 
185
will call the ``checkbox-trusted-launcher`` with the ``--warmup`` option.
 
186
It's like a NOOP and it will return immediately, but thanks to the installed policy file
 
187
the authentication will be kept.
 
188
 
 
189
.. note::
 
190
 
 
191
    When running the development version from a branch, the usual polkit
 
192
    authentication agent will pop up to ask the password each and every time.
 
193
    This is the only difference.
 
194
 
 
195
Special case of jobs using the CheckBox local plugin
 
196
----------------------------------------------------
 
197
 
 
198
For jobs generated from :ref:`local <local>` jobs (e.g. disk/read_performance.*)
 
199
the trusted launcher is started with ``--via`` meaning that we have to first
 
200
eval a local job to find a hash match.
 
201
Once a match is found, the job command is executed using :py:func:`os.execve`.
 
202
 
 
203
.. code-block:: bash
 
204
 
 
205
    $ pkexec checkbox-trusted-launcher --hash JOB-HASH --via LOCAL-JOB-HASH
 
206
 
 
207
.. note::
 
208
 
 
209
    it will obviously fail if any local job can ever generate another local job.