// Copyright (c) 2010 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef SANDBOX_WIN_SRC_POLICY_ENGINE_OPCODES_H_
#define SANDBOX_WIN_SRC_POLICY_ENGINE_OPCODES_H_
#include "sandbox/win/src/policy_engine_params.h"
#include "base/basictypes.h"
// The low-level policy is implemented using the concept of policy 'opcodes'.
// An opcode is a structure that contains enough information to perform one
// comparison against one single input parameter. For example, an opcode can
// encode just one of the following comparison:
//
// - Is input parameter 3 not equal to NULL?
// - Does input parameter 2 start with L"c:\\"?
// - Is input parameter 5, bit 3 is equal 1?
//
// Each opcode is in fact equivalent to a function invocation where all
// the parameters are known by the opcode except one. So say you have a
// function of this form:
// bool fn(a, b, c, d) with 4 arguments
//
// Then an opcode is:
// op(fn, b, c, d)
// Which stores the function to call and its 3 last arguments
//
// Then and opcode evaluation is:
// op.eval(a) ------------------------> fn(a,b,c,d)
// internally calls
//
// The idea is that complex policy rules can be split into streams of
// opcodes which are evaluated in sequence. The evaluation is done in
// groups of opcodes that have N comparison opcodes plus 1 action opcode:
//
// [comparison 1][comparison 2]...[comparison N][action][comparison 1]...
// ----- evaluation order----------->
//
// Each opcode group encodes one high-level policy rule. The rule applies
// only if all the conditions on the group evaluate to true. The action
// opcode contains the policy outcome for that particular rule.
//
// Note that this header contains the main building blocks of low-level policy
// but not the low level policy class.
namespace sandbox {
// These are the possible policy outcomes. Note that some of them might
// not apply and can be removed. Also note that The following values only
// specify what to do, not how to do it and it is acceptable given specific
// cases to ignore the policy outcome.
enum EvalResult {
// Comparison opcode values:
EVAL_TRUE, // Opcode condition evaluated true.
EVAL_FALSE, // Opcode condition evaluated false.
EVAL_ERROR, // Opcode condition generated an error while evaluating.
// Action opcode values:
ASK_BROKER, // The target must generate an IPC to the broker. On the broker
// side, this means grant access to the resource.
DENY_ACCESS, // No access granted to the resource.
GIVE_READONLY, // Give readonly access to the resource.
GIVE_ALLACCESS, // Give full access to the resource.
GIVE_CACHED, // IPC is not required. Target can return a cached handle.
GIVE_FIRST, // TODO(cpu)
SIGNAL_ALARM, // Unusual activity. Generate an alarm.
FAKE_SUCCESS, // Do not call original function. Just return 'success'.
FAKE_ACCESS_DENIED, // Do not call original function. Just return 'denied'
// and do not do IPC.
TERMINATE_PROCESS, // Destroy target process. Do IPC as well.
};
// The following are the implemented opcodes.
enum OpcodeID {
OP_ALWAYS_FALSE, // Evaluates to false (EVAL_FALSE).
OP_ALWAYS_TRUE, // Evaluates to true (EVAL_TRUE).
OP_NUMBER_MATCH, // Match a 32-bit integer as n == a.
OP_ULONG_MATCH_RANGE, // Match an ulong integer as a <= n <= b.
OP_ULONG_AND_MATCH, // Match using bitwise AND; as in: n & a != 0.
OP_WSTRING_MATCH, // Match a string for equality.
OP_ACTION // Evaluates to an action opcode.
};
// Options that apply to every opcode. They are specified when creating
// each opcode using OpcodeFactory::MakeOpXXXXX() family of functions
// Do nothing special.
const uint32 kPolNone = 0;
// Convert EVAL_TRUE into EVAL_FALSE and vice-versa. This allows to express
// negated conditions such as if ( a && !b).
const uint32 kPolNegateEval = 1;
// Zero the MatchContext context structure. This happens after the opcode
// is evaluated.
const uint32 kPolClearContext = 2;
// Use OR when evaluating this set of opcodes. The policy evaluator by default
// uses AND when evaluating. Very helpful when
// used with kPolNegateEval. For example if you have a condition best expressed
// as if(! (a && b && c)), the use of this flags allows it to be expressed as
// if ((!a) || (!b) || (!c)).
const uint32 kPolUseOREval = 4;
// Keeps the evaluation state between opcode evaluations. This is used
// for string matching where the next opcode needs to continue matching
// from the last character position from the current opcode. The match
// context is preserved across opcode evaluation unless an opcode specifies
// as an option kPolClearContext.
struct MatchContext {
size_t position;
uint32 options;
MatchContext() {
Clear();
}
void Clear() {
position = 0;
options = 0;
}
};
// Models a policy opcode; that is a condition evaluation were all the
// arguments but one are stored in objects of this class. Use OpcodeFactory
// to create objects of this type.
// This class is just an implementation artifact and not exposed to the
// API clients or visible in the intercepted service. Internally, an
// opcode is just:
// - An integer that identifies the actual opcode.
// - An index to indicate which one is the input argument
// - An array of arguments.
// While an OO hierarchy of objects would have been a natural choice, the fact
// that 1) this code can execute before the CRT is loaded, presents serious
// problems in terms of guarantees about the actual state of the vtables and
// 2) because the opcode objects are generated in the broker process, we need to
// use plain objects. To preserve some minimal type safety templates are used
// when possible.
class PolicyOpcode {
friend class OpcodeFactory;
public:
// Evaluates the opcode. For a typical comparison opcode the return value
// is EVAL_TRUE or EVAL_FALSE. If there was an error in the evaluation the
// the return is EVAL_ERROR. If the opcode is an action opcode then the
// return can take other values such as ASK_BROKER.
// parameters: An array of all input parameters. This argument is normally
// created by the macros POLPARAMS_BEGIN() POLPARAMS_END.
// count: The number of parameters passed as first argument.
// match: The match context that is persisted across the opcode evaluation
// sequence.
EvalResult Evaluate(const ParameterSet* parameters, size_t count,
MatchContext* match);
// Retrieves a stored argument by index. Valid index values are
// from 0 to < kArgumentCount.
template <typename T>
void GetArgument(size_t index, T* argument) const {
COMPILE_ASSERT(sizeof(T) <= sizeof(arguments_[0]), invalid_size);
*argument = *reinterpret_cast<const T*>(&arguments_[index].mem);
}
// Sets a stored argument by index. Valid index values are
// from 0 to < kArgumentCount.
template <typename T>
void SetArgument(size_t index, const T& argument) {
COMPILE_ASSERT(sizeof(T) <= sizeof(arguments_[0]), invalid_size);
*reinterpret_cast<T*>(&arguments_[index].mem) = argument;
}
// Retrieves the actual address of an string argument. When using
// GetArgument() to retrieve an index that contains a string, the returned
// value is just an offset to the actual string.
// index: the stored string index. Valid values are from 0
// to < kArgumentCount.
const wchar_t* GetRelativeString(size_t index) const {
ptrdiff_t str_delta = 0;
GetArgument(index, &str_delta);
const char* delta = reinterpret_cast<const char*>(this) + str_delta;
return reinterpret_cast<const wchar_t*>(delta);
}
// Returns true if this opcode is an action opcode without actually
// evaluating it. Used to do a quick scan forward to the next opcode group.
bool IsAction() const {
return (OP_ACTION == opcode_id_);
};
// Returns the opcode type.
OpcodeID GetID() const {
return opcode_id_;
}
// Returns the stored options such as kPolNegateEval and others.
uint32 GetOptions() const {
return options_;
}
// Sets the stored options such as kPolNegateEval.
void SetOptions(int16 options) {
options_ = options;
}
private:
static const size_t kArgumentCount = 4; // The number of supported argument.
struct OpcodeArgument {
UINT_PTR mem;
};
// Better define placement new in the class instead of relying on the
// global definition which seems to be fubared.
void* operator new(size_t, void* location) {
return location;
}
// Helper function to evaluate the opcode. The parameters have the same
// meaning that in Evaluate().
EvalResult EvaluateHelper(const ParameterSet* parameters,
MatchContext* match);
OpcodeID opcode_id_;
int16 parameter_;
int16 options_;
OpcodeArgument arguments_[PolicyOpcode::kArgumentCount];
};
enum StringMatchOptions {
CASE_SENSITIVE = 0, // Pay or Not attention to the case as defined by
CASE_INSENSITIVE = 1, // RtlCompareUnicodeString windows API.
EXACT_LENGHT = 2 // Don't do substring match. Do full string match.
};
// Opcodes that do string comparisons take a parameter that is the starting
// position to perform the comparison so we can do substring matching. There
// are two special values:
//
// Start from the current position and compare strings advancing forward until
// a match is found if any. Similar to CRT strstr().
const int kSeekForward = -1;
// Perform a match with the end of the string. It only does a single comparison.
const int kSeekToEnd = 0xfffff;
// A PolicyBuffer is a variable size structure that contains all the opcodes
// that are to be created or evaluated in sequence.
struct PolicyBuffer {
size_t opcode_count;
PolicyOpcode opcodes[1];
};
// Helper class to create any opcode sequence. This class is normally invoked
// only by the high level policy module or when you need to handcraft a special
// policy.
// The factory works by creating the opcodes using a chunk of memory given
// in the constructor. The opcodes themselves are allocated from the beginning
// (top) of the memory, while any string that an opcode needs is allocated from
// the end (bottom) of the memory.
//
// In essence:
//
// low address ---> [opcode 1]
// [opcode 2]
// [opcode 3]
// | | <--- memory_top_
// | free |
// | |
// | | <--- memory_bottom_
// [string 1]
// high address --> [string 2]
//
// Note that this class does not keep track of the number of opcodes made and
// it is designed to be a building block for low-level policy.
//
// Note that any of the MakeOpXXXXX member functions below can return NULL on
// failure. When that happens opcode sequence creation must be aborted.
class OpcodeFactory {
public:
// memory: base pointer to a chunk of memory where the opcodes are created.
// memory_size: the size in bytes of the memory chunk.
OpcodeFactory(char* memory, size_t memory_size)
: memory_top_(memory) {
memory_bottom_ = &memory_top_[memory_size];
}
// policy: contains the raw memory where the opcodes are created.
// memory_size: contains the actual size of the policy argument.
OpcodeFactory(PolicyBuffer* policy, size_t memory_size) {
memory_top_ = reinterpret_cast<char*>(&policy->opcodes[0]);
memory_bottom_ = &memory_top_[memory_size];
}
// Returns the available memory to make opcodes.
size_t memory_size() const {
return memory_bottom_ - memory_top_;
}
// Creates an OpAlwaysFalse opcode.
PolicyOpcode* MakeOpAlwaysFalse(uint32 options);
// Creates an OpAlwaysFalse opcode.
PolicyOpcode* MakeOpAlwaysTrue(uint32 options);
// Creates an OpAction opcode.
// action: The action to return when Evaluate() is called.
PolicyOpcode* MakeOpAction(EvalResult action, uint32 options);
// Creates an OpNumberMatch opcode.
// selected_param: index of the input argument. It must be a ulong or the
// evaluation result will generate a EVAL_ERROR.
// match: the number to compare against the selected_param.
PolicyOpcode* MakeOpNumberMatch(int16 selected_param, unsigned long match,
uint32 options);
// Creates an OpNumberMatch opcode (void pointers are cast to numbers).
// selected_param: index of the input argument. It must be an void* or the
// evaluation result will generate a EVAL_ERROR.
// match: the pointer numeric value to compare against selected_param.
PolicyOpcode* MakeOpVoidPtrMatch(int16 selected_param, const void* match,
uint32 options);
// Creates an OpUlongMatchRange opcode using the memory passed in the ctor.
// selected_param: index of the input argument. It must be a ulong or the
// evaluation result will generate a EVAL_ERROR.
// lower_bound, upper_bound: the range to compare against selected_param.
PolicyOpcode* MakeOpUlongMatchRange(int16 selected_param,
unsigned long lower_bound,
unsigned long upper_bound,
uint32 options);
// Creates an OpWStringMatch opcode using the raw memory passed in the ctor.
// selected_param: index of the input argument. It must be a wide string
// pointer or the evaluation result will generate a EVAL_ERROR.
// match_str: string to compare against selected_param.
// start_position: when its value is from 0 to < 0x7fff it indicates an
// offset from the selected_param string where to perform the comparison. If
// the value is SeekForward then a substring search is performed. If the
// value is SeekToEnd the comparison is performed against the last part of
// the selected_param string.
// Note that the range in the position (0 to 0x7fff) is dictated by the
// current implementation.
// match_opts: Indicates additional matching flags. Currently CaseInsensitive
// is supported.
PolicyOpcode* MakeOpWStringMatch(int16 selected_param,
const wchar_t* match_str,
int start_position,
StringMatchOptions match_opts,
uint32 options);
// Creates an OpUlongAndMatch opcode using the raw memory passed in the ctor.
// selected_param: index of the input argument. It must be ulong or the
// evaluation result will generate a EVAL_ERROR.
// match: the value to bitwise AND against selected_param.
PolicyOpcode* MakeOpUlongAndMatch(int16 selected_param,
unsigned long match,
uint32 options);
private:
// Constructs the common part of every opcode. selected_param is the index
// of the input param to use when evaluating the opcode. Pass -1 in
// selected_param to indicate that no input parameter is required.
PolicyOpcode* MakeBase(OpcodeID opcode_id, uint32 options,
int16 selected_param);
// Allocates (and copies) a string (of size length) inside the buffer and
// returns the displacement with respect to start.
ptrdiff_t AllocRelative(void* start, const wchar_t* str, size_t lenght);
// Points to the lowest currently available address of the memory
// used to make the opcodes. This pointer increments as opcodes are made.
char* memory_top_;
// Points to the highest currently available address of the memory
// used to make the opcodes. This pointer decrements as opcode strings are
// allocated.
char* memory_bottom_;
DISALLOW_COPY_AND_ASSIGN(OpcodeFactory);
};
} // namespace sandbox
#endif // SANDBOX_WIN_SRC_POLICY_ENGINE_OPCODES_H_