[//]: # ([[meta copyright="Copyright © 2007, 2008, 2010, 2011, 2013 Free Software Foundation, Inc."]])

[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
id="license" text="Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no Invariant
Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
is included in the section entitled [[GNU Free Documentation
License|/fdl]]."]]"""]]

[[!meta title="Capability"]]

A capability is a protected reference.  It is a reference in that
it designates an object; it is protected in that in cannot be
forged.  A capability both designates the object it refers to and
carries the authority to manipulate it.

By binding [[designation]] and [[authorization]] together, capabilities
simplify [[delegation]].  Imagine that program instance A wants to
tell program B to use a particular file to store some data.
Further imagine that A and B are running in different [[trust_domains]]
(e.g., with different UIDs).  If A sends B just the name
of the file, B needs to first ensure that he does not accidentally
enable A to access the file on his own authority.  That is, B wants
to protect against A hijacking his authority.  (This problem is
refused to the [[confused_deputy]] problem.)  Also, since A likely
sent a string to identify the file to B, the identifier lacks a
[[naming_context]] and therefore may resolve to a different object
than A intended.  By ensuring that [[designation]] and [[authorization]] are
always bound together, these problems are avoided.

If you found the above example a little too abstract, then consider the example
found on the [[wikipedia|https://en.wikipedia.org/wiki/Confused_deputy_problem]]
page.  Suppose a trusted server runs a compilation process, bills clients for
using the service, and stores billing information in the "bills.txt" file. The
compilation server needs clients to provide the name of the input and output
files to compile the program.  Suppose a client calls the compilation server
and specifies the output file as the "billing.txt" file.  The server compiles
the program, and then overwrites the billing information.  Now the server does
not know who to bill for the use of its services.

Capability-based system architectures strive to meet the *principle of least
privilege* ({{$wikipedia_polp}}).

[[!tag open_issue_documentation]] <!--
Revoking capabilities: destroy Mach port, invalidates *all* send rights.  See
shapiro_capintro_1999.  To be more fine-grained, need separate instances, for
example, valet key vs. door key.  Proxy objects (that can be destroyed
individually); attenuation design pattern, membranes
(wikipedia_object-capability_model)?
-->

A capability mechanism is typically implemented in software by the operating
system kernel (typically a [[microkernel]]).  The computing cost (as compared to
a hardware implementation) is neglectable.


[[!tag open_issue_documentation]] <!--
References.  shapiro_capintro_1999 has a bit.
-->


[[!tag open_issue_documentation]] <!--
# Advantages

  * increased security; POLP

  * easy exchanging of functionality

  * support modular design and encapsulation

  * easy collaboration (in theory; need real example)

-->


# UNIX

[[UNIX file descriptors|unix/file_descriptor]] can be viewed as capabilities.
They do not survive reboot, that is, they are not [[persistent|persistency]].
To work around this, [[ACL]]s are used to recover authority.


# GNU/Hurd

In the GNU/Hurd system, a capability is represented by a [[Mach
port|microkernel/mach/port]].  As in UNIX (see above), they are not
[[persistent|persistency]].


## IRC, freenode, #hurd, 2013-07-01

    <nlightnfotis> I have read plenty of documents, and wrapped my head around most Hurd concepts, but I still have not understood well what capabilities are.
    <youpi> Mmm, which capabilities?
    <youpi> AIUI, the Hurd doesn't really have a notion of capabilites, just a notion of owning a port right
    <nlightnfotis> From what I have understood (from the critique) they reference ports so they objects can be referenced via them
    <youpi> (which provides processes a way for doing things)
    <youpi> ok, so we are talking about the same thing, I guess
    <nlightnfotis> ahh, that's cool. I thought there was more to the story that I couldn't understand


# Further Reading
* [[Mach port|microkernel/mach/port]]
* {{$wikipedia_capability-based_security}}
* {{$wikipedia_object-capability_model}}
* {{$wikipedia_polp}}

<!-- This comment "pushes" polp into the list -->

[[!tag open_issue_documentation]] <!--
<http://www.eros-os.org/essays/wherefrom.html>,
<http://www.eros-os.org/essays/ACLSvCaps.html>,
<http://www.cap-lore.com/CapTheory/index.html>,
<http://www.cap-lore.com/CapTheory/tddCap.html>
<http://www.skyhunter.com/marcs/capabilityIntro/>
-->


[[!ymlfront data="""

shapiro_capintro_1999:

  "[What *is* a Capability,
  Anyway?](http://www.eros-os.org/essays/capintro.html), Jonathan Shapiro,
  1999"

shapiro_capintro_1999_text:

  "This is an easily readable introduction with good examples.  In the author's
  own words, the text *provides a layman's introduction to capabilities,
  describing what they are, what they do, and why they result in better
  security than today's computer systems*"

wikipedia_capability-based_security:

  "[[!wikipedia Capability-based_security desc=\"Wikipedia, capability-based
  security\"]]"

wikipedia_object-capability_model:

  "[[!wikipedia Object-capability_model desc=\"Wikipedia, object-capability
  model\"]]"

wikipedia_polp:

  "[[!wikipedia Principle_of_least_privilege desc=\"Wikipedia, principle of
  least privilege\"]]"

"""]]