diff mbox

[v3,11/11] smack: documentation for the Smack namespace

Message ID 1437732285-11524-12-git-send-email-l.pawelczyk@samsung.com (mailing list archive)
State New, archived
Headers show

Commit Message

Lukasz Pawelczyk July 24, 2015, 10:04 a.m. UTC
Adds Documentation/smack-namespace.txt.

Signed-off-by: Lukasz Pawelczyk <l.pawelczyk@samsung.com>
Reviewed-by: Casey Schaufler <casey@schaufler-ca.com>
---
 Documentation/security/00-INDEX            |   2 +
 Documentation/security/Smack-namespace.txt | 231 +++++++++++++++++++++++++++++
 MAINTAINERS                                |   1 +
 security/smack/Kconfig                     |   2 +
 4 files changed, 236 insertions(+)
 create mode 100644 Documentation/security/Smack-namespace.txt

Comments

Serge Hallyn July 29, 2015, 3:25 p.m. UTC | #1
On Fri, Jul 24, 2015 at 12:04:45PM +0200, Lukasz Pawelczyk wrote:
> +--- Design ideas ---
> +
> +"Smack namespace" is rather "Smack labels namespace" as not the whole
> +MAC is namespaced, only the labels. There is a great analogy between
> +Smack labels namespace and the user namespace part that remaps UIDs.
> +
> +The idea is to create a map of labels for a namespace so the namespace
> +is only allowed to use those labels. Smack rules are always the same
> +as in the init namespace (limited only by what labels are mapped) and
> +cannot be manipulated from the child namespace. The map is actually
> +only for labels' names. The underlying structures for labels remain
> +the same. The filesystem also stores the "unmapped" labels from the
> +init namespace.
> +
> +Let's say we have those labels in the init namespace:
> +label1
> +label2
> +label3
> +
> +and those rules:
> +label1 label2 rwx
> +label1 label3 rwx
> +label2 label3 rwx
> +
> +We create a map for a namespace:
> +label1 -> mapped1
> +label2 -> mapped2
> +
> +This means that 'label3' is completely invisible in the namespace. As if
> +it didn't exist. All the rules that include it are ignored.
> +
> +Effectively in the namespace we have only one rule:
> +mapped1 mapped2 rwx
> +
> +Which in reality is:
> +label1 label2 rwx
> +
> +All requests to access an object with a 'label3' will be denied. If it
> +ever comes to a situation where 'label3' would have to be printed
> +(e.g. reading an exec or mmap label from a file to which we have
> +access) then huh sign '?' will be printed instead.
> +
> +All the operations in the namespace on the remaining labels will have
> +to be performed using their mapped names. Things like changing own
> +process's label, changing filesystem label. Labels will also be
> +printed with their mapped names.
> +
> +You cannot import new labels in a namespace. Every operation that
> +would do so in an init namespace will return an error in the child
> +namespace. You cannot assign an unmapped or not existing label to an
> +object. You can only operate on labels that have been explicitly
> +mapped.
> +
> +
> +--- Capabilities ---
> +
> +Enabling Smack related capabilities (CAP_MAC_ADMIN and
> +CAP_MAC_OVERRIDE) is main goal of Smack namespace, so it can work
> +properly in the container. And those capabilities do work to some
> +extent. In several places where capabilities are checked compatibility
> +with Smack namespace has been introduced. Capabilities are of course
> +limited to operate only on mapped labels.
> +
> +CAP_MAC_OVERRIDE works fully, will allow you to ignore Smack access
> +rules, but only between objects that have labels mapped. So in the
> +example above having this CAP will allow e.g. label2 to write to
> +label1, but will not allow any access to label3.

(Sorry it took me this long to get to reading, and thanks for working
on this)

Oh my.  All this is not at all what I'd expected :)

Is there rationale for these decisions?  Hm, I guess it really is
following the user_ns design, but the huge difference is that the
user_ns is partitioning an already-enumerated set of kuids.  The
smack labels are inherently different.

In containers, something we'd really like to be able to do is:

