update process/security docs in parallelz

docs/source/parallelz/parallel_multiengine.txt

@@ -192,9 +192,9 b' by index-access to the client:'
 
 .. sourcecode:: ipython
 
-    In [6]: rc.execute('c=a+b',targets=[0,2])
+    In [6]: rc[::2].execute('c=a+b') # shorthand for rc.execute('c=a+b',targets=[0,2])
 
-    In [7]: rc.execute('c=a-b',targets=[1,3])
+    In [7]: rc[1::2].execute('c=a-b') # shorthand for rc.execute('c=a-b',targets=[1,3])
 
     In [8]: rc[:]['c'] # shorthand for rc.pull('c',targets='all')
     Out[8]: [15,-5,15,-5]

docs/source/parallelz/parallel_process.txt

@@ -4,10 +4,6 b''
 Starting the IPython controller and engines
 ===========================================
 
-.. note::
-
-    Not adapted to zmq yet
-
 To use IPython for parallel computing, you need to start one instance of
 the controller and one or more instances of the engine. The controller
 and each engine can run on different machines or on the same machine.
@@ -16,8 +12,8 b' Because of this, there are many different possibilities.'
 Broadly speaking, there are two ways of going about starting a controller and engines:
 
 * In an automated manner using the :command:`ipclusterz` command.
-* In a more manual way using the :command:`ipcontroller` and 
-  :command:`ipengine` commands.
+* In a more manual way using the :command:`ipcontrollerz` and 
+  :command:`ipenginez` commands.
 
 This document describes both of these methods. We recommend that new users
 start with the :command:`ipclusterz` command as it simplifies many common usage
@@ -34,26 +30,24 b' matter which method you use to start your IPython cluster.'
 Let's say that you want to start the controller on ``host0`` and engines on
 hosts ``host1``-``hostn``. The following steps are then required:
 
-1. Start the controller on ``host0`` by running :command:`ipcontroller` on
+1. Start the controller on ``host0`` by running :command:`ipcontrollerz` on
    ``host0``.
-2. Move the FURL file (:file:`ipcontroller-engine.furl`) created by the 
+2. Move the JSON file (:file:`ipcontroller-engine.json`) created by the 
    controller from ``host0`` to hosts ``host1``-``hostn``.
 3. Start the engines on hosts ``host1``-``hostn`` by running 
-   :command:`ipengine`.  This command has to be told where the FURL file 
-   (:file:`ipcontroller-engine.furl`) is located.
-
-At this point, the controller and engines will be connected. By default, the
-FURL files created by the controller are put into the
-:file:`~/.ipython/security` directory. If the engines share a filesystem with
-the controller, step 2 can be skipped as the engines will automatically look
-at that location.
-
-The final step required required to actually use the running controller from a
-client is to move the FURL files :file:`ipcontroller-mec.furl` and
-:file:`ipcontroller-tc.furl` from ``host0`` to the host where the clients will
-be run. If these file are put into the :file:`~/.ipython/security` directory
-of the client's host, they will be found automatically. Otherwise, the full
-path to them has to be passed to the client's constructor.
+   :command:`ipenginez`.  This command has to be told where the JSON file 
+   (:file:`ipcontroller-engine.json`) is located.
+
+At this point, the controller and engines will be connected. By default, the JSON files
+created by the controller are put into the :file:`~/.ipython/clusterz_default/security`
+directory. If the engines share a filesystem with the controller, step 2 can be skipped as
+the engines will automatically look at that location.
+
+The final step required to actually use the running controller from a client is to move
+the JSON file :file:`ipcontroller-client.json` from ``host0`` to any host where clients
+will be run. If these file are put into the :file:`~/.ipython/clusterz_default/security`
+directory of the client's host, they will be found automatically. Otherwise, the full path
+to them has to be passed to the client's constructor.
 
 Using :command:`ipclusterz`
 ==========================
@@ -78,29 +72,39 b' controller and engines in the following situations:'
 .. note::
 
     Currently :command:`ipclusterz` requires that the
-    :file:`~/.ipython/security` directory live on a shared filesystem that is
+    :file:`~/.ipython/cluster_<profile>/security` directory live on a shared filesystem that is
     seen by both the controller and engines. If you don't have a shared file
