Merge ~cjwatson/launchpad:doc-update-security into launchpad:master

[Colin Watson]

Update some details of "Security Policy in Launchpad"

I updated formatting, some paths, and a few other details. Otherwise it seems to be more or less up to date (if perhaps not very complete), so lift it back up to the "Technical" section of the index.

[Jürgen Gmach (jugmac00)]

review: Approve

diff --git a/doc/index.rst b/doc/index.rst
index 1677578..cfe0521 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -48,6 +48,7 @@ Technical
    :maxdepth: 1
 
    pip
+   security
 
 Possibly out-of-date
 --------------------
@@ -55,7 +56,6 @@ Possibly out-of-date
 .. toctree::
    :maxdepth: 1
 
-   security
    email
 
 Other
diff --git a/doc/security.rst b/doc/security.rst
index 0ff5d6a..c80dba8 100644
--- a/doc/security.rst
+++ b/doc/security.rst
@@ -10,20 +10,24 @@ This document is about security policy in Launchpad.
 Defining Permissions in Launchpad
 ---------------------------------
 
-**NOTE: A new permission should only be defined if absolutely necessary, and
-it should be considered thoroughly in a code review.**
+.. note::
 
-Occassionally, you'll find yourself in a situation where the existing
-permissions in Launchpad aren't enough for what you want. For example, as I
-was writing this document I needed a permission I could attach to things to
-provide policy for who can view a thing. That is, I wanted a permission called
-launchpad.View.
-A new permission (see the NOTE above) is defined in Launchpad in the file
-lib/canonical/launchpad/permissions.zcml. So, to define the permission
-launchpad.View, we'd add a line like this to that file:
+    A new permission should only be defined if absolutely necessary, and it
+    should be considered thoroughly in a code review.
 
-    <permission id="launchpad.View" title="Viewing something"
-      access_level="read" />
+Occasionally, you'll find yourself in a situation where the existing
+permissions in Launchpad aren't enough for what you want. For example, when
+privacy support was first being added to Launchpad, it required a permission
+to provide policy for who can view a thing, called ``launchpad.View``.
+
+A new permission (see the note above) is defined in Launchpad in the file
+``lib/lp/permissions.zcml``. So, to define the permission
+``launchpad.View``, we'd add a line like this to that file:
+
+.. code-block:: xml
+
+    <permission
+      id="launchpad.View" title="Viewing something" access_level="read" />
 
 
 Defining Authorization Policies for Permissions
@@ -36,25 +40,29 @@ interface.
 In Launchpad, an authorization policy is expressed through a security adapter.
 To define a security adapter for a given permission on an interface:
 
-1. Define the adapter in lib/canonical/launchpad/security.py. Here's a simple
-example of an adapter that authorizes only an object owner for the
-launchpad.Edit permission on objects that implement the IHasOwner interface::
+1. Define the adapter in ``lib/lp/security.py``. Here's a simple example of
+   an adapter that authorizes only an object owner for the
+   ``launchpad.Edit`` permission on objects that implement the ``IHasOwner``
+   interface:
+
+.. code-block:: python
 
     class EditByOwner(AuthorizationBase):
         permission = 'launchpad.Edit'
         usedfor = IHasOwner
 
-        def checkAuthenticated(self, person):
+        def checkAuthenticated(self, user):
             """Authorize the object owner."""
-            if person.id == self.obj.owner.id:
-                return True
+            return user.isOwner(self.obj)
+
+Read the ``IAuthorization`` interface to ensure that you've defined the
+adapter appropriately.
 
-Read the IAuthorization interface to ensure that you've defined the adapter
-appropriately.
+2. Declare the permission on a given interface in a ZCML file. So, for the
+   above adapter, here's how it might be hooked up to ``IProduct``, where
+   ``IProduct`` is protected with the ``launchpad.Edit`` permission:
 
-2. Declare the permission on a given interface in a zcml file. So, for the
-above adapter, here's how it's hooked up to IProduct, where IProduct is
-protected with the launchpad.Edit permission::
+.. code-block:: xml
 
     <class
         class="lp.registry.model.product.Product">
@@ -68,6 +76,7 @@ protected with the launchpad.Edit permission::
           set_attributes="commercial_subscription description"/>
     </class>
 
-In this example, the EditByOwner adapter's checkAuthenticated method will be
-called to determine if the currently authenticated user is authorized to
-access whatever is protected by launchpad.Edit on an IProduct.
+In this example, the ``EditByOwner`` adapter's ``checkAuthenticated`` method
+will be called to determine if the currently authenticated user is
+authorized to access whatever is protected by ``launchpad.Edit`` on an
+``IProduct``.