Home | History | Annotate | Download | only in common 
      1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
      2 // Use of this source code is governed by a BSD-style license that can be
      3 // found in the LICENSE file.
      4 
      5 #ifndef CONTENT_COMMON_SANDBOX_MAC_H_
      6 #define CONTENT_COMMON_SANDBOX_MAC_H_
      7 
      8 #include <string>
      9 
     10 #include "base/basictypes.h"
     11 #include "base/containers/hash_tables.h"
     12 #include "base/gtest_prod_util.h"
     13 #include "content/common/content_export.h"
     14 #include "content/public/common/sandbox_type_mac.h"
     15 
     16 namespace base {
     17 class FilePath;
     18 }
     19 
     20 #if __OBJC__
     21 @class NSArray;
     22 @class NSString;
     23 #else
     24 class NSArray;
     25 class NSString;
     26 #endif
     27 
     28 namespace content {
     29 
     30 // Class representing a substring of the sandbox profile tagged with its type.
     31 class SandboxSubstring {
     32  public:
     33   enum SandboxSubstringType {
     34     PLAIN,    // Just a plain string, no escaping necessary.
     35     LITERAL,  // Escape for use in (literal ...) expression.
     36     REGEX,    // Escape for use in (regex ...) expression.
     37   };
     38 
     39   SandboxSubstring() {}
     40 
     41   explicit SandboxSubstring(const std::string& value)
     42       : value_(value),
     43         type_(PLAIN) {}
     44 
     45   SandboxSubstring(const std::string& value, SandboxSubstringType type)
     46       : value_(value),
     47         type_(type) {}
     48 
     49   const std::string& value() { return value_; }
     50   SandboxSubstringType type() { return type_; }
     51 
     52  private:
     53   std::string value_;
     54   SandboxSubstringType type_;
     55 };
     56 
     57 class CONTENT_EXPORT Sandbox {
     58  public:
     59   // A map of variable name -> string to substitute in its place.
     60   typedef base::hash_map<std::string, SandboxSubstring>
     61       SandboxVariableSubstitions;
     62 
     63   // Warm up System APIs that empirically need to be accessed before the
     64   // sandbox is turned on. |sandbox_type| is the type of sandbox to warm up.
     65   // Valid |sandbox_type| values are defined by the enum SandboxType, or can be
     66   // defined by the embedder via
     67   // ContentClient::GetSandboxProfileForProcessType().
     68   static void SandboxWarmup(int sandbox_type);
     69 
     70   // Turns on the OS X sandbox for this process.
     71   // |sandbox_type| - type of Sandbox to use. See SandboxWarmup() for legal
     72   // values.
     73   // |allowed_dir| - directory to allow access to, currently the only sandbox
     74   // profile that supports this is SANDBOX_TYPE_UTILITY .
     75   //
     76   // Returns true on success, false if an error occurred enabling the sandbox.
     77   static bool EnableSandbox(int sandbox_type,
     78                             const base::FilePath& allowed_dir);
     79 
     80   // Returns true if the sandbox has been enabled for the current process.
     81   static bool SandboxIsCurrentlyActive();
     82 
     83   // Exposed for testing purposes, used by an accessory function of our tests
     84   // so we can't use FRIEND_TEST.
     85 
     86   // Build the Sandbox command necessary to allow access to a named directory
     87   // indicated by |allowed_dir|.
     88   // Returns a string containing the sandbox profile commands necessary to allow
     89   // access to that directory or nil if an error occured.
     90 
     91   // The header comment for PostProcessSandboxProfile() explains how variable
     92   // substition works in sandbox templates.
     93   // The returned string contains embedded variables. The function fills in
     94   // |substitutions| to contain the values for these variables.
     95   static NSString* BuildAllowDirectoryAccessSandboxString(
     96                        const base::FilePath& allowed_dir,
     97                        SandboxVariableSubstitions* substitutions);
     98 
     99   // Assemble the final sandbox profile from a template by removing comments
    100   // and substituting variables.
    101   //
    102   // |sandbox_template| is a string which contains 2 entitites to operate on:
    103   //
    104   // - Comments - The sandbox comment syntax is used to make the OS sandbox
    105   // optionally ignore commands it doesn't support. e.g.
    106   // ;10.6_ONLY (foo)
    107   // Where (foo) is some command that is only supported on OS X 10.6.
    108   // The ;10.6_ONLY comment can then be removed from the template to enable
    109   // (foo) as appropriate.
    110   //
    111   // - Variables - denoted by @variable_name@ .  These are defined in the
    112   // sandbox template in cases where another string needs to be substituted at
    113   // runtime. e.g. @HOMEDIR_AS_LITERAL@ is substituted at runtime for the user's
    114   // home directory escaped appropriately for a (literal ...) expression.
    115   //
    116   // |comments_to_remove| is a list of NSStrings containing the comments to
    117   // remove.
    118   // |substitutions| is a hash of "variable name" -> "string to substitute".
    119   // Where the replacement string is tagged with information on how it is to be
    120   // escaped e.g. used as part of a regex string or a literal.
    121   //
    122   // On output |final_sandbox_profile_str| contains the final sandbox profile.
    123   // Returns true on success, false otherwise.
    124   static bool PostProcessSandboxProfile(
    125                   NSString* in_sandbox_data,
    126                   NSArray* comments_to_remove,
    127                   SandboxVariableSubstitions& substitutions,
    128                   std::string *final_sandbox_profile_str);
    129 
    130  private:
    131   // Returns an (allow file-read-metadata) rule for |allowed_path| and all its
    132   // parent directories.
    133   static NSString* AllowMetadataForPath(const base::FilePath& allowed_path);
    134 
    135   // Escape |src_utf8| for use in a plain string variable in a sandbox
    136   // configuraton file.  On return |dst| is set to the quoted output.
    137   // Returns: true on success, false otherwise.
    138   static bool QuotePlainString(const std::string& src_utf8, std::string* dst);
    139 
    140   // Escape |str_utf8| for use in a regex literal in a sandbox
    141   // configuraton file.  On return |dst| is set to the utf-8 encoded quoted
    142   // output.
    143   //
    144   // The implementation of this function is based on empirical testing of the
    145   // OS X sandbox on 10.5.8 & 10.6.2 which is undocumented and subject to
    146   // change.
    147   //
    148   // Note: If str_utf8 contains any characters < 32 || >125 then the function
    149   // fails and false is returned.
    150   //
    151   // Returns: true on success, false otherwise.
    152   static bool QuoteStringForRegex(const std::string& str_utf8,
    153                                   std::string* dst);
    154 
    155   // Convert provided path into a "canonical" path matching what the Sandbox
    156   // expects i.e. one without symlinks.
    157   // This path is not necessarily unique e.g. in the face of hardlinks.
    158   static base::FilePath GetCanonicalSandboxPath(const base::FilePath& path);
    159 
    160   FRIEND_TEST_ALL_PREFIXES(MacDirAccessSandboxTest, StringEscape);
    161   FRIEND_TEST_ALL_PREFIXES(MacDirAccessSandboxTest, RegexEscape);
    162   FRIEND_TEST_ALL_PREFIXES(MacDirAccessSandboxTest, SandboxAccess);
    163 
    164   DISALLOW_IMPLICIT_CONSTRUCTORS(Sandbox);
    165 };
    166 
    167 }  // namespace content
    168 
    169 #endif  // CONTENT_COMMON_SANDBOX_MAC_H_
    170