-    system you will need to use :command:`ipcontroller` and
-    :command:`ipengine` directly.  This constraint can be relaxed if you are 
+    system you will need to use :command:`ipcontrollerz` and
+    :command:`ipenginez` directly.  This constraint can be relaxed if you are 
     using the :command:`ssh` method to start the cluster.
 
-Underneath the hood, :command:`ipclusterz` just uses :command:`ipcontroller`
-and :command:`ipengine` to perform the steps described above.
+Under the hood, :command:`ipclusterz` just uses :command:`ipcontrollerz`
+and :command:`ipenginez` to perform the steps described above.
 
 Using :command:`ipclusterz` in local mode
 ----------------------------------------
 
 To start one controller and 4 engines on localhost, just do::
 
-    $ ipclusterz -n 4
+    $ ipclusterz start -n 4
 
 To see other command line options for the local mode, do::
 
     $ ipclusterz -h
 
+.. note::
+
+    The remainder of this section refers to the 0.10 clusterfile model, no longer in use.
+    skip to 
+
 Using :command:`ipclusterz` in mpiexec/mpirun mode
 -------------------------------------------------
 
+.. note::
+
+    This section is out of date for IPython 0.11
+
+
 The mpiexec/mpirun mode is useful if you:
 
 1. Have MPI installed.
@@ -148,6 +152,11 b' More details on using MPI with IPython can be found :ref:`here <parallelmpi>`.'
 Using :command:`ipclusterz` in PBS mode
 --------------------------------------
 
+.. note::
+
+    This section is out of date for IPython 0.11
+
+
 The PBS mode uses the Portable Batch System [PBS]_ to start the engines. To
 use this mode, you first need to create a PBS script template that will be
 used to start the engines. Here is a sample PBS script template:
@@ -179,7 +188,7 b' There are a few important points about this template:'
    escape any ``$`` by using ``$$``.  This is important when referring to 
    environment variables in the template.
 
-4. Any options to :command:`ipengine` should be given in the batch script 
+4. Any options to :command:`ipenginez` should be given in the batch script 
    template.
 
 5. Depending on the configuration of you system, you may have to set 
@@ -197,8 +206,13 b' Additional command line options for this mode can be found by doing::'
 Using :command:`ipclusterz` in SSH mode
 --------------------------------------
 
-The SSH mode uses :command:`ssh` to execute :command:`ipengine` on remote
-nodes and the :command:`ipcontroller` on localhost.
+.. note::
+
+    This section is out of date for IPython 0.11
+
+
+The SSH mode uses :command:`ssh` to execute :command:`ipenginez` on remote
+nodes and the :command:`ipcontrollerz` on localhost.
 
 When using using this mode it highly recommended that you have set up SSH keys
 and are using ssh-agent [SSH]_ for password-less logins.
@@ -220,7 +234,7 b' note:'
 * The `engines` dict, where the keys is the host we want to run engines on and
   the value is the number of engines to run on that host.
 * send_furl can either be `True` or `False`, if `True` it will copy over the
-  furl needed for :command:`ipengine` to each host.
+  furl needed for :command:`ipenginez` to each host.
 
 The ``--clusterfile`` command line option lets you specify the file to use for
 the cluster definition. Once you have your cluster file and you can
@@ -232,7 +246,7 b' start your cluster like so:'
    $ ipclusterz ssh --clusterfile /path/to/my/clusterfile.py
 
 
-Two helper shell scripts are used to start and stop :command:`ipengine` on
+Two helper shell scripts are used to start and stop :command:`ipenginez` on
 remote hosts:
 
 * sshx.sh 
@@ -254,7 +268,7 b' The default sshx.sh is the following:'
 If you want to use a custom sshx.sh script you need to use the ``--sshx``
 option and specify the file to use. Using a custom sshx.sh file could be
 helpful when you need to setup the environment on the remote host before
-executing :command:`ipengine`.
+executing :command:`ipenginez`.
 
 For a detailed options list:
 
@@ -267,40 +281,40 b' Current limitations of the SSH mode of :command:`ipclusterz` are:'
 * Untested on Windows. Would require a working :command:`ssh` on Windows.
   Also, we are using shell scripts to setup and execute commands on remote
   hosts.
-* :command:`ipcontroller` is started on localhost, with no option to start it
+* :command:`ipcontrollerz` is started on localhost, with no option to start it
   on a remote node.
 
