bsdcapsicum.rb 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5d83ead7ffc798a1957614930e629c867be433fc59a7138327ccae20e2bb35d4
+  data.tar.gz: 9b91b67471e6cd11ebc3eced51face9e8cae9f96136763666e110b175c4a8f55
+SHA512:
+  metadata.gz: 315f60aad74e7db220c09cedc03fa4072fbd483de4cf851c6351f0df599249fc7752d892fc304636f4ca08d80735c88f7bc366854d4323f582d7406760c9c40a
+  data.tar.gz: ab6a6c0b337f9ddcbf98e97053379bba9c585d51ecc02b1cd72f55ef9add3be5bcf26d3d0da310d939230a9fb2bf66a483f3accefe94e3d4ad8c729efdefbc76

data/LICENSE

@@ -0,0 +1,15 @@
+Copyright (C) 2023 by 0x1eef <0x1eef@protonmail.com>
+
+Permission to use, copy, modify, and/or distribute this
+software for any purpose with or without fee is hereby
+granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS
+ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
+EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
+RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
+OF THIS SOFTWARE.

data/LICENSE.ruby-capsicum

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Thomas Hurst
+
+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,147 @@
+## About
+
+bsdcapsicum.rb provides Ruby bindings for
+[capsicum(4)](https://man.freebsd.org/cgi/man.cgi?query=capsicum&apropos=0&sektion=4&format=html).
+
+## Examples
+
+__Capability mode__
+
+A process can enter into capability mode by calling
+[BSD::Capsicum.enter!](http://0x1eef.github.io/x/bsdcapsicum.rb/BSD/Capsicum.html#enter!-instance_method).
+After entering capability mode, the process has limited
+abilities. File descriptors acquired before entering into
+capability mode remain accessible and unrestricted, but
+their capabilites can be reduced. See the
+[cap_enter(2)](https://man.freebsd.org/cgi/man.cgi?query=cap_enter&apropos=0&sektion=2&format=html)
+manual page for more details:
+
+```ruby
+#!/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"
+
+begin
+  File.new(File::NULL)
+rescue Errno::ECAPMODE => ex
+  print "Error: #{ex.message} (#{ex.class})", "\n"
+end
+
+##
+# In capability mode: no
+# Enter capability mode: ok
+# In capability mode: yes
+# Error: Not permitted in capability mode @ rb_sysopen - /dev/null (Errno::ECAPMODE)
+```
+
+__IPC__
+
+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
+an architecture where a parent process can spawn one or more child processes to handle
+certain tasks but with restrictions in place:
+
+```ruby
+#!/usr/bin/env ruby
+require "bsd/capsicum"
+
+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] Exit", "\n"
+  exit 42
+end
+Process.wait
+print "[parent] In capability mode: ", BSD::Capsicum.in_capability_mode? ? "yes" : "no", "\n"
+
+##
+# [parent] In capability mode: no
+# [subprocess] Enter capability mode: ok
+# [subprocess] In capability mode: yes
+# [subprocess] Exit
+# [parent] In capability mode: no
+```
+
+__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
+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:
+
+``` ruby
+#!/usr/bin/env ruby
+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"
+fork do
+  BSD::Capsicum.set_rights!(file, %i[CAP_READ])
+  print "[subprocess] reduce rights to read-only", "\n"
+
+  file.gets
+  print "[subprocess] read successful", "\n"
+
+  begin
+    file.write "foo"
+  rescue Errno::ENOTCAPABLE => ex
+    print "[subprocess] Error: #{ex.message} (#{ex.class})", "\n"
+  end
+end
+Process.wait
+file.write "[parent] Hello from #{Process.pid}", "\n"
+print "[parent] write successful", "\n"
+
+##
+# [parent] obtain file descriptor (with read+write permissions)
+# [subprocess] reduce rights to read-only
+# [subprocess] read successful
+# [subprocess] Error: Capabilities insufficient @ io_write - /home/user/bsdcapsicum.txt (Errno::ENOTCAPABLE)
+# [parent] write successful
+```
+
+## Documentation
+
+A complete API reference is available at [0x1eef.github.io/x/bsdcapsicum.rb](https://0x1eef.github.io/x/bsdcapsicum.rb)
+
+## Install
+
+bsdcapsicum.rb is available via rubygems.org:
+
+    gem install bsdcapsicum.rb
+
+## Sources
+
+* [GitHub](https://github.com/0x1eef/bsdcapsicum.rb#readme)
+* [git.HardenedBSD.org](https://git.hardenedbsd.org/0x1eef/bsdcapsicum.rb#about)
+
+## See also
+
+* [Freaky/ruby-capsicum](https://github.com/Freaky/ruby-capsicum) <br>
+  bsdcapsicum.rb is a fork of this project. It was a huge help both
+  in terms of code and documentation.
+
+## License
+
+bsdcapsicum.rb
+<br>
+[BSD Zero Clause](https://choosealicense.com/licenses/0bsd/)
+<br>
+See [LICENSE](./LICENSE)
+<br><br>
+ruby-capsicum
+<br>
+[Freaky/ruby-capsicum](https://github.com/Freaky/ruby-capsicum) is released
+under the terms of the MIT license
+<br>
+See [LICENSE.ruby-capsicum](/.LICENSE-ruby-capsicum)

data/bsdcapsicum.rb.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'bsd/capsicum/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "bsdcapsicum.rb"
+  spec.version       = BSD::Capsicum::VERSION
+  spec.authors       = ["Thomas Hurst", "0x1eef"]
+  spec.email         = ["0x1eef@protonmail.com"]
+
+  spec.summary       = "Ruby bindings for FreeBSD's capsicum(4)"
+  spec.homepage      = "https://github.com/0x1eef/bsdcapsicum.rb"
+  spec.licenses      = ["0BSD", "MIT"]
+  spec.files         = Dir["lib/*.rb", "lib/**/*.rb", "README.md", "LICENSE", "LICENSE.ruby-capsicum", "*.gemspec"]
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "fiddle", "~> 1.1"
+  spec.add_development_dependency "bundler", "~> 2.5"
+  spec.add_development_dependency "rake", "~> 13.2"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "standard", "~> 1.38"
+  spec.add_development_dependency "test-cmd.rb", "~> 0.12"
+  spec.add_development_dependency "xchan.rb", "~> 0.17"
+end

data/lib/bsd/capsicum/constants.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module BSD::Capsicum
+  ##
+  # The constants found in this module are defined
+  # by sys/capsicum.h and sys/caprights.h. Their
+  # documentation can be found in the
+  # [rights(4)](https://man.freebsd.org/cgi/man.cgi?query=rights&apropos=0&sektion=4&format=html)
+  # man page
+  module Constants
+    CAP_RIGHTS_VERSION = 0x0
+
+    ##
+    # @group File capabilties
+    CAP_READ           = 0x200000000000001
+    CAP_WRITE          = 0x200000000000002
+    CAP_SEEK           = 0x20000000000000c
+    CAP_PREAD          = 0x20000000000000d
+    CAP_PWRITE         = 0x20000000000000e
+    CAP_MMAP           = 0x200000000000010
+    CAP_CREATE         = 0x200000000000040
+    CAP_FEXECVE        = 0x200000000000080
+    CAP_FSYNC          = 0x200000000000100
+    CAP_FTRUNCATE      = 0x200000000000200
+    CAP_FCHFLAGS       = 0x200000000001000
+    CAP_FCHMOD         = 0x200000000002000
+    CAP_FCHMODAT       = 0x200000000002400
+    CAP_FCHOWN         = 0x200000000004000
+    CAP_FCHOWNAT       = 0x200000000004400
+    CAP_FLOCK          = 0x200000000010000
+    CAP_FPATHCONF      = 0x200000000020000
+    CAP_FSTAT          = 0x200000000080000
+    CAP_FSTATAT        = 0x200000000080400
+    CAP_FSTATFS        = 0x200000000100000
+    CAP_FUTIMES        = 0x200000000200000
+    CAP_FUTIMESAT      = 0x200000000200400
+    # @endgroup
+
+    ##
+    # @group Socket capabilities
+    CAP_ACCEPT         = 0x200000020000000
+    CAP_BIND           = 0x200000040000000
+    CAP_CONNECT        = 0x200000080000000
+    CAP_GETPEERNAME    = 0x200000100000000
+    CAP_GETSOCKNAME    = 0x200000200000000
+    CAP_GETSOCKOPT     = 0x200000400000000
+    CAP_LISTEN         = 0x200000800000000
+    CAP_PEELOFF        = 0x200001000000000
+    CAP_RECV           = CAP_READ
+    CAP_SEND           = CAP_WRITE
+    CAP_SETSOCKOPT     = 0x200002000000000
+    CAP_SHUTDOWN       = 0x200004000000000
+    CAP_BINDAT         = 0x200008000000400
+    CAP_SOCK_CLIENT    = 0x200007780000003
+    CAP_SOCK_SERVER    = 0x200007f60000003
+    # @endgroup
+
+    ##
+    # @group ACL capabilities
+    CAP_ACL_CHECK      = 0x400000000010000
+    CAP_ACL_DELETE     = 0x400000000020000
+    CAP_ACL_GET        = 0x400000000040000
+    CAP_ACL_SET        = 0x400000000080000
+    # @endgroup
+
+    ##
+    # @group Process capabilities
+    CAP_PDGETPID       = 0x400000000000200
+    CAP_PDKILL         = 0x400000000000800
+    CAP_PDWAIT         = 0x400000000000400
+    # @endgroup
+
+    ##
+    # @group Uncategorized capabilities
+    CAP_CHFLAGSAT      = 0x200000000001400
+    CAP_EVENT          = 0x400000000000020
+    CAP_IOCTL          = 0x400000000000080
+    CAP_KQUEUE         = 0x400000000100040
+    CAP_LOOKUP         = 0x200000000000400
+    CAP_MAC_GET        = 0x400000000000001
+    CAP_MAC_SET        = 0x400000000000002
+    CAP_MKDIRAT        = 0x200000000800400
+    CAP_MKFIFOAT       = 0x200000001000400
+    CAP_MKNODAT        = 0x200000002000400
+    CAP_SEM_GETVALUE   = 0x400000000000004
+    CAP_SEM_POST       = 0x400000000000008
+    CAP_SEM_WAIT       = 0x400000000000010
+    CAP_TTYHOOK        = 0x400000000000100
+    CAP_UNLINKAT       = 0x200000010000400
+    CAP_FSCK           = 0x200000000040000
+    CAP_FCHDIR         = 0x200000000000800
+    CAP_FCNTL          = 0x200000000008000
+    # @endgroup
+  end
+end

data/lib/bsd/capsicum/ffi.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module BSD::Capsicum
+  module FFI
+    require "fiddle"
+    include Fiddle::Types
+    include Constants
+
+    module_function
+
+    ##
+    # Provides a Ruby interface for cap_enter(2)
+    # @return [Integer]
+    def cap_enter
+      Fiddle::Function.new(
+        libc["cap_enter"],
+        [],
+        INT
+      ).call
+    end
+
+    ##
+    # Provides a Ruby interface for cap_getmode(2)
+    # @param [Fiddle::Pointer] uintp
+    # @return [Integer]
+    def cap_getmode(uintp)
+      Fiddle::Function.new(
+        libc["cap_getmode"],
+        [INTPTR_T],
+        INT
+      ).call(uintp)
+    end
+
+    ##
+    # Provides a Ruby interface for cap_rights_limit(2)
+    # @param [Integer] fd
+    # @param [Fiddle::Pointer] rights
+    # @return [Integer]
+    def cap_rights_limit(fd, rights)
+      Fiddle::Function.new(
+        libc["cap_rights_limit"],
+        [INT, VOIDP],
+        INT
+      ).call(fd, rights)
+    end
+
+    ##
+    # Provides a Ruby interface for cap_rights_init(2)
+    # @param [Array<Integer>] rights
+    # @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
+    end
+
+    ##
+    # @api private
+    def libc
+      @libc ||= Fiddle.dlopen Dir["/lib/libc.*"].first
+    end
+  end
+  private_constant :FFI
+end

data/lib/bsd/capsicum/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module BSD
+end unless defined?(BSD)
+
+module BSD::Capsicum
+  VERSION = "0.2.0"
+end

data/lib/bsd/capsicum.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module BSD
+end unless defined?(BSD)
+
+module BSD::Capsicum
+  require_relative "capsicum/version"
+  require_relative "capsicum/constants"
+  require_relative "capsicum/ffi"
+  extend self
+
+  ##
+  # Check if we're in capability mode
+  #
+  # @see https://man.freebsd.org/cgi/man.cgi?query=cap_getmode&apropos=0&sektion=2&format=html cap_getmode(2)
+  # @raise [SystemCallError]
+  #  Might raise a subclass of SystemCallError
+  # @return [Boolean]
+  #  Returns true when the current process is in capability mode
+  def in_capability_mode?
+    uintp = Fiddle::Pointer.malloc(Fiddle::SIZEOF_UINT)
+    if FFI.cap_getmode(uintp).zero?
+      uintp[0, Fiddle::SIZEOF_UINT].unpack("i") == [1]
+    else
+      raise SystemCallError.new("cap_getmode", Fiddle.last_error)
+    end
+  ensure
+    uintp.call_free
+  end
+  alias_method :capability_mode?, :in_capability_mode?
+
+  ##
+  # Enter a process into capability mode
+  #
+  # @see https://man.freebsd.org/cgi/man.cgi?query=cap_enter&apropos=0&sektion=2&format=html cap_enter(2)
+  # @raise [SystemCallError]
+  #  Might raise a subclass of SystemCallError
+  # @return [Boolean]
+  #  Returns true when successful
+  def enter!
+    FFI.cap_enter.zero? ||
+    raise(SystemCallError.new("cap_enter", Fiddle.last_error))
+  end
+  alias_method :enter_capability_mode!, :enter!
+
+  ##
+  # Restrict 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
+  #   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
+  #  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? ||
+    raise(SystemCallError.new("cap_rights_limit", Fiddle.last_error))
+  ensure
+    voidp.call_free
+  end
+end

data/lib/bsdcapsicum.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "bsd/capsicum"

metadata

@@ -0,0 +1,152 @@
+--- !ruby/object:Gem::Specification
+name: bsdcapsicum.rb
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Thomas Hurst
+- '0x1eef'
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-06-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fiddle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.38'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.38'
+- !ruby/object:Gem::Dependency
+  name: test-cmd.rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: xchan.rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.17'
+description:
+email:
+- 0x1eef@protonmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- LICENSE.ruby-capsicum
+- README.md
+- bsdcapsicum.rb.gemspec
+- lib/bsd/capsicum.rb
+- lib/bsd/capsicum/constants.rb
+- lib/bsd/capsicum/ffi.rb
+- lib/bsd/capsicum/version.rb
+- lib/bsdcapsicum.rb
+homepage: https://github.com/0x1eef/bsdcapsicum.rb
+licenses:
+- 0BSD
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Ruby bindings for FreeBSD's capsicum(4)
+test_files: []