secret_string 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '059dcb7dea1885b6f2b24c01c70567028e24cf9d4a916e607ce98d3a8ec5baab'
+  data.tar.gz: 4fc32cecd334d8cddbe7f577b5997a09c437b8d89c2d61f243db0aac137ebdb8
+SHA512:
+  metadata.gz: ae6503a05ddb781a1f79235630228e86c0b3c42984c43f4cbae9b331c1e7b3d456b604a523b3d4123de44b7434aea6aa4ec1c70e24410ac941d6481f7100de0c
+  data.tar.gz: 7725fe9c2bc7c17276b380ad75d68587958d1fcc6efaa1c8ed1d2591c971b91e8832966d745380933b309524ef8981409af04dd73ef59564aa8d1b0f9f9058fb

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# [v0.0.1](https://github.com/Muriel-Salvan/secret_string/compare/...v0.0.1) (2021-06-28 16:06:53)
+
+### Patches
+
+* [Set Ruby 2.7](https://github.com/Muriel-Salvan/secret_string/commit/8c641d864d8c951fd6a40f36a614a070b66630b8)

data/LICENSE.md

@@ -0,0 +1,31 @@
+
+The license stated herein is a copy of the BSD License (modified on July 1999).
+The AUTHOR mentionned below refers to the list of people involved in the
+creation and modification of any file included in the delivered package.
+This list is found in the file named AUTHORS.
+The AUTHORS and LICENSE files have to be included in any release of software
+embedding source code of this package, or using it as a derivative software.
+
+Copyright (c) 2021 Muriel Salvan (muriel@x-aeon.com)
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+   1. Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+   2. Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the documentation
+      and/or other materials provided with the distribution.
+   3. The name of the author may not be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
+EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
+OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
+OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,158 @@
+[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
+
+# secret_string - Remove secrets (passwords, keys...) from memory
+
+## Description
+
+This Rubygem gives you ways to clean sensitive data (secrets, SSH keys, passwords) from your Ruby String variables in memory.
+
+## Install
+
+Via gem
+
+``` bash
+$ gem install secret_string
+```
+
+If using `bundler`, add this in your `Gemfile`:
+
+``` ruby
+gem 'secret_string'
+```
+
+## Usage
+
+### With a protecting scope
+
+The simplest and more robust way to use it is with the `SecretString.protect` method that gives a scope for a secret to be used from a String and will make sure this secret is removed from memory when code ends.
+
+Example:
+```ruby
+require 'secret_string'
+
+secret = 'P4$Sw0rD' # Usually retrieved from a file, ENV var, user input...
+
+# Create the protected scope
+SecretString.protect(secret) do |secret_string|
+
+  # Let's try to display the password
+  puts "Password on screen is #{secret_string}"
+  # => Password on screen is XXXXX
+
+  # Its value can still be accessed using to_unprotected
+  puts "If we REALLY want to display it or use its real secret value somewhere: #{secret_string.to_unprotected}"
+  # => If we REALLY want to display it or use its real secret value somewhere: P4$Sw0rD
+
+end
+
+# Now that we are out of the protected scope, let's try leetch its value again!
+puts "Outside of protection, my secret from memory is now #{secret}"
+# => Outside of protection, my secret from memory is now
+```
+
+You can also control the silenced secret, in case you still need to display it in logs or messages:
+```ruby
+require 'secret_string'
+
+SecretString.protect('P4$Sw0rD', silenced_str: '<FAKE PASSWORD>') do |secret_string|
+  # Let's try to display the password
+  puts "Password on screen is #{secret_string}"
+  # => Password on screen is <FAKE PASSWORD>
+end
+```
+
+### With the `SecretString` class
+
+If you need more control (like having a simple scope is not enough), you can directly use the `SecureString` class to protect your strings.
+If you do so, don't forget to call the `erase` method to clean their data, and make sure you didn't clone the secret in other variables.
+
+Example:
+```ruby
+require 'secret_string'
+
+my_secret = SecretString.new('P4$Sw0rD', silenced_str: '<FAKE PASSWORD>')
+
+puts "My secret handled without precaution is #{my_secret}"
+# => My secret handled without precaution is <FAKE PASSWORD>
+
+puts "My secret when I REALLY want its value is #{my_secret.to_unprotected}"
+# => My secret when I REALLY want its value is P4$Sw0rD
+
+my_secret.erase
+
+puts "My secret after being erased is #{my_secret.to_unprotected}"
+# => My secret after being erased is
+```
+
+### Dealing directly with original Strings
+
+You can erase any Ruby String using `SecretString.erase` method:
+
+```ruby
+require 'secret_string'
+
+my_secret = 'P4$Sw0rD'
+
+puts "My secret before erase is #{my_secret}"
+# => My secret before erase is P4$Sw0rD
+
+SecretString.erase(my_secret)
+
+puts "My secret after being erased is #{my_secret}"
+# => My secret after being erased is
+```
+
+The `erase` and `to_unprotected` methods have also been added to the core String class so that you can treat both `String` and `SecretString` easily within your code logic (no need to plague your code with `if str.is_a?(SecureString)`). Those methods won't do or change anything to the normal Ruby Strings.
+
+Example:
+```ruby
+require 'secret_string'
+
+strings = [
+  'Normal string',
+  SecretString.new('Secret: P4$Sw0rD', silenced_str: 'Secret: NO WAY')
+]
+
+puts "My strings are: #{strings}"
+# => My strings are: ["Normal string", "Secret: NO WAY"]
+
+puts "My unprotected strings are: #{strings.map(&:to_unprotected)}"
+# => My unprotected strings are: ["Normal string", "Secret: P4$Sw0rD"
+```
+
+## Change log
+
+Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
+
+## Testing
+
+Automated tests are done using rspec.
+
+To execute them, first install development dependencies:
+
+```bash
+bundle install
+```
+
+Then execute rspec
+
+```bash
+bundle exec rspec
+```
+
+Manual testing has been done using `gdb` to effectively check that a Ruby process dumping its full memory on disk does not reveal secrets once erased by `SecretString` (tested on Ruby 2.7).
+
+## Contributing
+
+Any contribution is welcome:
+* Fork the github project and create pull requests.
+* Report bugs by creating tickets.
+* Suggest improvements and new features by creating tickets.
+
+## Credits
+
+- [Muriel Salvan](https://x-aeon.com/muriel)
+
+## License
+
+The BSD License. Please see [License File](LICENSE.md) for more information.

data/lib/secret_string.rb

@@ -0,0 +1,69 @@
+require 'forwardable'
+require 'stringio'
+require 'secret_string/core_extensions/string'
+
+# Protect sensitive data in Strings by erasing it from memory when not needed anymore.
+class SecretString
+
+  class << self
+
+    # Securely erase a String from memory
+    #
+    # Parameters::
+    # * *secret* (String): The secret to erase from memory
+    def erase(secret)
+      secret_size = secret.bytesize
+      io = StringIO.new("\0" * secret_size)
+      io.read(secret_size, secret)
+    end
+
+    # Protect a String by giving access only to a secured version of it.
+    # Make sure the String will be erased at the end of its access.
+    #
+    # Parameters::
+    # * *str* (String): String to protect
+    # * *silenced_str* (String): The protected representation of this string [default: 'XXXXX']
+    # * Proc: Code called with the string secured
+    #   * Parameters::
+    #     * *secretstring* (SecretString): The secret string
+    def protect(str, silenced_str: 'XXXXX')
+      secret_string = SecretString.new(str, silenced_str: silenced_str)
+      yield secret_string
+    ensure
+      secret_string.erase
+    end
+
+  end
+
+  # Constructor
+  #
+  # Parameters::
+  # * *str* (String): The original string to protect
+  # * *silenced_str* (String): The silenced representation of this string [default: 'XXXXX']
+  def initialize(str, silenced_str: 'XXXXX')
+    @str = str
+    # Make sure we manipulate @str without cloning or modifying it from now on.
+    @silenced_str = silenced_str
+  end
+
+  # Delegate the String representations methods to the silenced String by default
+  extend Forwardable
+  def_delegators :@silenced_str, *%i[
+    inspect
+    to_s
+  ]
+
+  # Return the unprotected String
+  #
+  # Result::
+  # * String: Unprotected string
+  def to_unprotected
+    @str
+  end
+
+  # Erase the string
+  def erase
+    SecretString.erase(@str)
+  end
+
+end

data/lib/secret_string/core_extensions/string.rb

@@ -0,0 +1,28 @@
+class SecretString
+
+  module CoreExtensions
+
+    # Make sure a String can be used as a SecretString.
+    # This helps in avoiding code like "if my_str.is_a?(SecretString)" to access to its content.
+    module String
+
+      # Return the unprotected String
+      #
+      # Result::
+      # * String: Unprotected string
+      def to_unprotected
+        self
+      end
+
+      # Erase the string
+      def erase
+        # Nothing to do
+      end
+
+    end
+
+  end
+
+end
+
+String.include SecretString::CoreExtensions::String

data/lib/secret_string/version.rb

@@ -0,0 +1,5 @@
+class SecretString
+
+  VERSION = '1.0.0'
+
+end

data/spec/secret_string_test/helpers.rb

@@ -0,0 +1 @@
+require 'secret_string'

data/spec/secret_string_test/tests/rubocop_spec.rb

@@ -0,0 +1,31 @@
+require 'json'
+
+describe 'Coding guidelines' do
+
+  it 'makes sure code style follow Rubocop guides' do
+    rubocop_report = JSON.parse(`bundle exec rubocop --format json`)
+    expect(rubocop_report['summary']['offense_count']).to(
+      eq(0),
+      proc do
+        # Format a great error message to help
+        wrong_files = rubocop_report['files'].reject { |file_info| file_info['offenses'].empty? }
+        <<~EO_ERROR
+          #{wrong_files.size} files have Rubocop issues:
+          #{
+            wrong_files.map do |file_info|
+              offenses = file_info['offenses'].map { |offense_info| "L#{offense_info['location']['start_line']}: #{offense_info['cop_name']} - #{offense_info['message']}" }
+              "* #{file_info['path']}:#{
+                if offenses.size == 1
+                  " #{offenses.first}"
+                else
+                  " #{offenses.size} offenses:\n#{offenses.map { |offense| "  - #{offense}" }.join("\n")}"
+                end
+              }"
+            end.join("\n")
+          }
+        EO_ERROR
+      end
+    )
+  end
+
+end

data/spec/secret_string_test/tests/secret_string_spec.rb

@@ -0,0 +1,50 @@
+describe SecretString do
+
+  context 'with a silenced string' do
+
+    subject(:secret) { described_class.new('MySecret', silenced_str: 'SilencedString') }
+
+    it 'silences using to_s' do
+      expect(secret.to_s).to eq 'SilencedString'
+    end
+
+    it 'silences using inspect' do
+      expect(secret.inspect).to eq '"SilencedString"'
+    end
+
+    it 'reveals using to_unprotected' do
+      expect(secret.to_unprotected).to eq 'MySecret'
+    end
+
+    it 'erases the data in memory' do
+      secret.erase
+      expect(secret.to_unprotected).not_to eq 'MySecret'
+    end
+
+  end
+
+  describe 'erase' do
+
+    it 'erases a String' do
+      str = 'MySecret'
+      described_class.erase(str)
+      expect(str).not_to eq 'MySecret'
+    end
+
+  end
+
+  describe 'protect' do
+
+    it 'protects a String' do
+      str = 'MySecret'
+      described_class.protect(str, silenced_str: 'SilencedString') do |secret_string|
+        expect(secret_string.to_s).to eq 'SilencedString'
+        expect(secret_string.to_unprotected).to eq 'MySecret'
+        expect(str.to_s).to eq 'MySecret'
+      end
+      expect(str.to_s).not_to eq 'MySecret'
+    end
+
+  end
+
+end

data/spec/secret_string_test/tests/string_spec.rb

@@ -0,0 +1,13 @@
+describe String do
+
+  it 'implements the same API as SecretString: to_unprotected' do
+    expect('MySecret'.to_unprotected).to eq 'MySecret'
+  end
+
+  it 'implements the same API as SecretString: erase' do
+    str = 'MySecret'
+    expect { str.erase }.not_to raise_error
+    expect(str).to eq 'MySecret'
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,102 @@
+require 'secret_string_test/helpers'
+
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# The generated `.rspec` file contains `--require spec_helper` which will cause
+# this file to always be loaded, without a need to explicitly require it in any
+# files.
+#
+# Given that it is always loaded, you are encouraged to keep this file as
+# light-weight as possible. Requiring heavyweight dependencies from this file
+# will add to the boot time of your test suite on EVERY test run, even for an
+# individual file that may not need all of that loaded. Instead, consider making
+# a separate helper file that requires the additional dependencies and performs
+# the additional setup, and require it from the spec files that actually need
+# it.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  # rspec-expectations config goes here. You can use an alternate
+  # assertion/expectation library such as wrong or the stdlib/minitest
+  # assertions if you prefer.
+  config.expect_with :rspec do |expectations|
+    # This option will default to `true` in RSpec 4. It makes the `description`
+    # and `failure_message` of custom matchers include text for helper methods
+    # defined using `chain`, e.g.:
+    #     be_bigger_than(2).and_smaller_than(4).description
+    #     # => "be bigger than 2 and smaller than 4"
+    # ...rather than:
+    #     # => "be bigger than 2"
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  # rspec-mocks config goes here. You can use an alternate test double
+  # library (such as bogus or mocha) by changing the `mock_with` option here.
+  config.mock_with :rspec do |mocks|
+    # Prevents you from mocking or stubbing a method that does not exist on
+    # a real object. This is generally recommended, and will default to
+    # `true` in RSpec 4.
+    mocks.verify_partial_doubles = true
+  end
+
+  # This option will default to `:apply_to_host_groups` in RSpec 4 (and will
+  # have no way to turn it off -- the option exists only for backwards
+  # compatibility in RSpec 3). It causes shared context metadata to be
+  # inherited by the metadata hash of host groups and examples, rather than
+  # triggering implicit auto-inclusion in groups with matching metadata.
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+
+  # The settings below are suggested to provide a good initial experience
+  # with RSpec, but feel free to customize to your heart's content.
+
+  # This allows you to limit a spec run to individual examples or groups
+  # you care about by tagging them with `:focus` metadata. When nothing
+  # is tagged with `:focus`, all examples get run. RSpec also provides
+  # aliases for `it`, `describe`, and `context` that include `:focus`
+  # metadata: `fit`, `fdescribe` and `fcontext`, respectively.
+  # config.filter_run_when_matching :focus
+
+  # Allows RSpec to persist some state between runs in order to support
+  # the `--only-failures` and `--next-failure` CLI options. We recommend
+  # you configure your source control system to ignore this file.
+  # config.example_status_persistence_file_path = "spec/examples.txt"
+
+  # Limits the available syntax to the non-monkey patched syntax that is
+  # recommended. For more details, see:
+  #   - http://rspec.info/blog/2012/06/rspecs-new-expectation-syntax/
+  #   - http://www.teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
+  #   - http://rspec.info/blog/2014/05/notable-changes-in-rspec-3/#zero-monkey-patching-mode
+  # config.disable_monkey_patching!
+
+  # This setting enables warnings. It's recommended, but in some cases may
+  # be too noisy due to issues in dependencies.
+  # config.warnings = true
+
+  # Many RSpec users commonly either run the entire suite or an individual
+  # file, and it's useful to allow more verbose output when running an
+  # individual spec file.
+  # if config.files_to_run.one?
+  #   # Use the documentation formatter for detailed output,
+  #   # unless a formatter has already been configured
+  #   # (e.g. via a command-line flag).
+  #   config.default_formatter = "doc"
+  # end
+
+  # Print the 10 slowest examples and example groups at the
+  # end of the spec run, to help surface which specs are running
+  # particularly slow.
+  # config.profile_examples = 10
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  # config.order = :random
+
+  # Seed global randomization in this process using the `--seed` CLI option.
+  # Setting this allows you to use `--seed` to deterministically reproduce
+  # test failures related to randomization by passing the same `--seed` value
+  # as the one that triggered the failure.
+  # Kernel.srand config.seed
+
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: secret_string
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Muriel Salvan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2021-06-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+- !ruby/object:Gem::Dependency
+  name: sem_ver_components
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+description: Remove secrets (passwords, keys...) from memory
+email:
+- muriel@x-aeon.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+files:
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- lib/secret_string.rb
+- lib/secret_string/core_extensions/string.rb
+- lib/secret_string/version.rb
+- spec/secret_string_test/helpers.rb
+- spec/secret_string_test/tests/rubocop_spec.rb
+- spec/secret_string_test/tests/secret_string_spec.rb
+- spec/secret_string_test/tests/string_spec.rb
+- spec/spec_helper.rb
+homepage: 
+licenses:
+- BSD-3-Clause
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: Secret String
+test_files: []