-Using the :command:`ipcontroller` and :command:`ipengine` commands
-==================================================================
+Using the :command:`ipcontrollerz` and :command:`ipenginez` commands
+====================================================================
 
-It is also possible to use the :command:`ipcontroller` and :command:`ipengine`
+It is also possible to use the :command:`ipcontrollerz` and :command:`ipenginez`
 commands to start your controller and engines. This approach gives you full
 control over all aspects of the startup process.
 
 Starting the controller and engine on your local machine
 --------------------------------------------------------
 
-To use :command:`ipcontroller` and :command:`ipengine` to start things on your
+To use :command:`ipcontrollerz` and :command:`ipenginez` to start things on your
 local machine, do the following.
 
 First start the controller::
 
-	$ ipcontroller
+	$ ipcontrollerz
 	
 Next, start however many instances of the engine you want using (repeatedly)
 the command::
 
-	$ ipengine
+	$ ipenginez
 
 The engines should start and automatically connect to the controller using the
-FURL files in :file:`~./ipython/security`. You are now ready to use the
+JSON files in :file:`~/.ipython/cluster_<profile>/security`. You are now ready to use the
 controller and engines from IPython.
 
 .. warning:: 
 	
-	The order of the above operations is very important.  You *must*
- 	start the controller before the engines, since the engines connect 
-	to the controller as they get started.
+	The order of the above operations may be important.  You *must*
+	start the controller before the engines, unless you are manually specifying
+	the ports on which to connect, in which case ordering is not important.
 
 .. note::
 
@@ -315,58 +329,54 b' Starting the controller and engines on different hosts'
 When the controller and engines are running on different hosts, things are
 slightly more complicated, but the underlying ideas are the same:
 
-1. Start the controller on a host using :command:`ipcontroller`.
-2. Copy :file:`ipcontroller-engine.furl` from :file:`~./ipython/security` on
+1. Start the controller on a host using :command:`ipcontrollerz`.
+2. Copy :file:`ipcontroller-engine.json` from :file:`~/.ipython/cluster_<profile>/security` on
    the controller's host to the host where the engines will run.
-3. Use :command:`ipengine` on the engine's hosts to start the engines.
+3. Use :command:`ipenginez` on the engine's hosts to start the engines.
 
-The only thing you have to be careful of is to tell :command:`ipengine` where
-the :file:`ipcontroller-engine.furl` file is located. There are two ways you
+The only thing you have to be careful of is to tell :command:`ipenginez` where
+the :file:`ipcontroller-engine.json` file is located. There are two ways you
 can do this:
 
-* Put :file:`ipcontroller-engine.furl` in the :file:`~./ipython/security`
+* Put :file:`ipcontroller-engine.json` in the :file:`~/.ipython/cluster_<profile>/security`
   directory on the engine's host, where it will be found automatically.
-* Call :command:`ipengine` with the ``--furl-file=full_path_to_the_file``
+* Call :command:`ipenginez` with the ``--file=full_path_to_the_file``
   flag.
 
-The ``--furl-file`` flag works like this::
+The ``--file`` flag works like this::
 
-    $ ipengine --furl-file=/path/to/my/ipcontroller-engine.furl
+    $ ipengine --file=/path/to/my/ipcontroller-engine.json
 
 .. note::
     
     If the controller's and engine's hosts all have a shared file system  
-    (:file:`~./ipython/security` is the same on all of them), then things
+    (:file:`~/.ipython/cluster_<profile>/security` is the same on all of them), then things
     will just work!
 
-Make FURL files persistent
+Make JSON files persistent
 ---------------------------
 
-At fist glance it may seem that that managing the FURL files is a bit
-annoying. Going back to the house and key analogy, copying the FURL around
+At fist glance it may seem that that managing the JSON files is a bit
+annoying. Going back to the house and key analogy, copying the JSON around
 each time you start the controller is like having to make a new key every time
 you want to unlock the door and enter your house. As with your house, you want
-to be able to create the key (or FURL file) once, and then simply use it at
+to be able to create the key (or JSON file) once, and then simply use it at
 any point in the future.
 
-This is possible, but before you do this, you **must** remove any old FURL
-files in the :file:`~/.ipython/security` directory.
+This is possible, but before you do this, you **must** remove any old JSON
+files in the :file:`~/.ipython/cluster_<profile>/security` directory.
 
 .. warning::
 
