1 /*
2  * xentoolcore.h
3  *
4  * Copyright (c) 2017 Citrix
5  *
6  * Common features used/provided by all Xen tools libraries
7  *
8  * This library is free software; you can redistribute it and/or
9  * modify it under the terms of the GNU Lesser General Public
10  * License as published by the Free Software Foundation;
11  * version 2.1 of the License.
12  *
13  * This library is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
16  * Lesser General Public License for more details.
17  *
18  * You should have received a copy of the GNU Lesser General Public
19  * License along with this library; If not, see <http://www.gnu.org/licenses/>.
20  */
21 
22 #ifndef XENTOOLCORE_H
23 #define XENTOOLCORE_H
24 
25 #include <stdint.h>
26 #include <xen/xen.h>
27 
28 /*
29  * int xentoolcore_restrict_all(domid_t domid);
30  *
31  * Arranges that Xen library handles (fds etc.) which are currently held
32  * by Xen libraries, can no longer be used other than to affect domid.
33  *
34  * Does not prevent effects that amount only to
35  *   - denial of service, possibly host-wide, by resource exhaustion etc.
36  *
37  * If this cannot be achieved, returns -1 and sets errno.
38  * If called again with the same domid, it may succeed, or it may
39  * fail (even though such a call is potentially meaningful).
40  * (If called again with a different domid, it will necessarily fail.)
41  *
42  * Note for multi-threaded programs: If xentoolcore_restrict_all is
43  * called concurrently with a function which /or closes Xen library
44  * handles (e.g.  libxl_ctx_free, xs_close), the restriction is only
45  * guaranteed to be effective after all of the closing functions have
46  * returned, even if that is later than the return from
47  * xentoolcore_restrict_all.  (Of course if xentoolcore_restrict_all
48  * it is called concurrently with opening functions, the new handles
49  * might or might not be restricted.)
50  *
51  *  ====================================================================
52  *  IMPORTANT - IMPLEMENTATION STATUS
53  *
54  *  This function has been implemented insofar as it appears necessary
55  *  for the purposes of running a deprivileged qemu, and is believed to
56  *  be sufficient (subject to the caveats discussed in the appropriate
57  *  libxl documentation for this feature).
58  *
59  *  However, this function is NOT implemented for all Xen libraries.
60  *  For each use case of this function, the designer must evaluate and
61  *  audit whether the implementation is sufficient in their specific
62  *  context.
63  *
64  *  Of course, patches to extend the implementation are very welcome.
65  *  ====================================================================
66  *
67  * Thread safe.
68  *
69  * We expect that no callers do the following:
70  *   - in one thread call xen_somelibrary_open|close
71  *   - in another thread call fork
72  *   - in the child of the fork, before exec, call
73  *     xen_some[other]library_open|close or xentoolcore_restrict_all
74  *
75  */
76 int xentoolcore_restrict_all(domid_t domid);
77 
78 #endif /* XENTOOLCORE_H */
79 
80 /*
81  * Local variables:
82  * mode: C
83  * c-file-style: "BSD"
84  * c-basic-offset: 4
85  * tab-width: 4
86  * indent-tabs-mode: nil
87  * End:
88  */
89