bsdcapsicum.rb 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d83ead7ffc798a1957614930e629c867be433fc59a7138327ccae20e2bb35d4
-  data.tar.gz: 9b91b67471e6cd11ebc3eced51face9e8cae9f96136763666e110b175c4a8f55
+  metadata.gz: 68cc91e740a2c2e8586db3884729be9c4fcefe8de403876ff805ac2bdaa3575b
+  data.tar.gz: d71319a3f9a56b63faef409ea27647ea93796eedda15658ad28bf9a9cd395066
 SHA512:
-  metadata.gz: 315f60aad74e7db220c09cedc03fa4072fbd483de4cf851c6351f0df599249fc7752d892fc304636f4ca08d80735c88f7bc366854d4323f582d7406760c9c40a
-  data.tar.gz: ab6a6c0b337f9ddcbf98e97053379bba9c585d51ecc02b1cd72f55ef9add3be5bcf26d3d0da310d939230a9fb2bf66a483f3accefe94e3d4ad8c729efdefbc76
+  metadata.gz: 94b898fee6872449599545d87fd4d52e9231b6e6d7424d58d3bfc7b22e97c84d5b10719821581bc590822e49464703503a284d9205def2ccba65670d300f97d6
+  data.tar.gz: d3d0649cf733bd07ed0e66ee9bf223dbdee5c89a54b609e35583964a216bbd3136f2bfdf0d1988edc705c004ac1a2781a00316f08fd23f639054d83a56637318

data/README.md

@@ -20,9 +20,9 @@ manual page for more details:
 #!/usr/bin/env ruby
 require "bsd/capsicum"
 
-print "In capability mode: ", BSD::Capsicum.in_capability_mode? ? "yes" : "no", "\n"
-print "Enter capability mode: ", BSD::Capsicum.enter! ? "ok" : "error", "\n"
-print "In capability mode: ", BSD::Capsicum.in_capability_mode? ? "yes" : "no", "\n"
+print "In capability mode: ", (BSD::Capsicum.in_capability_mode? ? "yes" : "no"), "\n"
+print "Enter capability mode: ", (BSD::Capsicum.enter! ? "ok" : "error"), "\n"
+print "In capability mode: ", (BSD::Capsicum.in_capability_mode? ? "yes" : "no"), "\n"
 
 begin
   File.new(File::NULL)
@@ -37,7 +37,7 @@ end
 # Error: Not permitted in capability mode @ rb_sysopen - /dev/null (Errno::ECAPMODE)
 ```
 
-__IPC__
+__Child process__
 
 By spawning a child process and then entering capability mode, restrictions can be
 limited to a child process (and its child processes, if any). This can be helpful in
@@ -48,15 +48,15 @@ certain tasks but with restrictions in place:
 #!/usr/bin/env ruby
 require "bsd/capsicum"
 
-print "[parent] In capability mode: ", BSD::Capsicum.in_capability_mode? ? "yes" : "no", "\n"
+print "[parent] In capability mode: ", (BSD::Capsicum.in_capability_mode? ? "yes" : "no"), "\n"
 fork do
-  print "[subprocess] Enter capability mode: ", BSD::Capsicum.enter! ? "ok" : "error", "\n"
-  print "[subprocess] In capability mode: ", BSD::Capsicum.in_capability_mode? ? "yes" : "no", "\n"
+  print "[subprocess] Enter capability mode: ", (BSD::Capsicum.enter! ? "ok" : "error"), "\n"
+  print "[subprocess] In capability mode: ", (BSD::Capsicum.in_capability_mode? ? "yes" : "no"), "\n"
   print "[subprocess] Exit", "\n"
   exit 42
 end
 Process.wait
-print "[parent] In capability mode: ", BSD::Capsicum.in_capability_mode? ? "yes" : "no", "\n"
+print "[parent] In capability mode: ", (BSD::Capsicum.in_capability_mode? ? "yes" : "no"), "\n"
 
 ##
 # [parent] In capability mode: no
@@ -71,8 +71,8 @@ __Rights__
 The
 [BSD::Capsicum.set_rights!](http://0x1eef.github.io/x/bsdcapsicum.rb/BSD/Capsicum.html#set_rights!-instance_method)
 method can reduce the capabilities of a file descriptor. The following
-example obtains a file descriptor in a parent process (with both read and
-write permissions), then limits the capabilities of the file descriptor
+example obtains a file descriptor in a parent process (with full capabilities),
+then limits the capabilities of the file descriptor
 in a child process to allow only read operations. See the
 [rights(4)](https://man.freebsd.org/cgi/man.cgi?query=rights&apropos=0&sektion=4&format=html)
 man page for a full list of capabilities:
@@ -84,13 +84,13 @@ require "bsd/capsicum"
 path = File.join(Dir.home, "bsdcapsicum.txt")
 file = File.open(path, File::CREAT | File::TRUNC | File::RDWR)
 file.sync = true
-print "[parent] obtain file descriptor (with read+write permissions)", "\n"
+print "[parent] Obtain file descriptor (with all capabilities)", "\n"
 fork do
   BSD::Capsicum.set_rights!(file, %i[CAP_READ])
-  print "[subprocess] reduce rights to read-only", "\n"
+  print "[subprocess] Reduce capabilities to read", "\n"
 
   file.gets
-  print "[subprocess] read successful", "\n"
+  print "[subprocess] Read OK", "\n"
 
   begin
     file.write "foo"
@@ -100,14 +100,14 @@ fork do
 end
 Process.wait
 file.write "[parent] Hello from #{Process.pid}", "\n"
-print "[parent] write successful", "\n"
+print "[parent] Write OK", "\n"
 
 ##
-# [parent] obtain file descriptor (with read+write permissions)
-# [subprocess] reduce rights to read-only
-# [subprocess] read successful
+# [parent] Obtain file descriptor (with all capabilities)
+# [subprocess] Reduce capabilities to read
+# [subprocess] Read OK
 # [subprocess] Error: Capabilities insufficient @ io_write - /home/user/bsdcapsicum.txt (Errno::ENOTCAPABLE)
-# [parent] write successful
+# [parent] Write OK
 ```
 
 ## Documentation