-    You **must** remove old FURL files before using persistent FURL files.
-
-Then, The only thing you have to do is decide what ports the controller will
-listen on for the engines and clients. This is done as follows::
+    You **must** remove old JSON files before using persistent JSON files.
 
-    $ ipcontroller -r --client-port=10101 --engine-port=10102
+Then, the only thing you have to do is specify the registration port, so that
+the connection information in the JSON files remains accurate::
 
-These options also work with all of the various modes of
-:command:`ipclusterz`::
+    $ ipcontrollerz -r --regport 12345
 
-    $ ipclusterz -n 2 -r --client-port=10101 --engine-port=10102
 
-Then, just copy the furl files over the first time and you are set. You can
+Then, just copy the JSON files over the first time and you are set. You can
 start and stop the controller and engines any many times as you want in the
 future, just make sure to tell the controller to use the *same* ports.
 
@@ -383,8 +393,8 b' Log files'
 
 All of the components of IPython have log files associated with them.
 These log files can be extremely useful in debugging problems with
-IPython and can be found in the directory :file:`~/.ipython/log`.  Sending
-the log files to us will often help us to debug any problems.
+IPython and can be found in the directory :file:`~/.ipython/cluster_<profile>/log`.
+Sending the log files to us will often help us to debug any problems.
 
 
 .. [PBS] Portable Batch System.  http://www.openpbs.org/

docs/source/parallelz/parallel_security.txt

@@ -6,9 +6,10 b' Security details of IPython'
 
 .. note::
 
-    Not adapted to zmq yet
+    This section is not thorough, and IPython.zmq needs a thorough security
+    audit.
 
-IPython's :mod:`IPython.zmq.parallel` package exposes the full power of the
+IPython's :mod:`IPython.zmq` package exposes the full power of the
 Python interpreter over a TCP/IP network for the purposes of parallel
 computing. This feature brings up the important question of IPython's security
 model. This document gives details about this model and how it is implemented
@@ -24,37 +25,50 b' are summarized here:'
 * The IPython *engine*.  This process is a full blown Python
   interpreter in which user code is executed.  Multiple
   engines are started to make parallel computing possible.
-* The IPython *controller*.  This process manages a set of 
-  engines, maintaining a queue for each and presenting
-  an asynchronous interface to the set of engines.
+* The IPython *hub*.  This process monitors a set of 
+  engines and schedulers, and keeps track of the state of the processes. It listens
+  for registration connections from engines and clients, and monitor connections
+  from schedulers.
+* The IPython *schedulers*. This is a set of processes that relay commands and results
+  between clients and engines. They are typically on the same machine as the controller,
+  and listen for connections from engines and clients, but connect to the Hub.
 * The IPython *client*.  This process is typically an
   interactive Python process that is used to coordinate the
   engines to get a parallel computation done.
 
-Collectively, these three processes are called the IPython *kernel*.
+Collectively, these processes are called the IPython *kernel*, and the hub and schedulers
+together are referred to as the *controller*.
 
-These three processes communicate over TCP/IP connections with a well defined
-topology. The IPython controller is the only process that listens on TCP/IP
-sockets. Upon starting, an engine connects to a controller and registers
-itself with the controller. These engine/controller TCP/IP connections persist
-for the lifetime of each engine.
+.. note::
+
+    Are these really still referred to as the Kernel?  It doesn't seem so to me.  'cluster'
+    seems more accurate.
+    
+    -MinRK
+
+These processes communicate over any transport supported by ZeroMQ (tcp,pgm,infiniband,ipc)
+with a well defined topology. The IPython hub and schedulers listen on sockets. Upon
+starting, an engine connects to a hub and registers itself, which then informs the engine
+of the connection information for the schedulers, and the engine then connects to the
+schedulers. These engine/hub and engine/scheduler connections persist for the
+lifetime of each engine.
 
-The IPython client also connects to the controller using one or more TCP/IP
-connections. These connections persist for the lifetime of the client only.
+The IPython client also connects to the controller processes using a number of socket
+connections. As of writing, this is one socket per scheduler (4), and 3 connections to the
+hub for a total of 7. These connections persist for the lifetime of the client only.
 