Create a new container.  Just run it as label 'c1'.  Inside the
container, let the admin install mysql from a package which assigns
type 'mysqld', protecting the rest of the container from mysql.
Without the host admin doing anything.

Normally the way I think of implementing something like this would be
to allow the host to say "c1 is to be namespaceable."  Then on a userns
unshare, if the task is in c1, it gets transitioned into the ns.  Then the
container sees c1 as _ (or whatever).  It can create 'mysql' which is
actually 'c1.mysql' on the host, and it can create and override rules
to c1.*.

Also, allowing CAP_MAC_OVERRIDE in this way seems overly dangerous.
If there were rules defined by the container, then I'd expect those to
be overrideable - but not all rules pertaining to all labels mapped
into the container.  But I guess based on  your envisioned usage (where
I assume 'label1' is meant to *only* be used for that container) it
might be ok.

thanks,
-serge
--
To unsubscribe from this list: send the line "unsubscribe linux-fsdevel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Lukasz Pawelczyk July 29, 2015, 4:13 p.m. UTC | #2
Appologise for sending my previous email in HTML, this email address
was never meant to be used with lists. I resend in plain text.

On Wed, Jul 29, 2015 at 5:25 PM, Serge E. Hallyn <serge@hallyn.com> wrote:

>> +Enabling Smack related capabilities (CAP_MAC_ADMIN and
>> +CAP_MAC_OVERRIDE) is main goal of Smack namespace, so it can work
>> +properly in the container. And those capabilities do work to some
>> +extent. In several places where capabilities are checked compatibility
>> +with Smack namespace has been introduced. Capabilities are of course
>> +limited to operate only on mapped labels.
>> +
>> +CAP_MAC_OVERRIDE works fully, will allow you to ignore Smack access
>> +rules, but only between objects that have labels mapped. So in the
>> +example above having this CAP will allow e.g. label2 to write to
>> +label1, but will not allow any access to label3.
>
> (Sorry it took me this long to get to reading, and thanks for working
> on this)
>
> Oh my.  All this is not at all what I'd expected :)
>
> Is there rationale for these decisions?  Hm, I guess it really is
> following the user_ns design, but the huge difference is that the
> user_ns is partitioning an already-enumerated set of kuids.  The
> smack labels are inherently different.

There is a big rationale for this. This is not to make Smack limit how
namespace can be created (this can be done separately, no conflict
here). This is to make Smack work at all inside a namespace. Please
note that contrary to SELinux and AppArmor Smack needs CAP_MAC_ADMIN
for it to operate on a normal basis. There is no rule for changing
labels. CAP_MAC_ADMIN is always required for this. And you cannot
unlock and give this capability just like that to anyone. Like in
every namespace you need a level of abstraction to allow an
unprivileged namespace to administer something.

> In containers, something we'd really like to be able to do is:
>
> Create a new container.  Just run it as label 'c1'.  Inside the
> container, let the admin install mysql from a package which assigns
> type 'mysqld', protecting the rest of the container from mysql.
> Without the host admin doing anything.
>
> Normally the way I think of implementing something like this would be
> to allow the host to say "c1 is to be namespaceable."  Then on a userns
> unshare, if the task is in c1, it gets transitioned into the ns.  Then the
> container sees c1 as _ (or whatever).  It can create 'mysql' which is
> actually 'c1.mysql' on the host, and it can create and override rules
> to c1.*.