@@ -123,7 +123,9 @@ bsdcapsicum.rb is available via rubygems.org:
 ## Sources
 
 * [GitHub](https://github.com/0x1eef/bsdcapsicum.rb#readme)
-* [git.HardenedBSD.org](https://git.hardenedbsd.org/0x1eef/bsdcapsicum.rb#about)
+* [GitLab](https://gitlab.com/0x1eef/bsdcapsicum.rb#about)
+* [git.HardenedBSD.org/@0x1eef](https://git.hardenedbsd.org/0x1eef/bsdcapsicum.rb#about)
+* [brew.bsd.cafe/@0x1eef](https://brew.bsd.cafe/0x1eef/bsdcapsicum.rb)
 
 ## See also
 

data/lib/bsd/capsicum/constants.rb

@@ -91,5 +91,9 @@ module BSD::Capsicum
     CAP_FCHDIR         = 0x200000000000800
     CAP_FCNTL          = 0x200000000008000
     # @endgroup
+
+    # @group Sizes
+    SIZEOF_CAP_RIGHTS_T = 16
+    # @endgroup
   end
 end

data/lib/bsd/capsicum/ffi.rb

@@ -3,8 +3,16 @@
 module BSD::Capsicum
   module FFI
     require "fiddle"
+    require "fiddle/import"
     include Fiddle::Types
     include Constants
+    extend Fiddle::Importer
+    dlload Dir["/lib/libc.*"].first
+
+    extern "int cap_getmode(u_int*)"
+    extern "int cap_enter(void)"
+    extern "int cap_rights_limit(int, const cap_rights_t*)"
+    extern "cap_rights_t* __cap_rights_init(int version, cap_rights_t*, ...)"
 
     module_function
 
@@ -12,11 +20,7 @@ module BSD::Capsicum
     # Provides a Ruby interface for cap_enter(2)
     # @return [Integer]
     def cap_enter
-      Fiddle::Function.new(
-        libc["cap_enter"],
-        [],
-        INT
-      ).call
+      self["cap_enter"].call
     end
 
     ##
@@ -24,45 +28,43 @@ module BSD::Capsicum
     # @param [Fiddle::Pointer] uintp
     # @return [Integer]
     def cap_getmode(uintp)
-      Fiddle::Function.new(
-        libc["cap_getmode"],
-        [INTPTR_T],
-        INT
-      ).call(uintp)
+      self["cap_getmode"].call(uintp)
     end
 
     ##
     # Provides a Ruby interface for cap_rights_limit(2)
     # @param [Integer] fd
-    # @param [Fiddle::Pointer] rights
+    # @param [Fiddle::Pointer] rightsp
     # @return [Integer]
-    def cap_rights_limit(fd, rights)
-      Fiddle::Function.new(
-        libc["cap_rights_limit"],
-        [INT, VOIDP],
-        INT
-      ).call(fd, rights)
+    def cap_rights_limit(fd, rightsp)
+      self["cap_rights_limit"].call(fd, rightsp)
     end
 
     ##
     # Provides a Ruby interface for cap_rights_init(2)
-    # @param [Array<Integer>] rights
+    # @see BSD::Capsicum::Constants See Constants for a full list of capabilities
+    # @param [Fiddle::Pointer] rightsp
+    #  A pointer to initialize the `cap_rights_t` structure
+    # @param [Array<Symbol, Integer>] capabilities
+    #  An allowed set of capabilities
     # @return [Fiddle::Pointer]
-    def cap_rights_init(*rights)
-      voidp = Fiddle::Pointer.malloc(Fiddle::SIZEOF_VOIDP)
-      varargs = rights.flat_map { [ULONG_LONG, (Symbol === _1) ? Constants.const_get(_1) : _1] }
-      Fiddle::Function.new(
-        libc["__cap_rights_init"],
-        [INT, VOIDP, VARIADIC],
-        VOIDP
-      ).call(CAP_RIGHTS_VERSION, voidp, *varargs)
-      voidp
+    #  Returns a pointer to the structure `cap_rights_t`
+    def cap_rights_init(rightsp, *capabilities)
+      self["__cap_rights_init"].call(
+        CAP_RIGHTS_VERSION,
+        rightsp,
+        *capabilities.flat_map { |cap|
+          [ULONG_LONG, cap_all.include?(cap) ? const_get(cap) : cap]
+        }
+      )
     end
 
     ##
     # @api private
-    def libc
-      @libc ||= Fiddle.dlopen Dir["/lib/libc.*"].first
+    # @return [Array<Symbol>]
+    #  Returns all known capabilities
+    def cap_all
+      @cap_all ||= Constants.constants.select { _1.to_s.start_with?("CAP_") }
     end
   end
   private_constant :FFI

data/lib/bsd/capsicum/version.rb

@@ -4,5 +4,5 @@ module BSD
 end unless defined?(BSD)
 
 module BSD::Capsicum
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/bsd/capsicum.rb

@@ -44,26 +44,27 @@ module BSD::Capsicum
   alias_method :enter_capability_mode!, :enter!
 
   ##
-  # Restrict the capabilities of a file descriptor
+  # Limit the capabilities of a file descriptor
   #
   # @see https://man.freebsd.org/cgi/man.cgi?query=cap_rights_limit&apropos=0&sektion=2&format=html cap_rights_limit(2)
   # @see BSD::Capsicum::Constants See Constants for a full list of capabilities
   # @example
-  #   # Restrict capabilities of STDOUT to read / write
+  #   # Limit standard output capabilities to read and write
   #   BSD::Capsicum.set_rights!(STDOUT, %i[CAP_READ CAP_WRITE])
   # @raise [SystemCallError]
   #  Might raise a subclass of SystemCallError
   # @param [#to_i] io
   #  An IO object
-  # @param [Array<String>] rights
+  # @param [Array<Symbol, Integer>] capabilities
   #  An allowed set of capabilities
   # @return [Boolean]
   #  Returns true when successful
-  def set_rights!(io, rights)
-    voidp = FFI.cap_rights_init(*rights)
-    FFI.cap_rights_limit(io.to_i, voidp).zero? ||
+  def set_rights!(io, capabilities)
+    rightsp = Fiddle::Pointer.malloc(Constants::SIZEOF_CAP_RIGHTS_T)
+    FFI.cap_rights_init(rightsp, *capabilities)
+    FFI.cap_rights_limit(io.to_i, rightsp).zero? ||
     raise(SystemCallError.new("cap_rights_limit", Fiddle.last_error))
   ensure
-    voidp.call_free
+    rightsp.call_free
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bsdcapsicum.rb
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Thomas Hurst
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-27 00:00:00.000000000 Z
+date: 2024-07-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fiddle