policy_machine 0.0.1

data/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing
+
+If you find a bug:
+
+* Check the "GitHub issue tracker" to see if anyone else has reported issue.
+* If you don't see anything, create an issue with information on how to reproduce it.
+
+If you want to contribute an enhancement or a fix:
+
+* Fork the project on GitHub.
+* bundle install
+* Make your changes with tests.
+* Run all automated tests to see if your change broke anything or is providing anything less than 100% code coverage (see below).
+* Commit the changes without making changes to any other files that aren't related to your enhancement or fix.
+* Send a pull request.
+
+## Running Automated Tests
+
+Run all rspec with:
+
+```
+[bundle exec] rspec
+```
+
+Simplecov code coverage is generated automatically.  Any changes you make to this repository should
+ensure that code coverage remains at 100%.  **No pull request will be merged unless proof is given 
+(i.e. a PR comment) that code coverage remains at 100% in the PR branch.**
+
+## Making Your Own Policy Machine Storage Adapter
+
+A template storage adapter is provided in `lib/policy_machine_storage_adapters/template.rb`.  Copy this 
+storage adapter as a starting point for making your own; implement all methods contained therein.
+
+To test your storage adapter, adapt the tests in either `spec/policy_machine_storage_adapters/in_memory_spec.rb` or
+`spec/policy_machine_storage_adapters/neography_spec.rb`.

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 YOURNAME
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,98 @@
+policy_machine
+==============
+
+A ruby implementation of the Policy Machine authorization formalism.  You can find the NIST specification for Policy
+Machines [here](http://csrc.nist.gov/pm/documents/pm_report-rev-x_final.pdf).
+
+Note that prohibitions, obligations and multiple policy classes have not yet been implemented.  These aspects of the Policy Machine
+will be included in future versions of this gem.
+
+# Installation
+
+Add the following to your Gemfile:
+```
+gem 'policy_machine'
+```
+
+# Usage
+```
+require 'policy_machine'
+require 'policy_machine_storage_adapters/in_memory'
+
+policy_machine = PolicyMachine.new('my_policy_machine', ::PolicyMachineStorageAdapter::InMemory)
+
+# This PM is taken from the policy machine spec at http://csrc.nist.gov/pm/documents/pm_report-rev-x_final.pdf,
+# Figure 4. (pg. 19)
+
+# Users
+u1 = policy_machine.create_user('u1')
+u2 = policy_machine.create_user('u2')
+u3 = policy_machine.create_user('u3')
+
+# Objects
+o1 = policy_machine.create_object('o1')
+o2 = policy_machine.create_object('o2')
+o3 = policy_machine.create_object('o3')
+
+# User Attributes
+group1 = policy_machine.create_user_attribute('Group1')
+group2 = policy_machine.create_user_attribute('Group2')
+division = policy_machine.create_user_attribute('Division')
+
+# Object Attributes
+project1 = policy_machine.create_object_attribute('Project1')
+project2 = policy_machine.create_object_attribute('Project2')
+projects = policy_machine.create_object_attribute('Projects')
+
+# Operations
+r = policy_machine.create_operation('read')
+w = policy_machine.create_operation('write')
+
+# Assignments
+policy_machine.add_assignment(u1, group1)
+policy_machine.add_assignment(u2, group2)
+policy_machine.add_assignment(u3, division)
+policy_machine.add_assignment(group1, division)
+policy_machine.add_assignment(group2, division)
+policy_machine.add_assignment(o1, project1)
+policy_machine.add_assignment(o2, project1)
+policy_machine.add_assignment(o3, project2)
+policy_machine.add_assignment(project1, projects)
+policy_machine.add_assignment(project2, projects)
+
+# Associations
+policy_machine.add_association(group1, Set.new([w]), project1)
+policy_machine.add_association(group2, Set.new([w]), project2)
+policy_machine.add_association(division, Set.new([r]), projects)
+
+# List all privileges encoded in the policy machine
+policy_machine.privileges
+
+# Returns true
+policy_machine.is_privilege?(u1, w, o1)
+
+# Returns false
+policy_machine.is_privilege?(u3, w, o3)
+```
+
+# Storage Adapters
+
+Note that the Policy Machine in the above example stores policy elements in memory.  Other persistent
+storage options are available in `lib/policy_machine_storage_adapters`.
+
+*Neography*
+
+The Neography storage adapter uses the neo4j graph database, which must be installed separately,
+and `gem 'neography'`. This should not be used in production since the interface is slow.
+
+*ActiveRecord*
+
+The ActiveRecord storage adapter talks to your existing MySQL database via your preconfigured
+ActiveRecord. You'll need to run `rails generate policy_machine migration` to add the necessary
+tables to your database.
+
+If you'd like to make your own storage adapter, see See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+# Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).

data/lib/generators/policy_machine/policy_machine_generator.rb

@@ -0,0 +1,13 @@
+require 'rails/generators/active_record/migration/migration_generator'
+
+class PolicyMachineGenerator < ::ActiveRecord::Generators::MigrationGenerator
+  desc "Create a migration to store Policy Machine elements in your database"
+
+  source_root File.expand_path('../templates', __FILE__)
+
+  def initialize(*args)
+    args[0] = ['generate_policy_machine']
+    super(*args)
+  end
+
+end

data/lib/generators/policy_machine/templates/migration.rb

@@ -0,0 +1,40 @@
+class GeneratePolicyMachine < ActiveRecord::Migration
+  def change
+
+    create_table :policy_elements do |t|
+      t.string :unique_identifier, null: false
+      t.string :policy_machine_uuid
+      t.string :type, null: false
+      t.text :extra_attributes
+    end
+    add_index :policy_elements, [:unique_identifier], unique: true
+    add_index :policy_elements, [:type]
+
+    create_table :policy_element_associations do |t|
+      t.integer :user_attribute_id, null: false
+      t.integer :object_attribute_id, null: false
+    end
+    add_index :policy_element_associations, [:user_attribute_id, :object_attribute_id], name: 'index_pe_assocs_on_ua_and_oa'
+
+    create_table :transitive_closure, id: false do |t|
+      t.integer :ancestor_id, null: false
+      t.integer :descendant_id, null: false
+    end
+    add_index :transitive_closure, [:ancestor_id, :descendant_id], unique: true
+    add_index :transitive_closure, [:descendant_id]
+
+    create_table :assignments do |t|
+      t.integer :parent_id, null: false
+      t.integer :child_id, null: false
+    end
+    add_index :assignments, [:parent_id, :child_id], unique: true
+    add_index :assignments, [:child_id]
+
+    create_table :operations_policy_element_associations, id: false do |t|
+      t.integer :policy_element_association_id, null: false
+      t.integer :operation_id, null: false
+    end
+    add_index :operations_policy_element_associations, [:policy_element_association_id, :operation_id], unique: true, name: 'index_pe_assoc_os_on_assoc_and_o'
+
+  end
+end

data/lib/policy_machine.rb

@@ -0,0 +1,236 @@
+require 'policy_machine/policy_element'
+require 'policy_machine/association'
+require 'securerandom'
+require 'active_support/inflector'
+require 'set'
+
+# require all adapters
+Dir.glob(File.dirname(File.absolute_path(__FILE__)) + '/policy_machine_storage_adapters/*.rb').each{ |f| require f }
+
+class PolicyMachine
+  POLICY_ELEMENT_TYPES = %w(user user_attribute object object_attribute operation policy_class)
+
+  attr_accessor :name
+  attr_reader   :uuid
+  attr_reader   :policy_machine_storage_adapter
+
+  def initialize(options = {})
+    @name = (options[:name] || options['name'] || 'default_policy_machine').to_s.strip
+    @uuid = (options[:uuid] || options['uuid'] || SecureRandom.uuid).to_s.strip
+    policy_machine_storage_adapter_class = options[:storage_adapter] || options['storage_adapter'] || ::PolicyMachineStorageAdapter::InMemory
+    @policy_machine_storage_adapter = policy_machine_storage_adapter_class.new
+
+    raise(ArgumentError, "uuid cannot be blank") if @uuid.empty?
+  end
+
+  ##
+  # Persist an assignment in this policy machine.
+  # An assignment is a binary relation between two existing policy elements.
+  # Some policy element types cannot be assigned to other types.  See the NIST
+  # spec for details.
+  #
+  def add_assignment(src_policy_element, dst_policy_element)
+    assert_policy_element_in_machine(src_policy_element)
+    assert_policy_element_in_machine(dst_policy_element)
+
+    src_policy_element.assign_to(dst_policy_element)
+  end
+
+  ##
+  # Remove an assignment in this policy machine.
+  #
+  def remove_assignment(src_policy_element, dst_policy_element)
+    assert_policy_element_in_machine(src_policy_element)
+    assert_policy_element_in_machine(dst_policy_element)
+
+    src_policy_element.unassign(dst_policy_element)
+  end
+
+  ##
+  # Add an association between a user_attribute, an operation_set and an object_attribute
+  # in this policy machine.
+  #
+  def add_association(user_attribute_pe, operation_set, object_attribute_pe)
+    assert_policy_element_in_machine(user_attribute_pe)
+    operation_set.each{ |op| assert_policy_element_in_machine(op) }
+    assert_policy_element_in_machine(object_attribute_pe)
+
+    PM::Association.create(user_attribute_pe, operation_set, object_attribute_pe, @uuid, @policy_machine_storage_adapter)
+  end
+
+  ##
+  # Can we derive a privilege of the form (u, op, o) from this policy machine?
+  # user_or_attribute is a user or user_attribute.
+  # operation is an operation.
+  # object_or_attribute is an object or object attribute.
+  #
+  # TODO: add option to ignore policy classes to allow consumer to speed up this method.
+  def is_privilege?(user_or_attribute, operation, object_or_attribute, options = {})
+    unless user_or_attribute.is_a?(PM::User) || user_or_attribute.is_a?(PM::UserAttribute)
+      raise(ArgumentError, "user_attribute_pe must be a User or UserAttribute.")
+    end
+
+    unless operation.is_a?(PM::Operation)
+      raise(ArgumentError, "operation must be an Operation.")
+    end
+
+    unless object_or_attribute.is_a?(PM::Object) || object_or_attribute.is_a?(PM::ObjectAttribute)
+      raise(ArgumentError, "object_or_attribute must either be an Object or ObjectAttribute.")
+    end
+
+    # Try to get associations to check from options
+    associations = options[:associations] || options['associations']
+    if associations
+      raise(ArgumentError, "expected options[:associations] to be an Array; got #{associations.class}") unless associations.is_a?(Array)
+      raise(ArgumentError, "options[:associations] cannot be empty") if associations.empty?
+      raise(ArgumentError, "expected each element of options[:associations] to be a PM::Association") unless associations.all?{|a| a.is_a?(PM::Association)}
+
+      associations.keep_if{ |assoc| assoc.includes_operation?(operation) }
+      return false if associations.empty?
+    else
+      associations = operation.associations
+    end
+
+    # Is a privilege iff options[:in_user_attribute] is involved (given options[:in_user_attribute] is not nil)
+    in_user_attribute = options[:in_user_attribute] || options['in_user_attribute']
+    if in_user_attribute
+      unless in_user_attribute.is_a?(PM::UserAttribute)
+        raise(ArgumentError, "expected options[:in_user_attribute] to be a PM::UserAttribute; got #{in_user_attribute.class}")
+      end
+      if user_or_attribute.connected?(in_user_attribute)
+        user_or_attribute = in_user_attribute
+      else
+        return false
+      end
+    end
+
+    # Is a privilege iff options[:in_object_attribute] is involved (given options[:in_object_attribute] is not nil)
+    in_object_attribute = options[:in_object_attribute] || options['in_object_attribute']
+    if in_object_attribute
+      unless in_object_attribute.is_a?(PM::ObjectAttribute)
+        raise(ArgumentError, "expected options[:in_object_attribute] to be a PM::ObjectAttribute; got #{in_object_attribute.class}")
+      end
+      if object_or_attribute.connected?(in_object_attribute)
+        object_or_attribute = in_object_attribute
+      else
+        return false
+      end
+    end
+
+    policy_classes_containing_object = object_or_attribute.policy_classes
+    if policy_classes_containing_object.empty?
+      is_privilege_single_policy_class(user_or_attribute, object_or_attribute, associations)
+    else
+      is_privilege_multiple_policy_classes(user_or_attribute, object_or_attribute, associations, policy_classes_containing_object)
+    end
+  end
+
+  ##
+  # Returns an array of all privileges encoded in this
+  # policy machine.  Each privilege is of the form:
+  # [PM::User, PM::Operation, PM::Object]
+  #
+  # TODO:  might make privilege a class of its own
+  def privileges
+    privileges = []
+
+    users.each do |user|
+      operations.each do |operation|
+        objects.each do |object|
+          if is_privilege?(user, operation, object)
+            privileges << [user, operation, object]
+          end
+        end
+      end
+    end
+
+    privileges
+  end
+
+  ##
+  # Returns an array of all user_attributes a PM::User is assigned to,
+  # directly or indirectly.
+  def list_user_attributes(user)
+    unless user.is_a?(PM::User)
+      raise(ArgumentError, "Expected a PM::User, got a #{user.class}")
+    end
+    assert_policy_element_in_machine(user)
+    user.user_attributes(@policy_machine_storage_adapter)
+  end
+
+  POLICY_ELEMENT_TYPES.each do |pe_type|
+    pm_class = "PM::#{pe_type.camelize}".constantize
+
+    ##
+    # Define a create method for each policy element type, as in create_user
+    # Each method takes one argument, the unique_identifier of the policy element.
+    #
+    define_method("create_#{pe_type}") do |unique_identifier, extra_attributes = {}|
+      # when creating a policy element, we provide a unique_identifier, the uuid of this policy machine
+      # and a policy machine storage adapter to allow us to persist the policy element.
+      pm_class.send(:create, unique_identifier, @uuid, @policy_machine_storage_adapter, extra_attributes)
+    end
+
+    ##
+    # Define an "all" method for each policy element type, as in .users or .object_attributes
+    # This will return all persisted of the elements of this type. If an options hash is passed
+    # then only elements that match all specified attributes will be returned.
+    #
+    define_method(pe_type.pluralize) do |options = {}|
+      # TODO:  We might want to scope by the uuid of this policy machine in the request to the persistent store, rather than
+      # here, after records have already been retrieved.
+      # TODO: When the policy machine raises a NoMethoError, we should log a nice message
+      # saying that the underlying policy element class doesn't implement 'all'.  Do
+      # it when we have a logger, though.
+      all_found = pm_class.send(:all, @policy_machine_storage_adapter, options)
+      all_found.select{ |pe| pe.policy_machine_uuid == uuid }
+    end
+  end
+
+  ##
+  # Execute the passed-in block transactionally: any error raised out of the block causes
+  # all the block's changes to be rolled back.
+  # TODO: Possibly rescue NotImplementError and warn.
+  def transaction(&block)
+    policy_machine_storage_adapter.transaction(&block)
+  end
+
+  private
+
+    # Raise unless the argument is a policy element.
+    def assert_policy_element_in_machine(arg_pe)
+      unless arg_pe.is_a?(PM::PolicyElement)
+        raise(ArgumentError, "arg must each be a kind of PolicyElement; got #{arg_pe.class.name} instead")
+      end
+      unless arg_pe.policy_machine_uuid == self.uuid
+        raise(ArgumentError, "#{arg_pe.unique_identifier} is not in policy machine with uuid #{self.uuid}")
+      end
+    end
+
+    # According to the NIST spec:  "the triple (u, op, o) is a privilege, iff there
+    # exists an association (ua, ops, oa), such that user u→+ua, op ∈ ops, and o→*oa."
+    # Note:  this method assumes that the caller has already checked that the given operation is in the operation_set
+    # for all associations provided.
+    def is_privilege_single_policy_class(user_or_attribute, object_or_attribute, associations)
+      # does there exist an association (ua, ops, oa), such that user u→+ua, op ∈ ops, and o→*oa?
+      associations.any? do |assoc|
+        user_or_attribute.connected?(assoc.user_attribute) && object_or_attribute.connected?(assoc.object_attribute)
+      end
+    end
+
+    # According to the NIST spec:  "In multiple policy class situations, the triple (u, op, o) is a PM privilege, iff for
+    # each policy class pcl that contains o, there exists an association (uai, opsj, oak),
+    # such that user u→+uai, op ∈ opsj, o→*oak, and oak→+pcl."
+    # Note:  this method assumes that the caller has already checked that the given operation is in the operation_set
+    # for all associations provided.
+    def is_privilege_multiple_policy_classes(user_or_attribute, object_or_attribute, associations, policy_classes_containing_object)
+      policy_classes_containing_object.all? do |pc|
+        associations.any? do |assoc|
+          user_or_attribute.connected?(assoc.user_attribute) &&
+          object_or_attribute.connected?(assoc.object_attribute) &&
+          assoc.object_attribute.connected?(pc)
+        end
+      end
+    end
+
+end