memory_locker 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f3a6f1d81fcec94948578a19104e6465844402d3a58c2379b8c9a02e973fe8a
-  data.tar.gz: 0c5133932a48f4409961bc2fc6beeb53c28b183f754497166ff401eabecc7c03
+  metadata.gz: cf1ecf9a93e9fd2ef3cf96d45489c2663704fba61001726fc362343cfaad5082
+  data.tar.gz: aafb584707726f4307a1bac47cd4095dae0d7a5bac7acd843cb31e895aa94db9
 SHA512:
-  metadata.gz: 8f6c0e2f07e918f1971f7d0c7f1ddd5c8f82c42e438e796b5c829e46856371dbeaf7716c59f784541b7ee2f43e59648088ee7f65c4195d3df884fb192fe79f94
-  data.tar.gz: 76494e83446a77fdc49b45c4c6ba51a59a1aafb64f238052c053b3bfcf8c80cb025a7dfddaa0bc9a1513a7730b2c2b13a5c371877dee53d2680fc406325f474a
+  metadata.gz: b0197269a2b177801c35ad9107ccedc6d45b01f5e2f91594909b081894d21833288573059c62e4195fe6e1ad4ba3dd501e6fb24545b6ed7219e424b7024a8f6b
+  data.tar.gz: fd22371427af738e0a4d52232f70bbc72f4f8be412fb655019ad858b91675afcaccb53b8fb915759a67f3728ced819c16edc1e810761d4c6ce4b2b1e6f6051ac

data/README.md

@@ -1,54 +1,71 @@
 # MemoryLocker
