[pypy-svn] r38259 - pypy/dist/pypy/doc

[arigo at codespeak.net]

Author: arigo
Date: Fri Feb  9 15:05:42 2007
New Revision: 38259

Modified:
   pypy/dist/pypy/doc/objspace-proxies.txt
Log:
Typo-sized changes.


Modified: pypy/dist/pypy/doc/objspace-proxies.txt
==============================================================================
--- pypy/dist/pypy/doc/objspace-proxies.txt	(original)
+++ pypy/dist/pypy/doc/objspace-proxies.txt	Fri Feb  9 15:05:42 2007
@@ -157,11 +157,15 @@
 references needed).
 
 The basic idea of this kind of security is not to protect against
-malicious code, unlike sandboxing, for example.  The idea is that,
-considering a large application that handles sensitive data, there are
-typically only a small number of places that need to explicitly
-manipulate that sensitive data; all the other places merely pass it
-around, or do entierely unrelated things.
+malicious code, unlike sandboxing, for example.  This is about the
+handling of "sensitive" data.  It covers two kinds of sensitive data:
+secret data which should not leak, and untrusted data coming from an
+external source and that must be validated before it is used.
+
+The idea is that, considering a large application that handles these
+kinds of sensitive data, there are typically only a small number of
+places that need to explicitly manipulate that sensitive data; all the
+other places merely pass it around, or do entierely unrelated things.
 
 Nevertheless, if a large application needs to be reviewed for security,
 it must be entierely carefully checked, because it is possible that a
@@ -170,7 +174,8 @@
 example, if any part of the application provides web services, an
 attacker might be able to issue unexpected requests with a regular web
 browser and deduce secret information from the details of the answers he
-gets.
+gets.  Another example is the common CGI attack where an attacker sends
+malformed inputs and causes the CGI script to do unintended things.
 
 An approach like that of the Taint Object Space allows the small parts
 of the program that manipulate sensitive data to be explicitly marked.
@@ -179,11 +184,16 @@
 because even a bug would be unable to leak the information.
 
 We have implemented a simple two-levels model: objects are either
-regular (untainted), or hidden (tainted).  It would be simple to extend
-the code for more fine-grained scales of secrecy.  For example it is
-typical in the literature to consider user-specified lattices of secrecy
-levels, corresponding to multiple "owners" that cannot access data
-belonging to another "owner" unless explicitly authorized to do so.
+regular (untainted), or sensitive (tainted).  Objects are marked as
+sensitive if they are secret or untrusted, and only declassified at
+carefully-checked positions (e.g. where the secret data is needed, or
+after the untrusted data has been fully validated).
+
+It would be simple to extend the code for more fine-grained scales of
+secrecy.  For example it is typical in the literature to consider
+user-specified lattices of secrecy levels, corresponding to multiple
+"owners" that cannot access data belonging to another "owner" unless
+explicitly authorized to do so.
 
 Tainting and untainting
 -----------------------
@@ -194,23 +204,23 @@
     >>>> from pypymagic import taint
     >>>> x = taint(6)
 
-    # x is secret from now on.  We can pass it around and
+    # x is hidden from now on.  We can pass it around and
     # even operate on it, but not inspect it.  Taintness
     # is propagated to operation results.
 
     >>>> x
     TaintError
 
-    >>>> if x > 5: y = 2
+    >>>> if x > 5: y = 2   # see below
     TaintError
 
-    >>>> y = x + 5       # ok
+    >>>> y = x + 5         # ok
     >>>> lst = [x, y]
     >>>> z = lst.pop()
-    >>>> t = type(z)     # type() works too, tainted answer
+    >>>> t = type(z)       # type() works too, tainted answer
     >>>> t
     TaintError
-    >>>> u = t is int    # even 'is' works
+    >>>> u = t is int      # even 'is' works
     >>>> u
     TaintError
 
@@ -222,12 +232,11 @@
 in the variable ``y``.
 
 Of course, there is a way to inspect tainted objects.  The basic way is
-to explicitly untaint the object.  In an application, the places that
-use this ``untaint()`` declassification function are the places that
-need careful security review.  To avoid unexpected objects showing up,
-the ``untaint()`` function must be called with the exact type of the
-object to declassify.  It will raise ``TaintError`` if the type doesn't
-match::
+to explicitly "declassify" it with the ``untaint()`` function.  In an
+application, the places that use ``untaint()`` are the places that need
+careful security review.  To avoid unexpected objects showing up, the
+``untaint()`` function must be called with the exact type of the object
+to declassify.  It will raise ``TaintError`` if the type doesn't match::
 
     >>>> from pypymagic import taint
     >>>> untaint(int, x)
