pledge 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7369f71bb2bfdbbea7dd07d98c86f443b8c0a09ddaf13090c6c0a379c2fe6eed
-  data.tar.gz: bea75bb0d79544311c633aeb04ad7bcb3d2061ace0c6f9f0829e05dd387068e0
+  metadata.gz: 949027d706330a2286744e8230a2bf32dcc70eb96bc92d96ea3ecfcc4cc9c79f
+  data.tar.gz: 746d5466733720404a1ed65c53d635f67f90d7c187e8e77b30148bec9fe71e58
 SHA512:
-  metadata.gz: 4031731b34fe1c2497cfa84ffad17b698ada329362cbb0f8730ea2bfa4f094c0429150b92364a8764d04eef1397be3cdb7d70145ccc9ea88b6e0dadb425d36b7
-  data.tar.gz: 3509a67789e3876149e8880bc031fdb0d5df2bf111cd65b7f112132b1dd64696ff38ef9f70efc854d5ba99eb4c83d1256b4d68ba5805e879725fc5e6ed14a735
+  metadata.gz: 75456b41d7c3c77633ce3395cf9c55f5a3d3812ba99cbdeb7ef3a4ff3ef4c9fac4f7e83ecf7ab8501e54b07189b3a9aa53d16c589932f14c40b52e5fa0a3a733
+  data.tar.gz: a75f472530864f085cfd0aa427abd18a871708b1916b2d0f1fabed31a5164a73a695769884e10ab045ef6f1d28333a6bb75ed6081b092f0de92e9b7a1fba8af5

data/CHANGELOG

@@ -1,3 +1,7 @@
+=== 1.2.0 (2019-07-07)
+
+* Add unveil library and Pledge.unveil for access to unveil(2) to control file system access (jeremyevans)
+
 === 1.1.0 (2019-04-25)
 
 * Support execpromises as optional second argument to Pledge.pledge (jeremyevans)

data/README.rdoc

@@ -1,17 +1,17 @@
 = pledge
 
-pledge exposes OpenBSD's pledge(2) system call to ruby, allowing a
-program to restrict the types of operations the program
-can do after that point.  Unlike other similar systems,
-pledge is specifically designed for programs that need to
-use a wide variety of operations on initialization, but
+pledge exposes OpenBSD's pledge(2) and unveil(2) system
+calls to ruby. pledge(2) allows a program to restrict the
+types of operations the program can do, and unveil(2)
+restricts access to the file system.
+
+Unlike other similar systems, pledge and unveil are
+designed for programs that need to use a wide variety of
+operations and file access on initialization, but
 a fewer number after initialization (when user input will
 be accepted).
 
-pledge(2) is supported on OpenBSD 5.9+. pledge(2) supports a second
-argument for execpromises on OpenBSD 6.3+.
-
-== Usage
+== pledge
 
 First, you need to require the library
 
@@ -53,8 +53,6 @@ in other classes:
   Object.send(:include, Pledge)
   pledge("rpath")
 
-== Options
-
 See the pledge(2) man page for a description of the allowed
 promises in the strings passed to +Pledge.pledge+.
 
@@ -63,6 +61,69 @@ promise is added automatically to the current process's promises,
 as ruby does not function without it, but it is not added to
 the execpromises (as you can execute non-ruby programs).
 
