pledge 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7369f71bb2bfdbbea7dd07d98c86f443b8c0a09ddaf13090c6c0a379c2fe6eed
-  data.tar.gz: bea75bb0d79544311c633aeb04ad7bcb3d2061ace0c6f9f0829e05dd387068e0
+  metadata.gz: f794b6f397a93e9eaabdfff4928f49537fb0a45b55c042c7dc27c46d27918f5a
+  data.tar.gz: a0291c2d672594938292c7a6a83cc111d3c54679ea412c679e28087b8a870a89
 SHA512:
-  metadata.gz: 4031731b34fe1c2497cfa84ffad17b698ada329362cbb0f8730ea2bfa4f094c0429150b92364a8764d04eef1397be3cdb7d70145ccc9ea88b6e0dadb425d36b7
-  data.tar.gz: 3509a67789e3876149e8880bc031fdb0d5df2bf111cd65b7f112132b1dd64696ff38ef9f70efc854d5ba99eb4c83d1256b4d68ba5805e879725fc5e6ed14a735
+  metadata.gz: 9242a1de3c01334a60cb13ab98410dbe533e089228cf1a7a7cfdbb55a6d1ca7614aacbb306974ff85db1165b02a68e292ee9704038e41e9fab5100cccc7b68dc
+  data.tar.gz: e51bf3d1b375e5eba599052423fce0438cb21b3810b8dd38d6a26d7543bba2db8e8547edd0b53bbab99c999dfdead8b6f68e88620cfd9368a0c67bfcdf1c3d37

data/CHANGELOG

@@ -1,3 +1,11 @@
+=== 1.3.0 (2022-12-19)
+
+* Allow installation on platforms not supporting pledge, raising NotImplementedError when calling pledge/unveil methods in that case (jcs) (#3)
+
+=== 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,6 @@
-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'lib/*.so tmp coverage'
 
 desc "Build the gem"
 task :package do
@@ -17,12 +10,20 @@ end
 desc "Run specs"
 task :spec => :compile do
   ruby = ENV['RUBY'] ||= FileUtils::RUBY 
-  sh %{#{ruby} spec/pledge_spec.rb}
+  sh %{#{ruby} #{"-w" if RUBY_VERSION >= '3'} spec/pledge_spec.rb}
 end
 
 desc "Run specs"
 task :default => :spec
 
+desc "Run specs with coverage"
+task :spec_cov => [:compile] do
+  ruby = ENV['RUBY'] ||= FileUtils::RUBY 
+  ENV['COVERAGE'] = '1'
+  FileUtils.rm_rf('coverage')
+  sh %{#{ruby} spec/unveil_spec.rb}
+end
+
 begin
   require 'rake/extensiontask'
   Rake::ExtensionTask.new('pledge')

data/ext/pledge/extconf.rb

@@ -1,5 +1,7 @@
 require 'mkmf'
-have_header 'pledge'
+have_header 'unistd.h'
+have_func('pledge')
+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;
@@ -12,6 +13,7 @@ static VALUE rb_pledge(int argc, VALUE* argv, VALUE pledge_class) {
   const char * prom = NULL;
   const char * execprom = NULL;
 
+#ifdef HAVE_PLEDGE
   rb_scan_args(argc, argv, "11", &promises, &execpromises);
 
   if (!NIL_P(promises)) {
@@ -40,10 +42,44 @@ static VALUE rb_pledge(int argc, VALUE* argv, VALUE pledge_class) {
         rb_raise(ePledgeError, "pledge error");
     }
   }
+#else
+  rb_raise(rb_eNotImpError, "pledge not supported");
+#endif
 
   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 +88,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,71 @@
+# frozen-string-literal: true
+
+require_relative 'pledge'
+
+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)
+    # :nocov:
+    raise NotImplementedError, "unveil not supported" unless Pledge.respond_to?(:_unveil, true)
+    # :nocov:
+
+    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)
+    # :nocov:
+    raise NotImplementedError, "unveil not supported" unless Pledge.respond_to?(:_unveil, true)
+    # :nocov:
+
+    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

@@ -1,11 +1,4 @@
-require './lib/pledge'
-
-require 'rubygems'
-ENV['MT_NO_PLUGINS'] = '1' # Work around stupid autoloading of plugins
-gem 'minitest'
-require 'minitest/autorun'
-
-RUBY = ENV['RUBY'] || 'ruby'
+require_relative 'unveil_spec'
 
 describe "Pledge.pledge" do
   def execpledged(promises, execpromises, code)
@@ -41,7 +34,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
 
@@ -73,8 +66,8 @@ describe "Pledge.pledge" do
 
   it "should allow dns lookups if dns is used" do
     with_lib('socket') do
-      unpledged("Socket.gethostbyname('google.com')")
-      pledged("Socket.gethostbyname('google.com')", "dns")
+      unpledged("Addrinfo.getaddrinfo('google.com', nil)")
+      pledged("Addrinfo.getaddrinfo('google.com', nil)", "dns")
     end
   end
 
@@ -121,9 +114,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 +126,6 @@ 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

metadata

@@ -1,23 +1,50 @@
 --- !ruby/object:Gem::Specification
 name: pledge
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Jeremy Evans
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2019-04-25 00:00:00.000000000 Z
-dependencies: []
+date: 2022-12-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest-global_expectations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 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,18 +60,19 @@ 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:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options:
 - "--quiet"
 - "--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:
@@ -53,15 +81,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 1.8.7
+      version: 1.9.2
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.3.26
+signing_key:
 specification_version: 4
-summary: Restrict system operations on OpenBSD
+summary: Restrict system operations and file system access on OpenBSD
 test_files: []