@@ -265,27 +274,30 @@
     TaintError
 
 In the above example, all of ``i``, ``j`` and ``k`` contain a Taint
-Bomb.  Trying to untaint it raises ``TaintError``, but at the point
-where ``untaint()`` is called.  This means that all calls to
-``untaint()`` must also be carefully reviewed for what occurs if they
-receive a Taint Bomb; they might catch the ``TaintError`` and give the
-user a generic message that something went wrong, if we are reasonably
-careful that the message or even its preserve doesn't give information
-away.  This might be a decliate problem by itself, but there is no
-satisfying general solution to this problem; it must be considered on a
-case-by-case basis.  Again, what the Taint Object Space approach
-achieves is not solving these problems, but localizing them to
-well-defined small parts of the application - namely, around calls to
-``untaint()``.
+Bomb.  Trying to untaint it raises an exception - a generic
+``TaintError``.  What we win is that the exception gives little away,
+and most importantly it occurs at the point where ``untaint()`` is
+called, not where the operation failed.  This means that all calls to
+``untaint()`` - but not the rest of the code - must be carefully
+reviewed for what occurs if they receive a Taint Bomb; they might catch
+the ``TaintError`` and give the user a generic message that something
+went wrong, if we are reasonably careful that the message or even its
+presence doesn't give information away.  This might be a decliate
+problem by itself, but there is no satisfying general solution to this
+problem; it must be considered on a case-by-case basis.  Again, what the
+Taint Object Space approach achieves is not solving these problems, but
+localizing them to well-defined small parts of the application - namely,
+around calls to ``untaint()``.
 
 Note that the ``TaintError`` exception is deliberately not including any
 useful error message, because that might give information away too.
 However, it makes debugging quite harder.  This is a difficult problem
-to solve in general too; so far we implemented a "debug mode" that dumps
-information to the low-level stderr of the application (where we hope
+to solve in general too; so far we implemented a way to peek in a Taint
+Box or Bomb, ``pypymagic._taint_look(x)``, and a "debug mode" that
+prints the exception as soon as a Bomb is created.  Both write
+information to the low-level stderr of the application, where we hope
 that it is unlikely to be seen by anyone else than the application
-developer).  The debug mode must be activated with
-``pypymagic.taint_debug(1)``.
+developer.
 
 
 Taint Atomic functions
@@ -293,8 +305,8 @@
 
 Occasionally, a more complicated computation must be performed on a
 tainted object.  This requires first untainting the object, perform the
-computations, and then carefully taint the result again (including
-hiding all exceptions that could give information away).
+computations, and then carefully tainting the result again (including
+hiding all exceptions into Bombs).
 
 There is a built-in decorator that does exactly that::
 
@@ -340,7 +352,7 @@
         return expected_password == password
 
 It returns a tainted boolean answer, or a Taint Bomb if something
-went wrong.  A caller can do:
+went wrong.  A caller can do::
 
     ok = validate(passwords_db, 'john', '1234')
     ok = untaint(bool, ok)
@@ -349,19 +361,20 @@
 exception (with no information on it) if anything went wrong.  If even
 this is considered giving too much information away, the ``False`` case
 can be made indistinguishable from the ``TaintError`` case (simply by
-also raising an exception in ``validate()`` if the password is wrong).
+raising an exception in ``validate()`` if the password is wrong).
 
-In the above example, the security achieved is that as long as
-``validate()`` does not leak information, no other part of the code can
-obtain more information about a passwords database than a Yes/No answer
-to a precise query.
+In the above example, the security results achieved are the following:
+as long as ``validate()`` does not leak information, no other part of
+the code can obtain more information about a passwords database than a
+Yes/No answer to a precise query.
 
 A possible extension of the ``taint_atomic`` decorator would be to check
-the argument types as ``untaint()`` does, for the same reason - to
+the argument types, as ``untaint()`` does, for the same reason: to
 prevent bugs where a function like ``validate()`` above is accidentally
-called with the wrong kind of object, and thus leaks information about
-it.  For now, all ``taint_atomic`` function should be conservative and
-carefully check all assumptions on all input arguments.
+called with the wrong kind of tainted object, which would make it
+misbehave.  For now, all ``taint_atomic`` functions should be
+conservative and carefully check all assumptions on their input
+arguments.
 
 
 Interface