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