Few things here.
1. Such an extension with using prefixes (with two exceptions, see
below) could be added to my patches. I even planned to do so (make a
prefix for a container and assign it a group of labels, this doesn't
conflict with arbitrary mapping). But this was refused by Casey on a
basis that by Smack defintion labels have no meaning. So no prefixes.
2. (expcetion #1) Changing any rules in a container has been deemed
too insecure at this point.
3. (expcetion #2) About the: "Without the host admin doing anything.".
With this namespace you delegate part of CAP_MAC_ADMIN privilege to an
unprivileged user (as with any other namespace). There is now way that
this will not involve host admin. The way you described it you allow
an unprivileged process to change its own label and change labels on a
filesystem. This is simply against Smack rules and completely
insecure. Even with user_ns if you map several UID you need admin
intervention.
>
> Also, allowing CAP_MAC_OVERRIDE in this way seems overly dangerous.
> If there were rules defined by the container, then I'd expect those to
> be overrideable - but not all rules pertaining to all labels mapped
> into the container.  But I guess based on  your envisioned usage (where
> I assume 'label1' is meant to *only* be used for that container) it
> might be ok.

CAP_MAC_OVERRIDE is only possible for labels that the admin explicitly
mapped. So it's up to him to decide what is dangerous or not. It can
only map labels that are not used outside of the container if it
wishes to. But the user himself will not be able to explot that
without permission from the admin.

So sorry this is not what you expected, but it seems that what you
expected is simply not feasible.

> thanks,
> -serge

Thanks,
Lukasz
--
To unsubscribe from this list: send the line "unsubscribe linux-fsdevel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Lukasz Pawelczyk July 29, 2015, 4:24 p.m. UTC | #3
On Wed, Jul 29, 2015 at 6:13 PM, Lukasz Pawelczyk <havner@gmail.com> wrote:

> With this namespace you delegate part of CAP_MAC_ADMIN privilege to an
> unprivileged user (as with any other namespace).

Ok, maybe the part in the brackets is an overstatement. Mostly with
namespaces you create a full abstraction of some object and give user
priviledges to that object (e.g. uts structure, network interfaces,
with UTS and NET namespaces, etc). This is rather not possible with
Smack, as being a security module it has to retain its core security
paradigm.  It cannot be a separate LSM within a host LSM (remember the
part about changing process own label and changing any other object
label, mostly a file). So Smack namespace really as I see it has big
analogy to user namespace. You cannot abstract UIDs completely in a
namespace as those UIDs do live in a host as well. If you want to have
some capabilities over them, admin has to agree to that explicitly.

Thanks,
Lukasz
--
To unsubscribe from this list: send the line "unsubscribe linux-fsdevel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Serge Hallyn July 29, 2015, 4:37 p.m. UTC | #4
On Wed, Jul 29, 2015 at 06:13:59PM +0200, Lukasz Pawelczyk wrote:
> Appologise for sending my previous email in HTML, this email address
> was never meant to be used with lists. I resend in plain text.
> 
> On Wed, Jul 29, 2015 at 5:25 PM, Serge E. Hallyn <serge@hallyn.com> wrote:
> 
> >> +Enabling Smack related capabilities (CAP_MAC_ADMIN and
> >> +CAP_MAC_OVERRIDE) is main goal of Smack namespace, so it can work
> >> +properly in the container. And those capabilities do work to some
> >> +extent. In several places where capabilities are checked compatibility
> >> +with Smack namespace has been introduced. Capabilities are of course
> >> +limited to operate only on mapped labels.
> >> +
> >> +CAP_MAC_OVERRIDE works fully, will allow you to ignore Smack access
> >> +rules, but only between objects that have labels mapped. So in the
> >> +example above having this CAP will allow e.g. label2 to write to
> >> +label1, but will not allow any access to label3.
> >
> > (Sorry it took me this long to get to reading, and thanks for working
> > on this)
> >
> > Oh my.  All this is not at all what I'd expected :)
> >
> > Is there rationale for these decisions?  Hm, I guess it really is
> > following the user_ns design, but the huge difference is that the
> > user_ns is partitioning an already-enumerated set of kuids.  The
> > smack labels are inherently different.
> 
> There is a big rationale for this. This is not to make Smack limit how
> namespace can be created (this can be done separately, no conflict
> here). This is to make Smack work at all inside a namespace. Please
> note that contrary to SELinux and AppArmor Smack needs CAP_MAC_ADMIN
> for it to operate on a normal basis. There is no rule for changing
> labels. CAP_MAC_ADMIN is always required for this. And you cannot
> unlock and give this capability just like that to anyone. Like in
> every namespace you need a level of abstraction to allow an
> unprivileged namespace to administer something.

Hm, ok - it's been a few years since I used smack, so I'll go back
and re-read the Documentation file first, then the doc patch and
this email again.

> > In containers, something we'd really like to be able to do is:
> >
> > Create a new container.  Just run it as label 'c1'.  Inside the
> > container, let the admin install mysql from a package which assigns
> > type 'mysqld', protecting the rest of the container from mysql.
> > Without the host admin doing anything.
> >
> > Normally the way I think of implementing something like this would be
> > to allow the host to say "c1 is to be namespaceable."  Then on a userns
> > unshare, if the task is in c1, it gets transitioned into the ns.  Then the
> > container sees c1 as _ (or whatever).  It can create 'mysql' which is
> > actually 'c1.mysql' on the host, and it can create and override rules
> > to c1.*.
> 
> Few things here.
> 1. Such an extension with using prefixes (with two exceptions, see
> below) could be added to my patches. I even planned to do so (make a
> prefix for a container and assign it a group of labels, this doesn't
> conflict with arbitrary mapping). But this was refused by Casey on a
> basis that by Smack defintion labels have no meaning. So no prefixes.

Ok, I'm hoping to discuss this with Casey at LSS.  I assume there will
be reasons why what I want is simply not possible, but I'd like to give
it a shot :)

One way around this might be to let the host admin say:

create smack labels c1_a1..c1_aN.  Map them into the container in a
way such that they have no name in the container yet.

Now when container admin says "create mysql_t", so long as there is
a not-yet-named mapped label, c1-aM, it gets mapped to the new name.

One hurdle to overcome there, of course, is how to reproduce that
mapping the next time we create this container.

Anyway, if this patchset is simply about making smack work in user_ns
at all, I'll reread with that in mind :)

> 2. (expcetion #1) Changing any rules in a container has been deemed
> too insecure at this point.
> 3. (expcetion #2) About the: "Without the host admin doing anything.".
> With this namespace you delegate part of CAP_MAC_ADMIN privilege to an
> unprivileged user (as with any other namespace). There is now way that
> this will not involve host admin. The way you described it you allow
> an unprivileged process to change its own label and change labels on a
> filesystem. This is simply against Smack rules and completely
> insecure. Even with user_ns if you map several UID you need admin
> intervention.
> >
> > Also, allowing CAP_MAC_OVERRIDE in this way seems overly dangerous.
> > If there were rules defined by the container, then I'd expect those to
> > be overrideable - but not all rules pertaining to all labels mapped
> > into the container.  But I guess based on  your envisioned usage (where
> > I assume 'label1' is meant to *only* be used for that container) it
> > might be ok.
> 
> CAP_MAC_OVERRIDE is only possible for labels that the admin explicitly
> mapped. So it's up to him to decide what is dangerous or not. It can
> only map labels that are not used outside of the container if it
> wishes to. But the user himself will not be able to explot that
> without permission from the admin.
> 
> So sorry this is not what you expected, but it seems that what you
> expected is simply not feasible.

-serge
--
To unsubscribe from this list: send the line "unsubscribe linux-fsdevel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Lukasz Pawelczyk July 29, 2015, 5:05 p.m. UTC | #5
Just a clarification, from my previous email:

> 3. (expcetion #2) About the: "Without the host admin doing anything.".
> With this namespace you delegate part of CAP_MAC_ADMIN privilege to an
> unprivileged user (as with any other namespace). There is now way that
> this will not involve host admin.

What I meant is: "There is NO way that this will not involve host admin."
Typo, sorry.

On Wed, Jul 29, 2015 at 6:37 PM, Serge E. Hallyn <serge@hallyn.com> wrote:

> Ok, I'm hoping to discuss this with Casey at LSS.  I assume there will
> be reasons why what I want is simply not possible, but I'd like to give
> it a shot :)
>
> One way around this might be to let the host admin say:
>
> create smack labels c1_a1..c1_aN.  Map them into the container in a
> way such that they have no name in the container yet.
>
> Now when container admin says "create mysql_t", so long as there is
> a not-yet-named mapped label, c1-aM, it gets mapped to the new name.

This by itself like I said would theoretically be possible (without
the "no admin intervention" and "modifying rules" parts). You mark the
container prefixed with something, let's say with "C1". Now any new
label you create inside a namespace will get automatic (implicit)
mapping:

C1-label -> label

Casey disliked the idea for these reasons (there was actually more
then one as I remember now):
1. What I said previously about special meaning for labels. The real
host label C1-label has a meaning now.
2. Labels have a specific max length. By prefixing them we reduce that
length, and it is pressumed to be true in several parts of the code.
3. This mechanic allows users to import labels, and as Smack doesn't
free or reuse them this is potentially DOS surface. Granted this is
technical limitation only that could be remedied at some point, but
for now the assumption that labels are not destroyed is taken
advantage of in several parts of the code to simplify the
implementation of Smack itself. (Mappings and mapped label structures
are freed with the end of life of user namespace).

> One hurdle to overcome there, of course, is how to reproduce that
> mapping the next time we create this container.

The name of the real label would hold the info (C1-label).

> Anyway, if this patchset is simply about making smack work in user_ns
> at all, I'll reread with that in mind :)

Would appreciate.

Thanks,
Lukasz
--
To unsubscribe from this list: send the line "unsubscribe linux-fsdevel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Serge Hallyn July 30, 2015, 7:11 p.m. UTC | #6
On Wed, Jul 29, 2015 at 07:05:19PM +0200, Lukasz Pawelczyk wrote:
> > Anyway, if this patchset is simply about making smack work in user_ns
> > at all, I'll reread with that in mind :)
> 
> Would appreciate.

Ok - thanks for your patience.  I "get" it now.  Will go back to the
actual patches and review hopefully tonight and monday.

thanks,
-serge
--
To unsubscribe from this list: send the line "unsubscribe linux-fsdevel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
diff mbox

Patch

diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
index 45c82fd..c03a220 100644
--- a/Documentation/security/00-INDEX
+++ b/Documentation/security/00-INDEX
@@ -6,6 +6,8 @@  SELinux.txt
 	- how to get started with the SELinux security enhancement.
 Smack.txt
 	- documentation on the Smack Linux Security Module.
+Smack-namespace.txt
+	- documentation on the Smack namespace implementation.
 Yama.txt
 	- documentation on the Yama Linux Security Module.
 apparmor.txt
diff --git a/Documentation/security/Smack-namespace.txt b/Documentation/security/Smack-namespace.txt
new file mode 100644
index 0000000..120314d
--- /dev/null
+++ b/Documentation/security/Smack-namespace.txt
@@ -0,0 +1,231 @@ 
+
+                                      "Quis custodiet ipsos custodes?"
+                                                 - Satires of Juvenal
+
+
+--- What is a Smack namespace ---
+
+Smack namespace was developed to make it possible for Smack to work
+nicely with Linux containers where there is a full operating system
+with its own init inside the namespace. Such a system working with
+Smack expects to have at least partially working SMACK_MAC_ADMIN to be
+able to change labels of processes and files. This is required to be
+able to securely start applications under the control of Smack and
+manage their access rights.
+
+It was implemented using new LSM hooks added to the user namespace
+that were developed together with Smack namespace.
+
+
+--- Design ideas ---
+
+"Smack namespace" is rather "Smack labels namespace" as not the whole
+MAC is namespaced, only the labels. There is a great analogy between
+Smack labels namespace and the user namespace part that remaps UIDs.
+
+The idea is to create a map of labels for a namespace so the namespace
+is only allowed to use those labels. Smack rules are always the same
+as in the init namespace (limited only by what labels are mapped) and
+cannot be manipulated from the child namespace. The map is actually
+only for labels' names. The underlying structures for labels remain
+the same. The filesystem also stores the "unmapped" labels from the
+init namespace.
+
+Let's say we have those labels in the init namespace:
+label1
+label2
+label3
+
+and those rules:
+label1 label2 rwx
+label1 label3 rwx
+label2 label3 rwx
+
+We create a map for a namespace:
+label1 -> mapped1
+label2 -> mapped2
+
+This means that 'label3' is completely invisible in the namespace. As if
+it didn't exist. All the rules that include it are ignored.
+
+Effectively in the namespace we have only one rule:
+mapped1 mapped2 rwx
+
+Which in reality is:
+label1 label2 rwx
+
+All requests to access an object with a 'label3' will be denied. If it
+ever comes to a situation where 'label3' would have to be printed
+(e.g. reading an exec or mmap label from a file to which we have
+access) then huh sign '?' will be printed instead.
+
+All the operations in the namespace on the remaining labels will have
+to be performed using their mapped names. Things like changing own
+process's label, changing filesystem label. Labels will also be
+printed with their mapped names.
+
+You cannot import new labels in a namespace. Every operation that
+would do so in an init namespace will return an error in the child
+namespace. You cannot assign an unmapped or not existing label to an
+object. You can only operate on labels that have been explicitly
+mapped.
+
+
+--- Capabilities ---
+
+Enabling Smack related capabilities (CAP_MAC_ADMIN and
+CAP_MAC_OVERRIDE) is main goal of Smack namespace, so it can work
+properly in the container. And those capabilities do work to some
+extent. In several places where capabilities are checked compatibility
+with Smack namespace has been introduced. Capabilities are of course
+limited to operate only on mapped labels.
+
+CAP_MAC_OVERRIDE works fully, will allow you to ignore Smack access
+rules, but only between objects that have labels mapped. So in the
+example above having this CAP will allow e.g. label2 to write to
+label1, but will not allow any access to label3.
+
+With CAP_MAC_ADMIN the following operations has been allowed inside
+the namespace:
+- setting and removing xattr on files, including the security.* ones
+- setting process's own label (/proc/self/attr/current)
+- mounting in a privileged Smack mode, which means one can specify
+  additional mount options like: smackfsdef, smackfsfloor etc.
+
+Again this is also allowed only on the mapped labels. Labels on the
+filesystem will be stored in unmapped form so they are preserved
+through reboots.
+
+Such a namespace construct allows e.g. systemd (with Smack support)
+working in a container to assign labels properly to daemons and other
+processes.
+
+
+--- Usage ---
+
+Smack namespace is written using LSM hooks inside user namespace. That
+means it's connected to it.
+
+To create a new Smack namespace you need to unshare() user namespace
+as usual. If that is all you do though, than there is no difference to
+what is now. To activate the Smack namespace you need to fill the
+labels' map. It is in a file /proc/$PID/attr/label_map.
+
+By default the map is empty and Smack namespaces are inactive (labels
+are taken directly from a parent namespace). It also means that the
+Smack capabilities will be inactive. After you fill the map it starts
+to take effect in the namespace and Smack capabilities (only on mapped
+labels) start to work.
+
+Due to the way Smack works only CAP_MAC_ADMIN from the parent
+namespace (init_user_ns for now, see the "Current limitations" below)
+is allowed to fill the map. That means that an unprivileged user is
+still allowed to create the user namespace but it will not be able to
+fill the labels' map (activate Smack namespace). An administrator
+intervention is required.
+
+The attr_map write format is:
+unmapped_label mapped_label
+
+When reading the file it shows an active map for a namespace the
+process in question is in in the format:
+unmapped_label -> mapped_label
+
+If the label_map file is empty it means the namespace is not mapped
+and Smack namespace is inactive (no mappings, MAC related capabilities
+behave as they did before, meaning they are active only in
+init_user_ns). For init_user_ns the map will always be empty.
+
+Writing to the map file is not disabled after the first write as it is
+in uid_map. For Smack we have no means to map ranges of labels, hence
+it can really be advantageous to be able to expand the map later
+on. But you can only add to the map. You cannot remove already mapped
+labels. You cannot change the already existing mappings. Also mappings
+has to be 1-1. All requests to create a map where either the unmapped
+or the mapped label already exists in the map will be denied.
+
+setns() with Smack namespace active has an additional check that the
+label of a process that is calling setns() has to be already mapped in
+the target Smack namespace for the call to succeed.
+
+
+--- Special labels ---
+
+Smack is using some special labels that have built-in rules. Things
+like floor '_', dash '^', star '*', etc. Those labels are not
+automatically mapped to the namespace. Moreover, you can choose to map
+a different label from the init namespace to behave e.g. like floor
+inside the namespace.
+
+Let's say we have no rules and those labels in the init namespace:
+_
+floor_to_be
+label
+
+Both 'label' and 'floor_to_be' can read objects with '_'. But they
+have no access rights to each other.
+
+Now let's create a map like this:
+_             ordinary_label
+floor_to_be   _
+label         mapped
+
+Right now label 'mapped' can read label '_' which means that
+effectively inside this namespace label 'label' has gained read access
+to the 'floor_to_be'. The label 'ordinary_label' is exactly it, an
+ordinary label that the built-in rules no longer apply to inside the
+namespace.
+
+To sum up, special labels in the namespace behave the same as in the
+init namespace. Not the original special labels though, but the ones
+we map to specials. This is the only case where a namespace can have
+access rights the init namespace does not have (like the 'label' to
+'floor_to_be' in the example above).
+
+Of course mappings like these are perfectly legal:
+_   _
+*   *
+^   ^
+
+
+--- Current limitations ---
+
+The Smack namespace is not hierarchical yet. It is currently not
+possible to fill a label_map of a nested user namespace (you can still
+create nested user namespace, it will just inherit its parent's map
+and won't have active Smack capabilities). When hierarchy will be
+implemented the process creating another namespace will be allowed to
+map only labels that it has permission to itself (those that it has in
+its own map).
+
+Special files inside the virtual smackfs needs to be reviewed whether
+it's beneficial to have some of their functionality namespaced as well
+(e.g. onlycap, syslog. ambient, etc). This would increase
+CAP_MAC_ADMIN privileges inside the namespace.
+
+
+--- Error codes ---
+
+While working in the namespace patches the error codes has been made
+to propagate properly from a place they occurred. New error codes has
+also been introduced for Smack in the context of namespace usage. This
+is a complete summary of error codes used throughout the Smack now:
+
+ENOMEM      and other system errors that might come from low level
+            kernel functions like memory allocations
+EOPNOTSUPP  means the underlying system operation is not
+            supported (eg. getxattr)
+EINVAL      means invalid syntax (e.g. empty label or one starting
+            with '-')
+EEXIST      when creating map means that a label is already mapped
+EBADR       is used for wrong namespace usage:
+            - trying to import a label inside a namespace (like trying
+              to use an unmapped label that would otherwise be imported)
+            - trying to create a Smack label map in the init namespace
+ENOENT      when failed to find a label we expected to exist (will not
+            be propagated to user-space)
+EPERM       means no permission to operate on an object, e.g. due to
+            insufficient capabilities or simply because the object
+	    cannot be operated on in the current context
+EACCESS     when access has been denied due to Smack access checks
+            (including object being outside of a namespace)
diff --git a/MAINTAINERS b/MAINTAINERS
index a226416..6effb1a 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -9377,6 +9377,7 @@  W:	http://schaufler-ca.com
 T:	git git://git.gitorious.org/smack-next/kernel.git
 S:	Maintained
 F:	Documentation/security/Smack.txt
+F:	Documentation/security/Smack-namespace.txt
 F:	security/smack/
 
 DRIVERS FOR ADAPTIVE VOLTAGE SCALING (AVS)
diff --git a/security/smack/Kconfig b/security/smack/Kconfig
index b19a7fb..a6e0f3f 100644
--- a/security/smack/Kconfig
+++ b/security/smack/Kconfig
@@ -49,4 +49,6 @@  config SECURITY_SMACK_NS
 	  This enables Smack namespace that makes it possible to map
 	  specific labels within user namespace (analogously to mapping
 	  UIDs) and to gain MAC capabilities over them.
+	  Documentation is availabile here:
+	  Documentation/security/Smack-namespace.txt
 	  If you are unsure how to answer this question, answer N.