-A given IPython controller and set of engines typically has a relatively short
-lifetime. Typically this lifetime corresponds to the duration of a single
-parallel simulation performed by a single user. Finally, the controller,
-engines and client processes typically execute with the permissions of that
-same user. More specifically, the controller and engines are *not* executed as
-root or with any other superuser permissions.
+A given IPython controller and set of engines engines typically has a relatively
+short lifetime. Typically this lifetime corresponds to the duration of a single parallel
+simulation performed by a single user. Finally, the hub, schedulers, engines, and client
+processes typically execute with the permissions of that same user. More specifically, the
+controller and engines are *not* executed as root or with any other superuser permissions.
 
 Application logic
 =================
 
 When running the IPython kernel to perform a parallel computation, a user
 utilizes the IPython client to send Python commands and data through the
-IPython controller to the IPython engines, where those commands are executed
+IPython schedulers to the IPython engines, where those commands are executed
 and the data processed. The design of IPython ensures that the client is the
 only access point for the capabilities of the engines. That is, the only way
 of addressing the engines is through a client.
@@ -72,139 +86,62 b' Secure network connections'
 Overview
 --------
 
-All TCP/IP connections between the client and controller as well as the
-engines and controller are fully encrypted and authenticated. This section
-describes the details of the encryption and authentication approached used
-within IPython.
+ZeroMQ provides exactly no security. For this reason, users of IPython must be very
+careful in managing connections, because an open TCP/IP socket presents access to
+arbitrary execution as the user on the engine machines. As a result, the default behavior
+of controller processes is to only listen for clients on the loopback interface, and the
+client must establish SSH tunnels to connect to the controller processes.
 
-IPython uses the Foolscap network protocol [Foolscap]_ for all communications
-between processes. Thus, the details of IPython's security model are directly
-related to those of Foolscap. Thus, much of the following discussion is
-actually just a discussion of the security that is built in to Foolscap.
+.. warning:: 
 
-Encryption
-----------
+    If the controller's loopback interface is untrusted, then IPython should be considered
+    vulnerable, and this extends to the loopback of all connected clients, which have
+    opened a loopback port that is redirected to the controller's loopback port.
+
+
+SSH
+---
 
-For encryption purposes, IPython and Foolscap use the well known Secure Socket
-Layer (SSL) protocol [RFC5246]_. We use the implementation of this protocol
-provided by the OpenSSL project through the pyOpenSSL [pyOpenSSL]_ Python
-bindings to OpenSSL.
+Since ZeroMQ provides no security, SSH tunnels are the primary source of secure
+connections. A connector file, such as `ipcontroller-client.json`, will contain
+information for connecting to the controller, possibly including the address of an
+ssh-server through with the client is to tunnel. The Client object then creates tunnels
+using either [OpenSSH]_ or [Paramiko]_, depending on the platform. If users do not wish to
+use OpenSSH or Paramiko, or the tunneling utilities are insufficient, then they may
+construct the tunnels themselves, and simply connect clients and engines as if the
+controller were on loopback on the connecting machine.
+
+.. note::
+
+    There is not currently tunneling available for engines.
 
 Authentication
 --------------
 