+== unveil
+
+First, you need to require the library
+
+  require 'unveil'
+
+Then you can use +Pledge.unveil+ as the interface to the unveil(2)
+system call.  You pass +Pledge.unveil+ a hash of paths and permissions,
+for those paths, and it calls unveil(2) with the path and permissions
+for each entry.
+
+The permissions should be a string with the following characters:
+
+r :: Allow read access to existing files and directories
+w :: Allow write access to existing files and directories
+x :: Allow execute access to programs
+c :: Allow create access for new files and directories
+
+You can use the empty string as permissions if you want to allow no access
+to the given path, even if you have granted some access to a folder above
+the given folder.  You can use a value of +:gem+ to allow read access to
+the directory for the gem specified by the key.
+
++Pledge.unveil+ locks the file system access to the specified paths. If
+you want to specify which paths to allow in multiple places in your
+program, use +Pledge.unveil_without_lock+ for the initial calls and
++Pledge.unveil+ for the final call.
+
+If +Pledge.unveil+ is called with an empty hash, it adds an unveil of +/+
+with no permissions, which denies all access to the file system if
++unveil_without_lock+ was not called previously with paths.
+
+Example:
+
+  Pledge.unveil(
+    '/home/foo/bar' => 'r',
+    '/home/foo/bar/data' => 'rwc',
+    '/bin' => 'x',
+    '/home/foo/bar/secret' => '',
+    'rack' => :gem
+  )
+
+The value of :gem is mostly mostly needed if the gem uses autoload or
+other forms of runtime requires.  This allows read access to
+all files in the gem's folder, not just the gem's require paths,
+so it works correctly for gems that access data (e.g. templates)
+outside of the gem's require paths.
+
+If you plan to use pledge and unveil together, you should
+unveil before pledging, unless you use the +unveil+
+promise when pledging.
+
+=== Issues with unveil and File.realpath
+
++Pledge.unveil+ does not work with +File.realpath+ on Ruby <2.7.
+The Ruby ports officially supported by OpenBSD have had support to
+allow them to work together backported, as long as you are running
+OpenBSD 6.6+ (or 6.5-current after July 2019).  As +require+ uses
++File.realpath+, this means in most cases where you would want to
+use the +:gem+ support, it will not actually work correctly unless
+you are using Ruby 2.7+ or an OpenBSD package with the backported
+support.
+
 == Reporting issues/bugs
 
 This library uses GitHub Issues for tracking issues/bugs:
@@ -81,7 +142,7 @@ To get a copy:
 
 == Requirements
 
-* OpenBSD 5.9+
+* OpenBSD 5.9+ (6.4+ for unveil, but 6.6+ recommended)
 * ruby 1.8.7+
 * rake-compiler (if compiling)
 

data/Rakefile

@@ -1,13 +1,7 @@
 require "rake"
 require "rake/clean"
 
-CLEAN.include %w'**.rbc rdoc'
-
-desc "Do a full cleaning"
-task :distclean do
-  CLEAN.include %w'tmp pkg tame*.gem lib/*.so'
-  Rake::Task[:clean].invoke
-end
+CLEAN.include %w'**.rbc rdoc lib/*.so tmp'
 
 desc "Build the gem"
 task :package do

data/ext/pledge/extconf.rb

@@ -1,5 +1,7 @@
 require 'mkmf'
-have_header 'pledge'
+have_header 'unistd.h'
+have_func('pledge') || raise("pledge(2) not present, cannot built extension")
+have_func('unveil')
 $CFLAGS << " -O0 -g -ggdb" if ENV['DEBUG']
 $CFLAGS << " -Wall"
 create_makefile("pledge")

data/ext/pledge/pledge.c

@@ -5,6 +5,7 @@
 static VALUE ePledgeInvalidPromise;
 static VALUE ePledgePermissionIncreaseAttempt;
 static VALUE ePledgeError;
