diff mbox

[XEN,v8,28/29] tools/libs/*: Introduce APIs to restrict handles to a specific domain.

Message ID 1452864188-2417-29-git-send-email-ian.campbell@citrix.com (mailing list archive)
State New, archived
Headers show

Commit Message

Ian Campbell Jan. 15, 2016, 1:23 p.m. UTC
These are intended to allow user space processes (in particular QEMU)
to lock down all the handles at start of day and then drop the
privileges which would allow them to open any new unrestricted handles
(e.g. setuid or similar). This will reduce the privileges which taking
over such a process would gain an attacker wrt other domains in the
system.

These are currently unimplemented on all platforms, however the API
semantics are defined as the basis for discussion, and so that
consumers can rely on this interface always having been present rather
than requiring compile time API checks.

It is expected that these will be implemented by adding new ioctl
calls on the underlying driver and that the restrictions will be
enforced at the kernel interface layer (most likely by the kernel
itself).

For evtchn, foreignmemory, gnttab and gntshr this is hopefully
reasonably straightforward.

For call it is not so clear cut. Clearly the kernel cannot enforce
these restrictions for hypercalls which are not stable (domctl et al)
so they can never be on the whitelist. It may also be that potential
users would like to restrict the handle further than just a given
target domain, i.e. to a specific set of functionality (e.g. "things a
device model might reasonably do"). I think we will also need some way
to discover whether a given set of interfaces is available to a
restricted handle, in order to support the addition of new
functionality.

Notes:

- On many (all?) platforms libxencall and libxenforeignmemory are
  implemented by the same underlying privcmd driver. The platform
  level ioctl interface should support restricting the handle to only
  one or the other.
- On platforms with multiple privilege mapping ioctl variants should
  consider only allowing the newest/currently preferred one on a
  restricted handle. e.g. on Linux this would allow
  IOCTL_PRIVCMD_MMAPBATCH_V2 but not IOCTL_PRIVCMD_MMAPBATCH. (Of
  course any subsequently introduced _V3 would be subject to
  compatibility concerns)

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
---
v8: New

This applies on top of the Xen portion of "Begin to disentangle
libxenctrl and provide some stable libraries", v7, plus a couple of
minor fixes which will be in v8. All of this can be found in the
"vwip" branch of the tree referenced by that series at
git://xenbits.xen.org/people/ianc/libxenctrl-split/xen.git.
---
 tools/libs/call/core.c                             |  7 +++
 tools/libs/call/include/xencall.h                  | 34 ++++++++++++++
 tools/libs/call/libxencall.map                     |  2 +
 tools/libs/evtchn/core.c                           |  7 +++
 tools/libs/evtchn/include/xenevtchn.h              | 36 +++++++++++++++
 tools/libs/evtchn/libxenevtchn.map                 |  2 +
 tools/libs/foreignmemory/core.c                    |  7 +++
 .../libs/foreignmemory/include/xenforeignmemory.h  | 22 +++++++++
 tools/libs/foreignmemory/libxenforeignmemory.map   |  3 ++
 tools/libs/gnttab/gntshr_core.c                    |  8 ++++
 tools/libs/gnttab/gnttab_core.c                    |  7 +++
 tools/libs/gnttab/include/xengnttab.h              | 52 ++++++++++++++++++++++
 tools/libs/gnttab/libxengnttab.map                 |  8 +++-
 13 files changed, 193 insertions(+), 2 deletions(-)

Comments

Wei Liu Jan. 19, 2016, 1:24 p.m. UTC | #1
On Fri, Jan 15, 2016 at 01:23:07PM +0000, Ian Campbell wrote:
> These are intended to allow user space processes (in particular QEMU)
> to lock down all the handles at start of day and then drop the
> privileges which would allow them to open any new unrestricted handles
> (e.g. setuid or similar). This will reduce the privileges which taking
> over such a process would gain an attacker wrt other domains in the
> system.
> 
> These are currently unimplemented on all platforms, however the API
> semantics are defined as the basis for discussion, and so that
> consumers can rely on this interface always having been present rather
> than requiring compile time API checks.
> 
> It is expected that these will be implemented by adding new ioctl
> calls on the underlying driver and that the restrictions will be
> enforced at the kernel interface layer (most likely by the kernel
> itself).
> 
> For evtchn, foreignmemory, gnttab and gntshr this is hopefully
> reasonably straightforward.
> 
> For call it is not so clear cut. Clearly the kernel cannot enforce
> these restrictions for hypercalls which are not stable (domctl et al)
> so they can never be on the whitelist. It may also be that potential
> users would like to restrict the handle further than just a given
> target domain, i.e. to a specific set of functionality (e.g. "things a
> device model might reasonably do"). I think we will also need some way
> to discover whether a given set of interfaces is available to a
> restricted handle, in order to support the addition of new
> functionality.
> 
> Notes:
> 
> - On many (all?) platforms libxencall and libxenforeignmemory are
>   implemented by the same underlying privcmd driver. The platform
>   level ioctl interface should support restricting the handle to only
>   one or the other.

IIRC mini-os doesn't have ioctl. That would require some special
handling -- if we want to use the new API in qemu-trad, too.
We shall cross the bridge when we get there.

> - On platforms with multiple privilege mapping ioctl variants should
>   consider only allowing the newest/currently preferred one on a
>   restricted handle. e.g. on Linux this would allow
>   IOCTL_PRIVCMD_MMAPBATCH_V2 but not IOCTL_PRIVCMD_MMAPBATCH. (Of
>   course any subsequently introduced _V3 would be subject to
>   compatibility concerns)
> 
> Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
[...]
>  /*
> + * Attempt to restrict the given xcall handle to only be able to
> + * target the given domain.
> + *
> + * On success returns 0, after which only hypercalls which are on a
> + * platform specific whitelist can be called and the arguments will be
> + * audited by the platform to ensure that the target domain is
> + * domid.
> + *
> + * Subsequent attempts to call any hypercall not on the platform
> + * specific whitelist will return -1 setting errno to ENOSYS.
> + *
> + * Subsequent attempts to call any hypercall on the platform specific
> + * whitelist with any other target domain return -1 setting errno to
> + * EPERM.
> + *
> + * These restrictions will be implemented by the platform in a way
> + * which cannot be circumvented by a userspace process. Further
> + * privilege drops (such as using setuid(2) etc) may also be required
> + * to prevent a compromised process from simply opening a second
> + * handle
> + *
> + * XXX which hypercalls are restricted, per platform list, do we need
> + * a way to probe? Do we want to be able to restrict to particular
> + * subsets of whitelisted hypercalls?
> + *

TBH given the semantics of this call is not yet clear I don't think we
should rush committing this interface.

Wei.
Ian Campbell Jan. 19, 2016, 1:44 p.m. UTC | #2
On Tue, 2016-01-19 at 13:24 +0000, Wei Liu wrote:
> On Fri, Jan 15, 2016 at 01:23:07PM +0000, Ian Campbell wrote:
> > These are intended to allow user space processes (in particular QEMU)
> > to lock down all the handles at start of day and then drop the
> > privileges which would allow them to open any new unrestricted handles
> > (e.g. setuid or similar). This will reduce the privileges which taking
> > over such a process would gain an attacker wrt other domains in the
> > system.
> > 
> > These are currently unimplemented on all platforms, however the API
> > semantics are defined as the basis for discussion, and so that
> > consumers can rely on this interface always having been present rather
> > than requiring compile time API checks.
> > 
> > It is expected that these will be implemented by adding new ioctl
> > calls on the underlying driver and that the restrictions will be
> > enforced at the kernel interface layer (most likely by the kernel
> > itself).
> > 
> > For evtchn, foreignmemory, gnttab and gntshr this is hopefully
> > reasonably straightforward.
> > 
> > For call it is not so clear cut. Clearly the kernel cannot enforce
> > these restrictions for hypercalls which are not stable (domctl et al)
> > so they can never be on the whitelist. It may also be that potential
> > users would like to restrict the handle further than just a given
> > target domain, i.e. to a specific set of functionality (e.g. "things a
> > device model might reasonably do"). I think we will also need some way
> > to discover whether a given set of interfaces is available to a
> > restricted handle, in order to support the addition of new
> > functionality.
> > 
> > Notes:
> > 
> > - On many (all?) platforms libxencall and libxenforeignmemory are
> >   implemented by the same underlying privcmd driver. The platform
> >   level ioctl interface should support restricting the handle to only
> >   one or the other.
> 
> IIRC mini-os doesn't have ioctl. That would require some special
> handling

The actual implementation of this functionality would be OS specific and
therefore need to be in $os.c, where mini-os.c is under no obligation to
use an ioctl if it doesn't want to.

The only reason it is done in the common code here is to avoid adding a
dozen stubs prior to even one OS actually implementing this. I could add a
norestrict.c to each lib, put the stub there and link it on all platforms,
that would reduce the churn when someone comes to add the actual
functionality.

>  -- if we want to use the new API in qemu-trad, too.
> We shall cross the bridge when we get there.
> 
> > - On platforms with multiple privilege mapping ioctl variants should
> >   consider only allowing the newest/currently preferred one on a
> >   restricted handle. e.g. on Linux this would allow
> >   IOCTL_PRIVCMD_MMAPBATCH_V2 but not IOCTL_PRIVCMD_MMAPBATCH. (Of
> >   course any subsequently introduced _V3 would be subject to
> >   compatibility concerns)
> > 
> > Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
> [...]
> >  /*
> > + * Attempt to restrict the given xcall handle to only be able to
> > + * target the given domain.
> > + *
> > + * On success returns 0, after which only hypercalls which are on a
> > + * platform specific whitelist can be called and the arguments will be
> > + * audited by the platform to ensure that the target domain is
> > + * domid.
> > + *
> > + * Subsequent attempts to call any hypercall not on the platform
> > + * specific whitelist will return -1 setting errno to ENOSYS.
> > + *
> > + * Subsequent attempts to call any hypercall on the platform specific
> > + * whitelist with any other target domain return -1 setting errno to
> > + * EPERM.
> > + *
> > + * These restrictions will be implemented by the platform in a way
> > + * which cannot be circumvented by a userspace process. Further
> > + * privilege drops (such as using setuid(2) etc) may also be required
> > + * to prevent a compromised process from simply opening a second
> > + * handle
> > + *
> > + * XXX which hypercalls are restricted, per platform list, do we need
> > + * a way to probe? Do we want to be able to restrict to particular
> > + * subsets of whitelisted hypercalls?
> > + *
> 
> TBH given the semantics of this call is not yet clear I don't think we
> should rush committing this interface.

The intention was to try and get enough confidence that we could include
the call in the initial implementation such that applications could
unconditionally use it in the future.

If we can't manage a sufficient level of confidence in the proposed
interface then we should skip it for now of course.

Ian.
Wei Liu Jan. 19, 2016, 2:30 p.m. UTC | #3
On Tue, Jan 19, 2016 at 01:44:53PM +0000, Ian Campbell wrote:
> On Tue, 2016-01-19 at 13:24 +0000, Wei Liu wrote:
> > On Fri, Jan 15, 2016 at 01:23:07PM +0000, Ian Campbell wrote:
> > > These are intended to allow user space processes (in particular QEMU)
> > > to lock down all the handles at start of day and then drop the
> > > privileges which would allow them to open any new unrestricted handles
> > > (e.g. setuid or similar). This will reduce the privileges which taking
> > > over such a process would gain an attacker wrt other domains in the
> > > system.
> > > 
> > > These are currently unimplemented on all platforms, however the API
> > > semantics are defined as the basis for discussion, and so that
> > > consumers can rely on this interface always having been present rather
> > > than requiring compile time API checks.
> > > 
> > > It is expected that these will be implemented by adding new ioctl
> > > calls on the underlying driver and that the restrictions will be
> > > enforced at the kernel interface layer (most likely by the kernel
> > > itself).
> > > 
> > > For evtchn, foreignmemory, gnttab and gntshr this is hopefully
> > > reasonably straightforward.
> > > 
> > > For call it is not so clear cut. Clearly the kernel cannot enforce
> > > these restrictions for hypercalls which are not stable (domctl et al)
> > > so they can never be on the whitelist. It may also be that potential
> > > users would like to restrict the handle further than just a given
> > > target domain, i.e. to a specific set of functionality (e.g. "things a
> > > device model might reasonably do"). I think we will also need some way
> > > to discover whether a given set of interfaces is available to a
> > > restricted handle, in order to support the addition of new
> > > functionality.
> > > 
> > > Notes:
> > > 
> > > - On many (all?) platforms libxencall and libxenforeignmemory are
> > >   implemented by the same underlying privcmd driver. The platform
> > >   level ioctl interface should support restricting the handle to only
> > >   one or the other.
> > 
> > IIRC mini-os doesn't have ioctl. That would require some special
> > handling
> 
> The actual implementation of this functionality would be OS specific and
> therefore need to be in $os.c, where mini-os.c is under no obligation to
> use an ioctl if it doesn't want to.
> 
> The only reason it is done in the common code here is to avoid adding a
> dozen stubs prior to even one OS actually implementing this. I could add a
> norestrict.c to each lib, put the stub there and link it on all platforms,
> that would reduce the churn when someone comes to add the actual
> functionality.
> 

I don't think you need to do that. Doing this in common code is fine by
me.

> >  -- if we want to use the new API in qemu-trad, too.
> > We shall cross the bridge when we get there.
> > 
> > > - On platforms with multiple privilege mapping ioctl variants should
> > >   consider only allowing the newest/currently preferred one on a
> > >   restricted handle. e.g. on Linux this would allow
> > >   IOCTL_PRIVCMD_MMAPBATCH_V2 but not IOCTL_PRIVCMD_MMAPBATCH. (Of
> > >   course any subsequently introduced _V3 would be subject to
> > >   compatibility concerns)
> > > 
> > > Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
> > [...]
> > >  /*
> > > + * Attempt to restrict the given xcall handle to only be able to
> > > + * target the given domain.
> > > + *
> > > + * On success returns 0, after which only hypercalls which are on a
> > > + * platform specific whitelist can be called and the arguments will be
> > > + * audited by the platform to ensure that the target domain is
> > > + * domid.
> > > + *
> > > + * Subsequent attempts to call any hypercall not on the platform
> > > + * specific whitelist will return -1 setting errno to ENOSYS.
> > > + *
> > > + * Subsequent attempts to call any hypercall on the platform specific
> > > + * whitelist with any other target domain return -1 setting errno to
> > > + * EPERM.
> > > + *
> > > + * These restrictions will be implemented by the platform in a way
> > > + * which cannot be circumvented by a userspace process. Further
> > > + * privilege drops (such as using setuid(2) etc) may also be required
> > > + * to prevent a compromised process from simply opening a second
> > > + * handle
> > > + *
> > > + * XXX which hypercalls are restricted, per platform list, do we need
> > > + * a way to probe? Do we want to be able to restrict to particular
> > > + * subsets of whitelisted hypercalls?
> > > + *
> > 
> > TBH given the semantics of this call is not yet clear I don't think we
> > should rush committing this interface.
> 
> The intention was to try and get enough confidence that we could include
> the call in the initial implementation such that applications could
> unconditionally use it in the future.
> 
> If we can't manage a sufficient level of confidence in the proposed
> interface then we should skip it for now of course.
> 

Let's see what other people think about this particular function.

Wei.

> Ian.
diff mbox

Patch

diff --git a/tools/libs/call/core.c b/tools/libs/call/core.c
index bbf88de..07283da 100644
--- a/tools/libs/call/core.c
+++ b/tools/libs/call/core.c
@@ -14,6 +14,7 @@ 
  */
 
 #include <stdlib.h>