-IPython clients and engines must also authenticate themselves with the
-controller. This is handled in a capabilities based security model
-[Capability]_. In this model, the controller creates a strong cryptographic
-key or token that represents each set of capability that the controller
-offers. Any party who has this key and presents it to the controller has full
-access to the corresponding capabilities of the controller. This model is
-analogous to using a physical key to gain access to physical items
-(capabilities) behind a locked door.
-
-For a capabilities based authentication system to prevent unauthorized access,
-two things must be ensured:
-
-* The keys must be cryptographically strong.  Otherwise attackers could gain 
-  access by a simple brute force key guessing attack.
-* The actual keys must be distributed only to authorized parties.
-
-The keys in Foolscap are called Foolscap URL's or FURLs. The following section
-gives details about how these FURLs are created in Foolscap. The IPython
-controller creates a number of FURLs for different purposes:
-
-* One FURL that grants IPython engines access to the controller.  Also
-  implicit in this access is permission to execute code sent by an
-  authenticated IPython client.
-* Two or more FURLs that grant IPython clients access to the controller.
-  Implicit in this access is permission to give the controller's engine code 
-  to execute.
-
-Upon starting, the controller creates these different FURLS and writes them
-files in the user-read-only directory :file:`$HOME/.ipython/security`. Thus,
-only the user who starts the controller has access to the FURLs.
-
-For an IPython client or engine to authenticate with a controller, it must
-present the appropriate FURL to the controller upon connecting. If the
-FURL matches what the controller expects for a given capability, access is
-granted. If not, access is denied. The exchange of FURLs is done after
-encrypted communications channels have been established to prevent attackers
-from capturing them.
+To protect users of shared machines, an execution key is used to authenticate all messages.
+
+The Session object that handles the message protocol uses a unique key to verify valid
+messages. This can be any value specified by the user, but the default behavior is a
+pseudo-random 128-bit number, as generated by `uuid.uuid4()`. This key is checked on every
+message everywhere it is unpacked (Controller, Engine, and Client) to ensure that it came
+from an authentic user, and no messages that do not contain this key are acted upon in any
+way.
+
+There is exactly one key per cluster - it must be the same everywhere. Typically, the
+controller creates this key, and stores it in the private connection files
+`ipython-{engine|client}.json`. These files are typically stored in the
+`~/.ipython/clusterz_<profile>/security` directory, and are maintained as readable only by
+the owner, just as is common practice with a user's keys in their `.ssh` directory.
+
+.. warning::
+
+    It is important to note that the key authentication, as emphasized by the use of
+    a uuid rather than generating a key with a cryptographic library, provides a 
+    defense against *accidental* messages more than it does against malicious attacks.
+    If loopback is compromised, it would be trivial for an attacker to intercept messages
+    and deduce the key, as there is no encryption.
 
-.. note::
 
-    The FURL is similar to an unsigned private key in SSH.
-
-Details of the Foolscap handshake
----------------------------------
-
-In this section we detail the precise security handshake that takes place at
-the beginning of any network connection in IPython. For the purposes of this
-discussion, the SERVER is the IPython controller process and the CLIENT is the
-IPython engine or client process.
-
-Upon starting, all IPython processes do the following:
-
-1. Create a public key x509 certificate (ISO/IEC 9594).
-2. Create a hash of the contents of the certificate using the SHA-1 algorithm.
-   The base-32 encoded version of this hash is saved by the process as its 
-   process id (actually in Foolscap, this is the Tub id, but here refer to
-   it as the process id).
-
-Upon starting, the IPython controller also does the following:
-
-1. Save the x509 certificate to disk in a secure location. The CLIENT
-   certificate is never saved to disk.
-2. Create a FURL for each capability that the controller has.  There are
-   separate capabilities the controller offers for clients and engines.  The
-   FURL is created using:  a) the process id of the SERVER, b) the IP 
-   address and port the SERVER is listening on and c) a 160 bit,    
-   cryptographically secure string that represents the capability (the
-   "capability id").
-3. The FURLs are saved to disk in a secure location on the SERVER's host.
-
-For a CLIENT to be able to connect to the SERVER and access a capability of
-that SERVER, the CLIENT must have knowledge of the FURL for that SERVER's
-capability. This typically requires that the file containing the FURL be
-moved from the SERVER's host to the CLIENT's host. This is done by the end
-user who started the SERVER and wishes to have a CLIENT connect to the SERVER.
-
-When a CLIENT connects to the SERVER, the following handshake protocol takes
-place:
-
-1. The CLIENT tells the SERVER what process (or Tub) id it expects the SERVER
-   to have.
-2. If the SERVER has that process id, it notifies the CLIENT that it will now 
-   enter encrypted mode.  If the SERVER has a different id, the SERVER aborts.
-3. Both CLIENT and SERVER initiate the SSL handshake protocol.
-4. Both CLIENT and SERVER request the certificate of their peer and verify
-   that certificate.  If this succeeds, all further communications are 
-   encrypted.
-5. Both CLIENT and SERVER send a hello block containing connection parameters
-   and their process id.
-6. The CLIENT and SERVER check that their peer's stated process id matches the
-   hash of the x509 certificate the peer presented.  If not, the connection is
-   aborted.
-7. The CLIENT verifies that the SERVER's stated id matches the id of the
-   SERVER the CLIENT is intending to connect to.  If not, the connection is 
-   aborted.
-8. The CLIENT and SERVER elect a master who decides on the final connection
-   parameters.
-
-The public/private key pair associated with each process's x509 certificate
-are completely hidden from this handshake protocol. There are however, used
-internally by OpenSSL as part of the SSL handshake protocol. Each process
-keeps their own private key hidden and sends its peer only the public key
-(embedded in the certificate).
-
-Finally, when the CLIENT requests access to a particular SERVER capability,
-the following happens:
-
-1. The CLIENT asks the SERVER for access to a capability by presenting that 
-   capabilities id.
-2. If the SERVER has a capability with that id, access is granted. If not,
-   access is not granted.
-3. Once access has been gained, the CLIENT can use the capability.
 
 Specific security vulnerabilities
 =================================