+[![Gem Version](https://badge.fury.io/rb/memory_locker.svg)](https://badge.fury.io/rb/memory_locker)
 
 Lock memory containing sensitive data (such as passwords or cryptographic keys) to prevent it from being swapped
 by the kernel, which allows the attacker with access to swap space to recover secrets.
 
-Ruby doesn't allow granular memory management, therefore the approach is to lock the entire memory of a program.
+## How it works
+
+Ruby doesn't allow granular memory management, therefore the approach is to lock the entire memory of a current
+process using `mlockall()`.
+
+The memory will stay locked until the process terminates. Although unlocking memory is technically possible,
+the gem doesn't allow it. The reason is Ruby doesn't support reliable removal of secrets from memory,
+therefore it is safer to just keep memory locked.
+
+Warning: if your app leaks memory, it won't be swapped and at some point may be killed by the kernel.
+
+Subprocesses don't inherit memory locking. Make sure to lock memory in each one of them if they handle sensitive data.
 
 ## Requirements
 
-This gem requires `ffi` gem, which needs to be built on install.
+This gem requires [ffi gem](https://github.com/ffi/ffi), which needs to be built on install.
 In case of build-related issues, make sure you have the compiler installed.
+Refer to gem documentation for instructions.
 
-In Debian-based Linux distributions, you can install it by executing:
+Also, an OS supporting `mlockall()` is required. Those include most Unixes except macOS. Windows is not supported.
 
-    $ sudo apt install --no-install-recommends build-essential
+## Installation
 
-Refer to [ffi gem documentation](https://github.com/ffi/ffi) for requirements on other systems.
+    $ gem install memory_locker
 
-## Installation
+## Usage
 
-Install the gem and add it to the application's Gemfile by executing:
+### Enforced installation
 
-    $ bundle add memory_locker
+To lock the memory of your process, add the following code early in the app lifetime:
 
-If the bundler is not being used to manage dependencies, install the gem by executing:
+    require 'memory_locker'
+    MemoryLocker.call
 
-    $ gem install memory_locker
+### Optional installation
 
-## Usage
+If you don't want to force the user to install `memory_locker` gem, you can make it optional.
+If the user doesn't have it installed, the warning will appear, but your app will run.
 
-To lock the memory of the current process use the following once, whenever you want,
-but before sensitive data processing:
+    begin
+      require 'memory_locker'
+    rescue LoadError
+      warn 'Failed to lock memory. To fix install `memory_locker` gem.'
+    else
+      MemoryLocker.call
+    end
 
-    MemoryLocker.new(:glibc).lock!
+## Exceptions
 
-The above example uses the `glibc` backend which should work on most Linux distributions.
-Currently, only this backend is implemented, however, it is trivial to add support for other c-libraries.
+If your OS is unsupported or there was a locking error, you will get an exception descending from MemoryLocker::Error.
 
-The memory will stay locked until the process terminates. There is no way to unlock memory.
-The reason is Ruby doesn't support reliable removal of secrets from memory, therefore it is safer to just
-keep memory locked.
+## Testing
+
+Locking the memory of your app when testing is not needed, and if you use an unsupported OS will brake your app.
+
+As only the `#call` method is being used, you can easily replace `MemoryLocker` with empty lambda `->{}`.
 
 ## Development
 
 After checking out the repo, run `bundle install` to install dependencies. Then, run `rake spec` to run the tests.
 You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To implement the backend for a different c-library, use existing one as a template.
-Copy `lib/memory_locker/glibc.rb` to `lib/memory_locker/my_backend.rb`, and change it.
-Later use `:my_backend` as an argument to `MemoryLocker` initializer.
-
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the
 version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version,
 push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
@@ -65,5 +82,5 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the MemoryLocker project's codebases, issue trackers, chat rooms, and mailing lists
-is expected to follow the [code of conduct](https://github.com/phantom-node/memory_locker/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the MemoryLocker project's codebases, issue trackers, chat rooms, and mailing lists is
+expected to follow the [code of conduct](https://github.com/phantom-node/memory_locker/blob/master/CODE_OF_CONDUCT.md).

data/lib/memory_locker/libc.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class MemoryLocker
+  # Low level interface to libc
+  module Libc
+    # Those values should remain the same on all POSIX systems
+    MCL_CURRENT = 1
+    MCL_FUTURE = 2
+
+    extend FFI::Library
+    # Try to load already loaded libc from the current process, use system libc as a fallback
+    ffi_lib [FFI::CURRENT_PROCESS, FFI::Library::LIBC], FFI::Library::LIBC
+    attach_function :real_mlockall, :mlockall, [:int], :int
+
+    def self.mlockall
+      result = real_mlockall(MCL_CURRENT | MCL_FUTURE)
+      [result, FFI.errno]
+    end
+  end
+
+  private_constant :Libc
+end

data/lib/memory_locker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class MemoryLocker
-  VERSION = '0.1.0'
+  VERSION = '1.0.0'
 end

data/lib/memory_locker.rb

@@ -7,17 +7,33 @@ require 'ffi'
 # It is implemented as a one-way operation: there is no unlock.
 # That's because it's hard to properly clean memory in Ruby.
 class MemoryLocker
-  LockingError = Class.new StandardError
+  Error             = Class.new StandardError
+  UnsupportedError  = Class.new Error
+  LibcNotFoundError = Class.new Error
+  LockingError      = Class.new Error
 
-  def lock!
-    Backend.lock! || raise(LockingError, "Failed to lock memory, errno #{FFI.errno}")
+  def call
+    result, errno = libc.mlockall
+    raise LockingError, "Locking of memory failed with errno #{errno}" unless result.zero?
+  end
+
+  def self.call
+    new.call
   end
 
   private
 
-  attr_reader :backend
+  attr_reader :libc
 
-  def initialize(backend)
-    require_relative "memory_locker/#{backend}"
+  def initialize(libc_loader: -> { require_relative 'memory_locker/libc' },
+                 libc_fetcher: -> { Libc },
+                 unsupported_error: FFI::NotFoundError,
+                 libc_not_found_error: LoadError)
+    libc_loader.call
+    @libc = libc_fetcher.call
+  rescue unsupported_error => e
+    raise UnsupportedError, 'System does not support mlockall()', cause: e
+  rescue libc_not_found_error => e
+    raise LibcNotFoundError, 'Failed to find C library', cause: e
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: memory_locker
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Paweł Pokrywka
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-07-27 00:00:00.000000000 Z
+date: 2023-07-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -35,7 +35,7 @@ files:
 - LICENSE.txt
 - README.md
 - lib/memory_locker.rb
-- lib/memory_locker/glibc.rb
+- lib/memory_locker/libc.rb
 - lib/memory_locker/version.rb
 homepage: https://github.com/phantom-node/memory_locker
 licenses:

data/lib/memory_locker/glibc.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-class MemoryLocker
-  # Low level interface to glibc
-  module Backend
-    extend FFI::Library
-    ffi_lib 'libc.so.6'
-
-    MCL_CURRENT = 1
-    MCL_FUTURE = 2
-
-    attach_function :mlockall, [:int], :int
-
-    def self.lock!
-      mlockall(MCL_CURRENT | MCL_FUTURE).zero?
-    end
-  end
-end