+#include <errno.h>
 
 #include "private.h"
 
@@ -70,6 +71,12 @@  int xencall_close(xencall_handle *xcall)
     return rc;
 }
 
+int xencall_restrict_target(xencall_handle *xcall, uint32_t domid)
+{
+    errno = ENOSYS;
+    return -1;
+}
+
 int xencall0(xencall_handle *xcall, unsigned int op)
 {
     privcmd_hypercall_t call = {
diff --git a/tools/libs/call/include/xencall.h b/tools/libs/call/include/xencall.h
index 559624a..47c394d 100644
--- a/tools/libs/call/include/xencall.h
+++ b/tools/libs/call/include/xencall.h
@@ -73,6 +73,40 @@  xencall_handle *xencall_open(xentoollog_logger *logger, unsigned open_flags);
 int xencall_close(xencall_handle *xcall);
 
 /*
+ * Attempt to restrict the given xcall handle to only be able to
+ * target the given domain.
+ *
+ * On success returns 0, after which only hypercalls which are on a
+ * platform specific whitelist can be called and the arguments will be
+ * audited by the platform to ensure that the target domain is
+ * domid.
+ *
+ * Subsequent attempts to call any hypercall not on the platform
+ * specific whitelist will return -1 setting errno to ENOSYS.
+ *
+ * Subsequent attempts to call any hypercall on the platform specific
+ * whitelist with any other target domain return -1 setting errno to
+ * EPERM.
+ *
+ * These restrictions will be implemented by the platform in a way
+ * which cannot be circumvented by a userspace process. Further
+ * privilege drops (such as using setuid(2) etc) may also be required
+ * to prevent a compromised process from simply opening a second
+ * handle
+ *
+ * XXX which hypercalls are restricted, per platform list, do we need
+ * a way to probe? Do we want to be able to restrict to particular
+ * subsets of whitelisted hypercalls?
+ *
+ * On failure returns -1 and sets errno:
+ *   ENOSYS: The platform is not able to support restricting the
+ *           target domain.
+ *   Other: The platform should be able to support restricting the
+ *          target domain, but was unable to do so.
+ */
+int xencall_restrict_target(xencall_handle *xcall, uint32_t domid);
+
+/*
  * Call hypercalls with varying numbers of arguments.
  *
  * On success the return value of the hypercall is the return value of
diff --git a/tools/libs/call/libxencall.map b/tools/libs/call/libxencall.map
index 2f96144..d39f88e 100644
--- a/tools/libs/call/libxencall.map
+++ b/tools/libs/call/libxencall.map
@@ -3,6 +3,8 @@  VERS_1.0 {
 		xencall_open;
 		xencall_close;
 
+		xencall_restrict_target;
+
 		xencall0;
 		xencall1;
 		xencall2;
diff --git a/tools/libs/evtchn/core.c b/tools/libs/evtchn/core.c
index c31e08c..5f68f52 100644
--- a/tools/libs/evtchn/core.c
+++ b/tools/libs/evtchn/core.c
@@ -15,6 +15,7 @@ 
 
 #include <unistd.h>
 #include <stdlib.h>
+#include <errno.h>
 
 #include "private.h"
 
@@ -61,6 +62,12 @@  int xenevtchn_close(xenevtchn_handle *xce)
     return rc;
 }
 
+int xenevtchn_restrict_target(xenevtchn_handle *xce, uint32_t domid)
+{
+    errno = ENOSYS;
+    return -1;
+}
+
 /*
  * Local variables:
  * mode: C
diff --git a/tools/libs/evtchn/include/xenevtchn.h b/tools/libs/evtchn/include/xenevtchn.h
index 4d26161..d67a4e4 100644
--- a/tools/libs/evtchn/include/xenevtchn.h
+++ b/tools/libs/evtchn/include/xenevtchn.h
@@ -74,6 +74,42 @@  xenevtchn_handle *xenevtchn_open(xentoollog_logger *logger, unsigned open_flags)
 int xenevtchn_close(xenevtchn_handle *xce);
 
 /*
+ * Attempt to restrict the given evtchn handle to only operate on the
+ * given domain.
+ *
+ * On success returns 0, after which:
+ *
+ * - Any operations which take a peer domain as an argument can only
+ *   be called with the specified target domain. Subsequent attempts
+ *   to call any such interface with another domain will return -1
+ *   setting errno to EPERM.
+ *
+ * - Any operations which take an evtchn_port_t are not restricted
+ *   other than by the requirement to have previously bound that
+ *   evtchn to the handle. Therefore users of the restrict interface
+ *   should take care not to bind any event channels relating to other
+ *   domains prior to enforcing the restriction. The restrictions on
+ *   xenevtchn_bind_*() (which take a domain id, see previous point)
+ *   suffice to prevent any new such bindings being created.
+ *
+ * - xenevtchn_bind_virq is not permitted and will return -1 setting
+ *   errno to EPERM.
+ *
+ * These restrictions will be implemented by the platform in a way
+ * which cannot be circumvented by a userspace process. Further
+ * privilege drops (such as using setuid(2) etc) may also be required
+ * to prevent a compromised process from simply opening a second
+ * handle
+ *
+ * On failure returns -1 and sets errno:
+ *   ENOSYS: The platform is not able to support restricting the
+ *           target domain.
+ *   Other: The platform should be able to support restricting the
+ *          target domain, but was unable to do so.
+ */
+int xenevtchn_restrict_target(xenevtchn_handle *xce, uint32_t domid);
+
+/*
  * Return an fd that can be select()ed on.
  *
  * Note that due to bugs, setting this fd to non blocking may not
diff --git a/tools/libs/evtchn/libxenevtchn.map b/tools/libs/evtchn/libxenevtchn.map
index 625a1e2..08e9dd5 100644
--- a/tools/libs/evtchn/libxenevtchn.map
+++ b/tools/libs/evtchn/libxenevtchn.map
@@ -3,6 +3,8 @@  VERS_1.0 {
 		xenevtchn_open;
 		xenevtchn_close;
 
+		xenevtchn_restrict_target;
+
 		xenevtchn_fd;
 
 		xenevtchn_bind_unbound_port;
diff --git a/tools/libs/foreignmemory/core.c b/tools/libs/foreignmemory/core.c
index cfb0a73..73e8034 100644
--- a/tools/libs/foreignmemory/core.c
+++ b/tools/libs/foreignmemory/core.c
@@ -62,6 +62,13 @@  int xenforeignmemory_close(xenforeignmemory_handle *fmem)
     return rc;
 }
 
+int xenforeignmemory_restrict_target(xenforeignmemory_handle *fmem,
+                                     uint32_t domid)
+{
+    errno = ENOSYS;
+    return -1;
+}
+
 void *xenforeignmemory_map(xenforeignmemory_handle *fmem,
                            uint32_t dom, int prot,
                            size_t num,
diff --git a/tools/libs/foreignmemory/include/xenforeignmemory.h b/tools/libs/foreignmemory/include/xenforeignmemory.h
index 3724c63..350ca75 100644
--- a/tools/libs/foreignmemory/include/xenforeignmemory.h
+++ b/tools/libs/foreignmemory/include/xenforeignmemory.h
@@ -74,6 +74,28 @@  xenforeignmemory_handle *xenforeignmemory_open(xentoollog_logger *logger,
 int xenforeignmemory_close(xenforeignmemory_handle *fmem);
 
 /*
+ * Attempt to restrict the given handle to only target the given
+ * domain.
+ *
+ * On success returns 0, after which calls to xenforeignmemory_map
+ * which pass a domain other than the given domain will return -1
+ * setting errno to EPERM.
+ *
+ * This restriction will be implemented by the platform in a way which
+ * cannot be circumvented by a userspace process. Further privilege
+ * drops (such as using setuid(2) etc) may also be required to prevent
+ * a compromised process from simply opening a second handle
+ *
+ * On failure returns -1 and sets errno:
+ *   ENOSYS: The platform is not able to support restricting the
+ *           target domain.
+ *   Other: The platform should be able to support restricting the
+ *          target domain, but was unable to do so.
+ */
+int xenforeignmemory_restrict_target(xenforeignmemory_handle *fmem,
+                                     uint32_t domid);
+
+/*
  * Maps a range within one domain to a local address range.  Mappings
  * must be unmapped with xenforeignmemory_unmap and should follow the
  * same rules as mmap regarding page alignment.
diff --git a/tools/libs/foreignmemory/libxenforeignmemory.map b/tools/libs/foreignmemory/libxenforeignmemory.map
index df206b3..dc1e0a1 100644
--- a/tools/libs/foreignmemory/libxenforeignmemory.map
+++ b/tools/libs/foreignmemory/libxenforeignmemory.map
@@ -2,6 +2,9 @@  VERS_1.0 {
 	global:
 		xenforeignmemory_open;
 		xenforeignmemory_close;
+
+		xenforeignmemory_restrict_target;
+
 		xenforeignmemory_map;
 		xenforeignmemory_unmap;
 	local: *; /* Do not expose anything by default */
diff --git a/tools/libs/gnttab/gntshr_core.c b/tools/libs/gnttab/gntshr_core.c
index 7f6bf9d..0347a16 100644
--- a/tools/libs/gnttab/gntshr_core.c
+++ b/tools/libs/gnttab/gntshr_core.c
@@ -19,6 +19,7 @@ 
  */
 
 #include <stdlib.h>
+#include <errno.h>
 
 #include "private.h"
 
@@ -64,6 +65,13 @@  int xengntshr_close(xengntshr_handle *xgs)
     free(xgs);
     return rc;
 }
+
+int xengntshr_restrict_target(xengntshr_handle *xgs, uint32_t domid)
+{
+    errno = ENOSYS;
+    return -1;
+}
+
 void *xengntshr_share_pages(xengntshr_handle *xcg, uint32_t domid,
                             int count, uint32_t *refs, int writable)
 {
diff --git a/tools/libs/gnttab/gnttab_core.c b/tools/libs/gnttab/gnttab_core.c
index 5d0474d..77ce1670 100644
--- a/tools/libs/gnttab/gnttab_core.c
+++ b/tools/libs/gnttab/gnttab_core.c
@@ -19,6 +19,7 @@ 
  */
 
 #include <stdlib.h>
+#include <errno.h>
 
 #include "private.h"
 
@@ -65,6 +66,12 @@  int xengnttab_close(xengnttab_handle *xgt)
     return rc;
 }
 
+int xengnttab_restrict_target(xengnttab_handle *xgt, uint32_t domid)
+{
+    errno = ENOSYS;
+    return -1;
+}
+
 int xengnttab_set_max_grants(xengnttab_handle *xgt, uint32_t count)
 {
     return osdep_gnttab_set_max_grants(xgt, count);
diff --git a/tools/libs/gnttab/include/xengnttab.h b/tools/libs/gnttab/include/xengnttab.h
index 7bf8462..8d0d26c 100644
--- a/tools/libs/gnttab/include/xengnttab.h
+++ b/tools/libs/gnttab/include/xengnttab.h
@@ -148,6 +148,33 @@  xengnttab_handle *xengnttab_open(xentoollog_logger *logger, unsigned open_flags)
  */
 int xengnttab_close(xengnttab_handle *xgt);
 
+/*
+ * Attempt to restrict the given handle to only target the given
+ * domain.
+ *
+ * On success returns 0, after which:
+ *
+ * - Calls to xengnttab_map_*() which are passed a domain other than
+ *   the given domain (either as an argument or as any member of a
+ *   domid array argument, regardless of the validity of other members
+ *   of the array) will return -1 setting errno to EPERM.
+ *
+ * - Calls to xengnttab_set_max_grants() will return -1 having set
+ *   errno to EPERM.
+ *
+ * This restriction will be implemented by the platform in a way which
+ * cannot be circumvented by a userspace process. Further privilege
+ * drops (such as using setuid(2) etc) may also be required to prevent
+ * a compromised process from simply opening a second handle
+ *
+ * On failure returns -1 and sets errno:
+ *   ENOSYS: The platform is not able to support restricting the
+ *           target domain.
+ *   Other: The platform should be able to support restricting the
+ *          target domain, but was unable to do so.
+ */
+int xengnttab_restrict_target(xengnttab_handle *xgt, uint32_t domid);
+
 /**
  * Memory maps a grant reference from one domain to a local address range.
  * Mappings should be unmapped with xengnttab_unmap.  Logs errors.
@@ -305,6 +332,31 @@  xengntshr_handle *xengntshr_open(xentoollog_logger *logger,
  */
 int xengntshr_close(xengntshr_handle *xgs);
 
+/*
+ * Attempt to restrict the given handle to only target the given
+ * domain.
+ *
+ * On success returns 0, after which:
+ *
+ * - Calls to xengntshr_share_*() which are passed a domain other than
+ *   the given domain will return -1 setting errno to EPERM.
+ *
+ * - Calls to xengnttab_set_max_grants() will return -1 having set
+ *   errno to EPERM.
+ *
+ * This restriction will be implemented by the platform in a way which
+ * cannot be circumvented by a userspace process. Further privilege
+ * drops (such as using setuid(2) etc) may also be required to prevent
+ * a compromised process from simply opening a second handle
+ *
+ * On failure returns -1 and sets errno:
+ *   ENOSYS: The platform is not able to support restricting the
+ *           target domain.
+ *   Other: The platform should be able to support restricting the
+ *          target domain, but was unable to do so.
+ */
+int xengntshr_restrict_target(xengntshr_handle *xgs, uint32_t domid);
+
 /**
  * Allocates and shares pages with another domain.
  *
diff --git a/tools/libs/gnttab/libxengnttab.map b/tools/libs/gnttab/libxengnttab.map
index 66e8c12..c3d7d49 100644
--- a/tools/libs/gnttab/libxengnttab.map
+++ b/tools/libs/gnttab/libxengnttab.map
@@ -3,6 +3,8 @@  VERS_1.0 {
 		xengnttab_open;
 		xengnttab_close;
 
+		xengnttab_restrict_target;
+
 		xengnttab_set_max_grants;
 
 		xengnttab_map_domain_grant_refs;
@@ -11,10 +13,12 @@  VERS_1.0 {
 		xengnttab_map_grant_refs;
 
 		xengnttab_unmap;
-		
+
 		xengntshr_open;
 		xengntshr_close;
-		
+
+		xengntshr_restrict_target;
+
 		xengntshr_share_page_notify;
 		xengntshr_share_pages;