@@ -221,19 +158,27 b' Python code with the permissions of the user who started the engines. If an'
 attacker were able to connect their own hostile IPython client to the IPython
 controller, they could instruct the engines to execute code.
 
-This attack is prevented by the capabilities based client authentication
-performed after the encrypted channel has been established. The relevant
-authentication information is encoded into the FURL that clients must
-present to gain access to the IPython controller. By limiting the distribution
-of those FURLs, a user can grant access to only authorized persons.
 
-It is highly unlikely that a client FURL could be guessed by an attacker
+On the first level, this attack is prevented by requiring access to the controller's
+ports, which are recommended to only be open on loopback if the controller is on an
+untrusted local network. If the attacker does have access to the Controller's ports, then
+the attack is prevented by the capabilities based client authentication of the execution
+key. The relevant authentication information is encoded into the JSON file that clients
+must present to gain access to the IPython controller. By limiting the distribution of
+those keys, a user can grant access to only authorized persons, just as with SSH keys.
+
+It is highly unlikely that an execution key could be guessed by an attacker
 in a brute force guessing attack. A given instance of the IPython controller
 only runs for a relatively short amount of time (on the order of hours). Thus
 an attacker would have only a limited amount of time to test a search space of
-size 2**320. Furthermore, even if a controller were to run for a longer amount
-of time, this search space is quite large (larger for instance than that of
-typical username/password pair).
+size 2**128.  
+
+.. warning::
+
+    If the attacker has gained enough access to intercept loopback connections on
+    *either* the controller or client, then the key is easily deduced from network
+    traffic.
+
 
 Unauthorized engines
 --------------------
@@ -253,18 +198,22 b' client or engine to connect to a hostile IPython controller. That controller'
 would then have full access to the code and data sent between the IPython
 client and the IPython engines.
 
-Again, this attack is prevented through the FURLs, which ensure that a
-client or engine connects to the correct controller. It is also important to
-note that the FURLs also encode the IP address and port that the
-controller is listening on, so there is little chance of mistakenly connecting
-to a controller running on a different IP address and port.
+Again, this attack is prevented through the capabilities in a connection file, which
+ensure that a client or engine connects to the correct controller. It is also important to
+note that the connection files also encode the IP address and port that the controller is
+listening on, so there is little chance of mistakenly connecting to a controller running
+on a different IP address and port.
 
-When starting an engine or client, a user must specify which FURL to use
+When starting an engine or client, a user must specify the key to use
 for that connection. Thus, in order to introduce a hostile controller, the
-attacker must convince the user to use the FURLs associated with the
-hostile controller. As long as a user is diligent in only using FURLs from
+attacker must convince the user to use the key associated with the
+hostile controller. As long as a user is diligent in only using keys from
 trusted sources, this attack is not possible.
 
+.. note::
+
+    I may be wrong, the unauthorized controller may be easier to fake than this.
+
 Other security measures
 =======================
 
@@ -289,20 +238,24 b' or:'
 * The user has to use SSH port forwarding to tunnel the
   connections through the firewall.
    
-In either case, an attacker is presented with addition barriers that prevent
+In either case, an attacker is presented with additional barriers that prevent
 attacking or even probing the system.
 
 Summary
 =======
 
 IPython's architecture has been carefully designed with security in mind. The
-capabilities based authentication model, in conjunction with the encrypted
+capabilities based authentication model, in conjunction with SSH tunneled
 TCP/IP channels, address the core potential vulnerabilities in the system,
 while still enabling user's to use the system in open networks.
 
 Other questions
 ===============
 
+.. note::
+
+    this does not apply to ZMQ, but I am sure there will be questions.
+
 About keys
 ----------