+static VALUE ePledgeUnveilError;
 
 static VALUE rb_pledge(int argc, VALUE* argv, VALUE pledge_class) {
   VALUE promises = Qnil;
@@ -44,6 +45,37 @@ static VALUE rb_pledge(int argc, VALUE* argv, VALUE pledge_class) {
   return Qnil;
 }
 
+#ifdef HAVE_UNVEIL
+static VALUE check_unveil(const char * path, const char * perm) {
+  if (unveil(path, perm) != 0) {
+    switch(errno) {
+    case EINVAL:
+        rb_raise(ePledgeUnveilError, "invalid permissions value");
+    case EPERM:
+        rb_raise(ePledgeUnveilError, "attempt to increase permissions, path not accessible, or unveil already locked");
+    case E2BIG:
+        rb_raise(ePledgeUnveilError, "per-process limit for unveiled paths reached");
+    case ENOENT:
+        rb_raise(ePledgeUnveilError, "directory in the path does not exist");
+    default:
+        rb_raise(ePledgeUnveilError, "unveil error");
+    }
+  }
+
+  return Qnil;
+}
+
+static VALUE rb_unveil(VALUE pledge_class, VALUE path, VALUE perm) {
+  SafeStringValue(path);
+  SafeStringValue(perm);
+  return check_unveil(RSTRING_PTR(path), RSTRING_PTR(perm));
+}
+
+static VALUE rb_finalize_unveil(VALUE pledge_class) {
+  return check_unveil(NULL, NULL);
+}
+#endif
+
 void Init_pledge(void) {
   VALUE cPledge;
   cPledge = rb_define_module("Pledge");
@@ -52,4 +84,10 @@ void Init_pledge(void) {
   ePledgeError = rb_define_class_under(cPledge, "Error", rb_eStandardError);
   ePledgeInvalidPromise = rb_define_class_under(cPledge, "InvalidPromise", ePledgeError);
   ePledgePermissionIncreaseAttempt = rb_define_class_under(cPledge, "PermissionIncreaseAttempt", ePledgeError);
+
+#ifdef HAVE_UNVEIL
+  rb_define_private_method(cPledge, "_unveil", rb_unveil, 2);
+  rb_define_private_method(cPledge, "_finalize_unveil!", rb_finalize_unveil, 0);
+  ePledgeUnveilError = rb_define_class_under(cPledge, "UnveilError", rb_eStandardError);
+#endif
 }

data/lib/unveil.rb

@@ -0,0 +1,64 @@
+# frozen-string-literal: true
+
+require 'pledge'
+raise LoadError, "unveil not supported" unless Pledge.respond_to?(:_unveil, true)
+
+module Pledge
+  # Limit access to the file system using unveil(2).  +paths+ should be a hash
+  # where keys are paths and values are the access permissions for that path.  Each
+  # value should be a string with the following characters specifying what
+  # permissions are allowed:
+  #
+  # r :: Allow read access to existing files and directories
+  # w :: Allow write access to existing files and directories
+  # c :: Allow create/delete access for new files and directories
+  # x :: Allow execute access to programs
+  #
+  # You can use the empty string as permissions if you want to allow no access
+  # to the given path, even if you have granted some access to a folder above
+  # the given folder.  You can use a value of +:gem+ to allow read access to
+  # the directory for the gem specified by the key.
+  #
+  # If called with an empty hash, adds an unveil of +/+ with no permissions,
+  # which denies all access to the file system if +unveil_without_lock+
+  # was not called previously.
+  def unveil(paths)
+    if paths.empty?
+      paths = {'/'=>''}
+    end
+
+    unveil_without_lock(paths)
+    _finalize_unveil!
+  end
+
+  # Same as unveil, but allows for future calls to unveil or unveil_without_lock.
+  def unveil_without_lock(paths)
+    paths = Hash[paths]
+
+    paths.to_a.each do |path, perm|
+      unless path.is_a?(String)
+        raise UnveilError, "unveil path is not a string: #{path.inspect}"
+      end
+
+      case perm
+      when :gem
+        unless spec = Gem.loaded_specs[path]
+          raise UnveilError, "cannot unveil gem #{path} as it is not loaded"
+        end
+
+        paths.delete(path)
+        paths[spec.full_gem_path] = 'r'
+      when String
+        # nothing to do
+      else
+        raise UnveilError, "unveil permission is not a string: #{perm.inspect}"
+      end
+    end
+
+    paths.each do |path, perm|
+      _unveil(path, perm)
+    end
+
+    nil
+  end
+end

data/spec/pledge_spec.rb

@@ -41,7 +41,7 @@ describe "Pledge.pledge" do
     proc{Pledge.pledge("foo")}.must_raise Pledge::InvalidPromise
   end
 
-  it "should raise a Pledge::PermissionIncreaseAttempt if attempting to increase permissinos" do
+  it "should raise a Pledge::PermissionIncreaseAttempt if attempting to increase permissions" do
     pledged("begin; Pledge.pledge('rpath'); rescue Pledge::PermissionIncreaseAttempt; exit 0; end; exit 1")
   end
 
@@ -121,9 +121,9 @@ describe "Pledge.pledge" do
   end
 
   it "should handle both promises and execpromises arguments" do
-    execpledged("proc exec rpath", "stdio rpath", "exit(`cat MIT-LICENSE` == File.read('MIT-LICENSE') ? 0 : 1)").must_equal true
-    execpledged("proc exec", "stdio rpath", "$stderr.reopen('/dev/null', 'w'); exit(`cat MIT-LICENSE` == File.read('MIT-LICENSE') ? 0 : 1)").must_equal false
-    execpledged("proc exec rpath", "stdio", "$stderr.reopen('/dev/null', 'w'); exit(`cat MIT-LICENSE` == File.read('MIT-LICENSE') ? 0 : 1)").must_equal false
+    execpledged("proc exec rpath", "stdio rpath", "exit(`cat MIT-LICENSE` == File.read('MIT-LICENSE'))").must_equal true
+    execpledged("proc exec", "stdio rpath", "$stderr.reopen('/dev/null', 'w'); exit(`cat MIT-LICENSE` == File.read('MIT-LICENSE'))").must_equal false
+    execpledged("proc exec rpath", "stdio", "$stderr.reopen('/dev/null', 'w'); exit(`cat MIT-LICENSE` == File.read('MIT-LICENSE'))").must_equal false
   end
 
   it "should handle nil arguments" do
@@ -133,6 +133,82 @@ describe "Pledge.pledge" do
     execpledged("", nil, "`cat MIT-LICENSE`").must_equal false
     execpledged(nil, "stdio rpath", "`cat MIT-LICENSE`").must_equal true
     execpledged(nil, "stdio", "File.read('MIT-LICENSE')").must_equal true
-    execpledged(nil, "stdio", "$stderr.reopen('/dev/null', 'w'); exit(`cat MIT-LICENSE` == File.read('MIT-LICENSE') ? 0 : 1)").must_equal false
+    execpledged(nil, "stdio", "$stderr.reopen('/dev/null', 'w'); exit(`cat MIT-LICENSE` == File.read('MIT-LICENSE'))").must_equal false
   end
 end
+
+describe "Pledge.unveil" do
+  def unveiled(unveils, code)
+    system(RUBY, '-I', 'lib', '-r', 'unveil', '-e', "Pledge.unveil(#{unveils.inspect}); #{code}")
+  end
+
+  test_file = "spec/#{$$}_test.rb"
+
+  after do
+    File.delete(test_file) if File.file?(test_file)
+  end
+
+  it "should handle unveiling paths" do
+    unveiled({}, "exit(Dir['*'].empty?)").must_equal true
+    unveiled({'.'=>'r'}, "exit(!Dir['*'].empty?)").must_equal true
+
+    test_read = "exit(((File.read('MIT-LICENSE'); true) rescue false))"
+    unveiled({'.'=>'w'}, test_read).must_equal false
+    unveiled({'.'=>'r'}, test_read).must_equal true
+    unveiled({'.'=>'r'}, "exit(((File.open('MIT-LICENSE', 'w'){}; true) rescue false))").must_equal false
+
+    %w'rwxc rwx rwc rxc rx rw rc'.each do |perm|
+      unveiled({'.'=>perm}, test_read).must_equal true
+    end
+
+    %w'wxc wx wc xc x w c'.each do |perm|
+      unveiled({'.'=>perm}, test_read).must_equal false
+    end
+
+    unveiled({'MIT-LICENSE'=>'r'}, test_read).must_equal true
+    unveiled({'Rakefile'=>'r'}, test_read).must_equal false
+    unveiled({'.'=>'r', 'MIT-LICENSE'=>''}, test_read).must_equal false
+    unveiled({}, "Pledge.unveil{} rescue exit(1)").must_equal false
+    system(RUBY, '-I', 'lib', '-r', 'unveil', '-e', "Pledge.unveil_without_lock({'.'=>'r'}); Pledge.unveil({}); #{test_read}").must_equal true
+    system(RUBY, '-I', 'lib', '-r', 'unveil', '-e', "Pledge.unveil('foo/bar'=>'r') rescue exit(1)").must_equal false
+    system(RUBY, '-I', 'lib', '-r', 'unveil', '-e', "Pledge.send(:_unveil, '.', 'f') rescue exit(1)").must_equal false
+    system(RUBY, '-I', 'lib', '-r', 'unveil', '-e', "Pledge.unveil({1=>'s'}) rescue exit(1)").must_equal false
+    system(RUBY, '-I', 'lib', '-r', 'unveil', '-e', "Pledge.unveil({'s'=>1}) rescue exit(1)").must_equal false
+    system(RUBY, '-I', 'lib', '-r', 'unveil', '-e', "Pledge.send(:_unveil, 1, 'r') rescue exit(1)").must_equal false
+    system(RUBY, '-I', 'lib', '-r', 'unveil', '-e', "Pledge.send(:_unveil, '.', 1) rescue exit(1)").must_equal false
+  end
+
+  it "should handle require after unveil with read access after removing from $LOADED_FEATURES" do
+    [File.join('.', test_file), File.join(Dir.pwd, test_file)].each do |f|
+      f = f.inspect
+      system(RUBY, '-I', 'lib', '-r', 'unveil', '-e', <<-END).must_equal true
+        File.open(#{f}, 'w'){|f| f.write '1'}
+        require #{f}
+        Pledge.unveil('spec'=>'r')
+        $LOADED_FEATURES.delete #{f}
+        require #{f}
+      END
+    end
+  end
+
+  it "should handle :gem value to unveil gems" do
+    system(RUBY, '-I', 'lib', '-r', 'unveil', '-e', "$stderr.reopen('/dev/null', 'w'); require 'rubygems'; gem 'minitest'; require 'minitest'; Pledge.unveil({}); require 'minitest/benchmark' rescue exit(1)").must_equal false
+    system(RUBY, '-I', 'lib', '-r', 'unveil', '-e', "require 'rubygems'; gem 'minitest'; require 'minitest'; Pledge.unveil('minitest'=>:gem); require 'minitest/benchmark' rescue (p $!; puts $!.backtrace; exit(1))").must_equal true
+
+    system(RUBY, '-I', 'lib', '-r', 'unveil', '-e', "Pledge.unveil('gadzooks!!!'=>:gem) rescue exit(1)").must_equal false
+  end
+
+  it "should need create and write access for writing new files, and create access for removing files" do
+    unveiled({'.'=>'w'}, "File.open(#{test_file.inspect}, 'w'){|f| f.write '1'} rescue exit(1)").must_equal false
+    File.file?(test_file).must_equal false
+    unveiled({'.'=>'c'}, "File.open(#{test_file.inspect}, 'w'){|f| f.write '1'} rescue exit(1)").must_equal false
+    File.file?(test_file).must_equal false
+    unveiled({'.'=>'cw'}, "File.open(#{test_file.inspect}, 'w'){|f| f.write '1'}").must_equal true
+    File.read(test_file).must_equal '1'
+
+    unveiled({'.'=>'w'}, "File.delete(#{test_file.inspect}) rescue exit(1)").must_equal false
+    File.read(test_file).must_equal '1'
+    unveiled({'.'=>'c'}, "File.delete(#{test_file.inspect})").must_equal true
+    File.file?(test_file).must_equal false
+  end
+end if Pledge.respond_to?(:_unveil, true)

metadata

@@ -1,23 +1,22 @@
 --- !ruby/object:Gem::Specification
 name: pledge
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Jeremy Evans
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-04-25 00:00:00.000000000 Z
+date: 2019-07-07 00:00:00.000000000 Z
 dependencies: []
 description: |
-  pledge exposes OpenBSD's pledge(2) system call to ruby, allowing a
-  program to restrict the types of operations the program
-  can do after that point.  Unlike other similar systems,
-  pledge is specifically designed for programs that need to
-  use a wide variety of operations on initialization, but
-  a fewer number after initialization (when user input will
-  be accepted).
+  pledge exposes OpenBSD's pledge(2) and unveil(2) system calls to Ruby, allowing
+  a program to restrict the types of operations the program can do, and the file
+  system access the program has, after the point of call.  Unlike other similar
+  systems, pledge and unveil are specifically designed for programs that need to
+  use a wide variety of operations on initialization, but a fewer number after
+  initialization (when user input will be accepted).
 email: code@jeremyevans.net
 executables: []
 extensions:
@@ -33,6 +32,7 @@ files:
 - Rakefile
 - ext/pledge/extconf.rb
 - ext/pledge/pledge.c
+- lib/unveil.rb
 - spec/pledge_spec.rb
 homepage: https://github.com/jeremyevans/ruby-pledge
 licenses:
@@ -44,7 +44,7 @@ rdoc_options:
 - "--line-numbers"
 - "--inline-source"
 - "--title"
-- 'pledge: restrict system operations on OpenBSD'
+- 'pledge: restrict system operations and file system access on OpenBSD'
 - "--main"
 - README.rdoc
 require_paths:
@@ -63,5 +63,5 @@ requirements: []
 rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
-summary: Restrict system operations on OpenBSD
+summary: Restrict system operations and file system access on OpenBSD
 test_files: []