add some documentation notes about trust being per-profile

IPython/nbformat/sign.py

@@ -1,312 +1,319
 """Functions for signing notebooks"""
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2014, The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import base64
 from contextlib import contextmanager
 import hashlib
 from hmac import HMAC
 import io
 import os
 
 from IPython.utils.py3compat import string_types, unicode_type, cast_bytes
 from IPython.utils.traitlets import Instance, Bytes, Enum, Any, Unicode, Bool
 from IPython.config import LoggingConfigurable, MultipleInstanceError
 from IPython.core.application import BaseIPythonApplication, base_flags
 
 from .current import read, write
 
 #-----------------------------------------------------------------------------
 # Code
 #-----------------------------------------------------------------------------
 try:
     # Python 3
     algorithms = hashlib.algorithms_guaranteed
 except AttributeError:
     algorithms = hashlib.algorithms
 
 def yield_everything(obj):
     """Yield every item in a container as bytes
     
     Allows any JSONable object to be passed to an HMAC digester
     without having to serialize the whole thing.
     """
     if isinstance(obj, dict):
         for key in sorted(obj):
             value = obj[key]
             yield cast_bytes(key)
             for b in yield_everything(value):
                 yield b
     elif isinstance(obj, (list, tuple)):
         for element in obj:
             for b in yield_everything(element):
                 yield b
     elif isinstance(obj, unicode_type):
         yield obj.encode('utf8')
     else:
         yield unicode_type(obj).encode('utf8')
 
 
 @contextmanager
 def signature_removed(nb):
     """Context manager for operating on a notebook with its signature removed
     
     Used for excluding the previous signature when computing a notebook's signature.
     """
     save_signature = nb['metadata'].pop('signature', None)
     try:
         yield
     finally:
         if save_signature is not None:
             nb['metadata']['signature'] = save_signature
 
 
 class NotebookNotary(LoggingConfigurable):
     """A class for computing and verifying notebook signatures."""
     
     profile_dir = Instance("IPython.core.profiledir.ProfileDir")
     def _profile_dir_default(self):
         from IPython.core.application import BaseIPythonApplication
         app = None
         try:
             if BaseIPythonApplication.initialized():
                 app = BaseIPythonApplication.instance()
         except MultipleInstanceError:
             pass
         if app is None:
             # create an app, without the global instance
             app = BaseIPythonApplication()
             app.initialize(argv=[])
         return app.profile_dir
     
     algorithm = Enum(algorithms, default_value='sha256', config=True,
         help="""The hashing algorithm used to sign notebooks."""
     )
     def _algorithm_changed(self, name, old, new):
         self.digestmod = getattr(hashlib, self.algorithm)
     
     digestmod = Any()
     def _digestmod_default(self):
         return getattr(hashlib, self.algorithm)
     
     secret_file = Unicode(config=True,
         help="""The file where the secret key is stored."""
     )
     def _secret_file_default(self):
         if self.profile_dir is None:
             return ''
         return os.path.join(self.profile_dir.security_dir, 'notebook_secret')
     
     secret = Bytes(config=True,
         help="""The secret key with which notebooks are signed."""
     )
     def _secret_default(self):
         # note : this assumes an Application is running
         if os.path.exists(self.secret_file):
             with io.open(self.secret_file, 'rb') as f:
                 return f.read()
         else:
             secret = base64.encodestring(os.urandom(1024))
             self._write_secret_file(secret)
             return secret
     
     def _write_secret_file(self, secret):
         """write my secret to my secret_file"""
         self.log.info("Writing notebook-signing key to %s", self.secret_file)
         with io.open(self.secret_file, 'wb') as f:
             f.write(secret)
         try:
             os.chmod(self.secret_file, 0o600)
         except OSError:
             self.log.warn(
                 "Could not set permissions on %s",
                 self.secret_file
             )
         return secret
     
     def compute_signature(self, nb):
         """Compute a notebook's signature
         
         by hashing the entire contents of the notebook via HMAC digest.
         """
         hmac = HMAC(self.secret, digestmod=self.digestmod)
         # don't include the previous hash in the content to hash
         with signature_removed(nb):
             # sign the whole thing
             for b in yield_everything(nb):
                 hmac.update(b)
         
         return hmac.hexdigest()
     
     def check_signature(self, nb):
         """Check a notebook's stored signature
         
         If a signature is stored in the notebook's metadata,
         a new signature is computed and compared with the stored value.
         
         Returns True if the signature is found and matches, False otherwise.
         
         The following conditions must all be met for a notebook to be trusted:
         - a signature is stored in the form 'scheme:hexdigest'
         - the stored scheme matches the requested scheme
         - the requested scheme is available from hashlib
         - the computed hash from notebook_signature matches the stored hash
         """
         stored_signature = nb['metadata'].get('signature', None)
         if not stored_signature \
             or not isinstance(stored_signature, string_types) \
             or ':' not in stored_signature:
             return False
         stored_algo, sig = stored_signature.split(':', 1)
         if self.algorithm != stored_algo:
             return False
         my_signature = self.compute_signature(nb)
         return my_signature == sig
     
     def sign(self, nb):
         """Sign a notebook, indicating that its output is trusted
         
         stores 'algo:hmac-hexdigest' in notebook.metadata.signature
         
         e.g. 'sha256:deadbeef123...'
         """
         signature = self.compute_signature(nb)
         nb['metadata']['signature'] = "%s:%s" % (self.algorithm, signature)
     
     def mark_cells(self, nb, trusted):
         """Mark cells as trusted if the notebook's signature can be verified
         
         Sets ``cell.trusted = True | False`` on all code cells,
         depending on whether the stored signature can be verified.
         
         This function is the inverse of check_cells
         """
         if not nb['worksheets']:
             # nothing to mark if there are no cells
             return
         for cell in nb['worksheets'][0]['cells']:
             if cell['cell_type'] == 'code':
                 cell['trusted'] = trusted
     
     def _check_cell(self, cell):
         """Do we trust an individual cell?
         
         Return True if:
         
         - cell is explicitly trusted
         - cell has no potentially unsafe rich output
         
         If a cell has no output, or only simple print statements,
         it will always be trusted.
         """
         # explicitly trusted
         if cell.pop("trusted", False):
             return True
         
         # explicitly safe output
         safe = {
             'text/plain', 'image/png', 'image/jpeg',
             'text', 'png', 'jpg', # v3-style short keys
         }
         
         for output in cell['outputs']:
             output_type = output['output_type']
             if output_type in ('pyout', 'display_data'):
                 # if there are any data keys not in the safe whitelist
                 output_keys = set(output).difference({"output_type", "prompt_number", "metadata"})
                 if output_keys.difference(safe):
                     return False
         
         return True
     
     def check_cells(self, nb):
         """Return whether all code cells are trusted
         
         If there are no code cells, return True.
         
         This function is the inverse of mark_cells.
         """
         if not nb['worksheets']:
             return True
         trusted = True
         for cell in nb['worksheets'][0]['cells']:
             if cell['cell_type'] != 'code':
                 continue
             # only distrust a cell if it actually has some output to distrust
             if not self._check_cell(cell):
                 trusted = False
         return trusted
 
 
 trust_flags = {
     'reset' : (
         {'TrustNotebookApp' : { 'reset' : True}},
         """Generate a new key for notebook signature.
         All previously signed notebooks will become untrusted.
         """
     ),
 }
 trust_flags.update(base_flags)
 trust_flags.pop('init')
 
 
 class TrustNotebookApp(BaseIPythonApplication):
     
     description="""Sign one or more IPython notebooks with your key,
     to trust their dynamic (HTML, Javascript) output.
     
+    Trusting a notebook only applies to the current IPython profile.
+    To trust a notebook for use with a profile other than default,
+    add `--profile [profile name]`.
+    
     Otherwise, you will have to re-execute the notebook to see output.
     """
     
-    examples = """ipython trust mynotebook.ipynb and_this_one.ipynb"""
+    examples = """
+    ipython trust mynotebook.ipynb and_this_one.ipynb
+    ipython trust --profile myprofile mynotebook.ipynb
+    """
     
     flags = trust_flags
     
     reset = Bool(False, config=True,
         help="""If True, generate a new key for notebook signature.
         After reset, all previously signed notebooks will become untrusted.
         """
     )
     
     notary = Instance(NotebookNotary)
     def _notary_default(self):
         return NotebookNotary(parent=self, profile_dir=self.profile_dir)
     
     def sign_notebook(self, notebook_path):
         if not os.path.exists(notebook_path):
             self.log.error("Notebook missing: %s" % notebook_path)
             self.exit(1)
         with io.open(notebook_path, encoding='utf8') as f:
             nb = read(f, 'json')
         if self.notary.check_signature(nb):
             print("Notebook already signed: %s" % notebook_path)
         else:
             print("Signing notebook: %s" % notebook_path)
             self.notary.sign(nb)
             with io.open(notebook_path, 'w', encoding='utf8') as f:
                 write(nb, f, 'json')
     
     def generate_new_key(self):
         """Generate a new notebook signature key"""
         print("Generating new notebook key: %s" % self.notary.secret_file)
         self.notary._write_secret_file(os.urandom(1024))
     
     def start(self):
         if self.reset:
             self.generate_new_key()
             return
         if not self.extra_args:
             self.log.critical("Specify at least one notebook to sign.")
             self.exit(1)
         
         for notebook_path in self.extra_args:
             self.sign_notebook(notebook_path)
 

docs/source/notebook/security.rst

@@ -1,148 +1,154
 .. _notebook_security:
 
 Security in IPython notebooks
 =============================
 
 As IPython notebooks become more popular for sharing and collaboration,
 the potential for malicious people to attempt to exploit the notebook
 for their nefarious purposes increases. IPython 2.0 introduces a
 security model to prevent execution of untrusted code without explicit
 user input.
 
 The problem
 -----------
 
 The whole point of IPython is arbitrary code execution. We have no
 desire to limit what can be done with a notebook, which would negatively
 impact its utility.
 
 Unlike other programs, an IPython notebook document includes output.
 Unlike other documents, that output exists in a context that can execute
 code (via Javascript).
 
 The security problem we need to solve is that no code should execute
 just because a user has **opened** a notebook that **they did not
 write**. Like any other program, once a user decides to execute code in
 a notebook, it is considered trusted, and should be allowed to do
 anything.
 
 Our security model
 ------------------
 
 -  Untrusted HTML is always sanitized
 -  Untrusted Javascript is never executed
 -  HTML and Javascript in Markdown cells are never trusted
 -  **Outputs** generated by the user are trusted
 -  Any other HTML or Javascript (in Markdown cells, output generated by
    others) is never trusted
 -  The central question of trust is "Did the current user do this?"
 
 The details of trust
 --------------------
 
 IPython notebooks store a signature in metadata, which is used to answer
 the question "Did the current user do this?"
 
 This signature is a digest of the notebooks contents plus a secret key,
 known only to the user. The secret key is a user-only readable file in
 the IPython profile's security directory. By default, this is::
 
     ~/.ipython/profile_default/security/notebook_secret
 
+.. note::
+
+    The notebook secret being stored in the profile means that
+    loading a notebook in another profile results in it being untrusted,
+    unless you copy or symlink the notebook secret to share it across profiles.
+
 When a notebook is opened by a user, the server computes a signature
 with the user's key, and compares it with the signature stored in the
 notebook's metadata. If the signature matches, HTML and Javascript
 output in the notebook will be trusted at load, otherwise it will be
 untrusted.
 
 Any output generated during an interactive session is trusted.
 
 Updating trust
 **************
 
 A notebook's trust is updated when the notebook is saved. If there are
 any untrusted outputs still in the notebook, the notebook will not be
 trusted, and no signature will be stored. If all untrusted outputs have
 been removed (either via ``Clear Output`` or re-execution), then the
 notebook will become trusted.
 
 While trust is updated per output, this is only for the duration of a
 single session. A notebook file on disk is either trusted or not in its
 entirety.
 
 Explicit trust
 **************
 
 Sometimes re-executing a notebook to generate trusted output is not an
 option, either because dependencies are unavailable, or it would take a
 long time. Users can explicitly trust a notebook in two ways:
 
 -  At the command-line, with::
 
     ipython trust /path/to/notebook.ipynb
 
 -  After loading the untrusted notebook, with ``File / Trust Notebook``
 
 These two methods simply load the notebook, compute a new signature with
 the user's key, and then store the newly signed notebook.
 
 Reporting security issues
 -------------------------
 
 If you find a security vulnerability in IPython, either a failure of the
 code to properly implement the model described here, or a failure of the
 model itself, please report it to [e-mail].
 
 If you prefer to encrypt your security reports,
 you can use :download:`this PGP public key <ipython_security.asc>`.
 
 Affected use cases
 ------------------
 
 Some use cases that work in IPython 1.0 will become less convenient in
 2.0 as a result of the security changes. We do our best to minimize
 these annoyance, but security is always at odds with convenience.
 
 Javascript and CSS in Markdown cells
 ************************************
 
 While never officially supported, it had become common practice to put
 hidden Javascript or CSS styling in Markdown cells, so that they would
 not be visible on the page. Since Markdown cells are now sanitized (by
 `Google Caja <https://developers.google.com/caja>`__), all Javascript
 (including click event handlers, etc.) and CSS will be stripped.
 
 We plan to provide a mechanism for notebook themes, but in the meantime
 styling the notebook can only be done via either ``custom.css`` or CSS
 in HTML output. The latter only have an effect if the notebook is
 trusted, because otherwise the output will be sanitized just like
 Markdown.
 
 Collaboration
 *************
 
 When collaborating on a notebook, people probably want to see the
 outputs produced by their colleagues' most recent executions. Since each
 collaborator's key will differ, this will result in each share starting
 in an untrusted state. There are three basic approaches to this:
 
 -  re-run notebooks when you get them (not always viable)
 -  explicitly trust notebooks via ``ipython trust`` or the notebook menu
    (annoying, but easy)
 -  share a notebook secret, and use an IPython profile dedicated to the
    collaboration while working on the project.
 
 Multiple profiles or machines
 *****************************
 
 Since the notebook secret is stored in a profile directory by default,
 opening a notebook with a different profile or on a different machine
 will result in a different key, and thus be untrusted. The only current
 way to address this is by sharing the notebook secret. This can be
 facilitated by setting the configurable:
 
 .. sourcecode:: python
 
     c.NotebookApp.secret_file = "/path/to/notebook_secret"
 
 in each profile, and only sharing the secret once per machine.