cyphera 0.0.1.alpha.1 → 0.0.1.alpha.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '092f5a2db55a53433ed97db72c86fb9f77a56dc15be2f96c343c36c06fb07ac2'
-  data.tar.gz: 289ca8aa1a02f678cc6ad267a103d0aa5a26c0ead54edce4d28bc8d30dbeb4db
+  metadata.gz: 644fcfada6f2f21f7154a8a7d640ff476459486e1d51e4824ed96e4a15214ae1
+  data.tar.gz: 0a7456e7734eeb10464333f952d32871d67c55bfd106f5d11d1fd339530a81bb
 SHA512:
-  metadata.gz: 75c5fe10c28c3d07559c084a9f73e5a2b8276afd700b00ecac5f3c408257ed48989fb16af488fa2e031701b4e30c4d956a9b9657e374c8a72d6db9d2b17ca3af
-  data.tar.gz: d5a63dd12e2751ac8741cc90628f2e28da9a4ca0438df0763a4e02d1c210e69b326b59213a14367d237798340c66c78b368eaa7e76ddae2c092acfe01c66be24
+  metadata.gz: 0a522a4bef3f86874e8b296c05cbe57ce806321be56e5bb140f802cc402a333231a5c51be9dca1b958413c1c614e181b0265a667e04415b5ccadc4dc3fc49053
+  data.tar.gz: f1d9ad1bcc5f173774f00a172cbed7ed37d6abf8031f339b39792df490e8f9da4dca3b50721abef8bfd7fa2d8bd9c0077a0ca17063b8674610e0c515b951fc69

data/lib/cyphera/cyphera.rb

@@ -12,11 +12,11 @@ module Cyphera
 
   class Client
     def self.load
-      env = ENV['CYPHERA_POLICY_FILE']
+      env = ENV['CYPHERA_CONFIG_FILE']
       return from_file(env) if env && File.exist?(env)
       return from_file('cyphera.json') if File.exist?('cyphera.json')
       return from_file('/etc/cyphera/cyphera.json') if File.exist?('/etc/cyphera/cyphera.json')
-      raise 'No policy file found. Checked: CYPHERA_POLICY_FILE env, ./cyphera.json, /etc/cyphera/cyphera.json'
+      raise 'No configuration file found. Checked: CYPHERA_CONFIG_FILE env, ./cyphera.json, /etc/cyphera/cyphera.json'
     end
 
     def self.from_file(path)
@@ -28,89 +28,139 @@ module Cyphera
       new(config)
     end
 
-    def protect(value, policy_name)
-      policy = get_policy(policy_name)
-      case policy['engine']
-      when 'ff1' then protect_fpe(value, policy, false)
-      when 'ff3' then protect_fpe(value, policy, true)
-      when 'mask' then protect_mask(value, policy)
-      when 'hash' then protect_hash(value, policy)
-      else raise ArgumentError, "Unknown engine: #{policy['engine']}"
+    def protect(value, configuration_name)
+      configuration = get_configuration(configuration_name)
+      case configuration['engine']
+      when 'ff1' then protect_fpe(value, configuration, false)
+      when 'ff3' then protect_fpe(value, configuration, true)
+      when 'mask' then protect_mask(value, configuration)
+      when 'hash' then protect_hash(value, configuration)
+      else raise ArgumentError, "Unknown engine: #{configuration['engine']}"
       end
     end
 
-    def access(protected_value, policy_name = nil)
-      if policy_name
-        policy = get_policy(policy_name)
-        return access_fpe(protected_value, policy)
+    def access(protected_value, configuration_name = nil)
+      if configuration_name
+        configuration = get_configuration(configuration_name)
+        if configuration['header_enabled']
+          raise ArgumentError,
+            "configuration '#{configuration_name}' has header_enabled=true; use access(value) — " \
+            'the header identifies the configuration. The two-arg form is for ' \
+            'header_enabled=false configurations only.'
+        end
+        return access_fpe(protected_value, configuration)
       end
 
-      @tag_index.keys.sort_by { |t| -t.length }.each do |tag|
-        if protected_value.length > tag.length && protected_value.start_with?(tag)
-          policy = get_policy(@tag_index[tag])
-          return access_fpe(protected_value, policy)
+      access_by_header(protected_value)
+    end
+
+    def access_by_header(protected_value)
+      @header_index.keys.sort_by { |h| -h.length }.each do |header|
+        if protected_value.length > header.length && protected_value.start_with?(header)
+          configuration = get_configuration(@header_index[header])
+          stripped = protected_value[header.length..]
+          return access_fpe(stripped, configuration)
         end
       end
 
-      raise ArgumentError, 'No matching tag found. Use access(value, policy_name) for untagged values.'
+      raise ArgumentError, 'No matching header found. Use access(value, configuration_name) for headerless values.'
     end
 
     private
 
     def initialize(config)
-      @policies = {}
-      @tag_index = {}
+      @configurations = {}
+      @header_index = {}
       @keys = {}
 
       (config['keys'] || {}).each do |name, val|
-        material = val.is_a?(String) ? val : val['material']
-        @keys[name] = [material].pack('H*')
+        if val.is_a?(String)
+          @keys[name] = [val].pack('H*')
+        elsif val['material']
+          @keys[name] = [val['material']].pack('H*')
+        elsif val['source']
+          @keys[name] = self.class.resolve_key_source(name, val)
+        else
+          raise ArgumentError, "Key '#{name}' must have either 'material' or 'source'"
+        end
       end
 
-      (config['policies'] || {}).each do |name, pol|
-        tag_enabled = pol.fetch('tag_enabled', true)
-        tag = pol['tag']
+      (config['configurations'] || {}).each do |name, cfg|
+        header_enabled = cfg.fetch('header_enabled', true)
+        header = cfg['header']
 
-        if tag_enabled && (tag.nil? || tag.empty?)
-          raise ArgumentError, "Policy '#{name}' has tag_enabled=true but no tag specified"
+        if header_enabled && (header.nil? || header.empty?)
+          raise ArgumentError, "Configuration '#{name}' has header_enabled=true but no header specified"
         end
 
-        if tag_enabled && tag
-          if @tag_index.key?(tag)
-            raise ArgumentError, "Tag collision: '#{tag}' used by both '#{@tag_index[tag]}' and '#{name}'"
+        if header_enabled && header
+          if @header_index.key?(header)
+            raise ArgumentError, "Header collision: '#{header}' used by both '#{@header_index[header]}' and '#{name}'"
           end
-          @tag_index[tag] = name
+          @header_index[header] = name
         end
 
-        @policies[name] = {
-          'engine' => pol.fetch('engine', 'ff1'),
-          'alphabet' => resolve_alphabet(pol['alphabet']),
-          'key_ref' => pol['key_ref'],
-          'tag' => tag,
-          'tag_enabled' => tag_enabled,
-          'pattern' => pol['pattern'],
-          'algorithm' => pol.fetch('algorithm', 'sha256')
+        @configurations[name] = {
+          'engine' => cfg.fetch('engine', 'ff1'),
+          'alphabet' => resolve_alphabet(cfg['alphabet']),
+          'key_ref' => cfg['key_ref'],
+          'header' => header,
+          'header_enabled' => header_enabled,
+          'pattern' => cfg['pattern'],
+          'algorithm' => cfg.fetch('algorithm', 'sha256')
         }
       end
     end
 
-    def get_policy(name)
-      @policies.fetch(name) { raise ArgumentError, "Unknown policy: #{name}" }
+    def get_configuration(name)
+      @configurations.fetch(name) { raise ArgumentError, "Unknown configuration: #{name}" }
     end
 
     def resolve_key(key_ref)
-      raise ArgumentError, 'No key_ref in policy' if key_ref.nil? || key_ref.empty?
+      raise ArgumentError, 'No key_ref in configuration' if key_ref.nil? || key_ref.empty?
       @keys.fetch(key_ref) { raise ArgumentError, "Unknown key: #{key_ref}" }
     end
 
+    CLOUD_SOURCES = %w[aws-kms gcp-kms azure-kv vault].freeze
+
+    def self.resolve_key_source(name, config)
+      source = config['source']
+
+      case source
+      when 'env'
+        var_name = config['var'] or raise ArgumentError, "Key '#{name}': source 'env' requires 'var' field"
+        val = ENV[var_name] or raise ArgumentError, "Key '#{name}': environment variable '#{var_name}' is not set"
+        encoding = config['encoding'] || 'hex'
+        return encoding == 'base64' ? val.unpack1('m') : [val].pack('H*')
+      when 'file'
+        path = config['path'] or raise ArgumentError, "Key '#{name}': source 'file' requires 'path' field"
+        raw = File.read(path).strip
+        encoding = config['encoding'] || (path.end_with?('.b64', '.base64') ? 'base64' : 'hex')
+        return encoding == 'base64' ? raw.unpack1('m') : [raw].pack('H*')
+      end
+
+      if CLOUD_SOURCES.include?(source)
+        begin
+          require 'cyphera-keychain'
+          return CypheraKeychain.resolve(source, config)
+        rescue LoadError
+          raise LoadError,
+            "Key '#{name}' requires source '#{source}' but cyphera-keychain is not installed.\n" \
+            "Install it: gem install cyphera-keychain"
+        end
+      end
+
+      raise ArgumentError, "Key '#{name}': unknown source '#{source}'. Valid: env, file, #{CLOUD_SOURCES.join(', ')}"
+    end
+
     def resolve_alphabet(name)
       return ALPHABETS['alphanumeric'] if name.nil? || name.empty?
       ALPHABETS[name] || name
     end
 
-    def protect_fpe(value, policy, is_ff3)
-      key = resolve_key(policy['key_ref'])
-      alphabet = policy['alphabet']
+    def protect_fpe(value, configuration, is_ff3)
+      key = resolve_key(configuration['key_ref'])
+      alphabet = configuration['alphabet']
       encryptable, positions, chars = extract_passthroughs(value, alphabet)
       raise ArgumentError, 'No encryptable characters in input' if encryptable.empty?
 
@@ -121,29 +171,28 @@ module Cyphera
       end
 
       result = reinsert_passthroughs(encrypted, positions, chars)
-      if policy['tag_enabled'] && policy['tag']
-        policy['tag'] + result
+      if configuration['header_enabled'] && configuration['header']
+        configuration['header'] + result
       else
         result
       end
     end
 
-    def access_fpe(protected_value, policy)
-      unless %w[ff1 ff3].include?(policy['engine'])
-        raise ArgumentError, "Cannot reverse '#{policy['engine']}' — not reversible"
+    # Reverses an FPE-protected value. Assumes the input is already
+    # header-stripped (or that the configuration has header_enabled=false).
+    # Callers: access() routes here after the header_enabled=false check;
+    # access_by_header() strips the header itself before calling.
+    def access_fpe(protected_value, configuration)
+      unless %w[ff1 ff3].include?(configuration['engine'])
+        raise ArgumentError, "Cannot reverse '#{configuration['engine']}' — not reversible"
       end
 
-      key = resolve_key(policy['key_ref'])
-      alphabet = policy['alphabet']
-
-      without_tag = protected_value
-      if policy['tag_enabled'] && policy['tag']
-        without_tag = protected_value[policy['tag'].length..]
-      end
+      key = resolve_key(configuration['key_ref'])
+      alphabet = configuration['alphabet']
 
-      encryptable, positions, chars = extract_passthroughs(without_tag, alphabet)
+      encryptable, positions, chars = extract_passthroughs(protected_value, alphabet)
 
-      decrypted = if policy['engine'] == 'ff3'
+      decrypted = if configuration['engine'] == 'ff3'
         FF3.new(key, "\x00" * 8, alphabet).decrypt(encryptable)
       else
         FF1.new(key, '', alphabet).decrypt(encryptable)
@@ -152,9 +201,9 @@ module Cyphera
       reinsert_passthroughs(decrypted, positions, chars)
     end
 
-    def protect_mask(value, policy)
-      pattern = policy['pattern']
-      raise ArgumentError, "Mask policy requires 'pattern'" if pattern.nil? || pattern.empty?
+    def protect_mask(value, configuration)
+      pattern = configuration['pattern']
+      raise ArgumentError, "Mask configuration requires 'pattern'" if pattern.nil? || pattern.empty?
       len = value.length
       case pattern
       when 'last4', 'last_4' then ('*' * [0, len - 4].max) + value[[0, len - 4].max..]
@@ -165,17 +214,17 @@ module Cyphera
       end
     end
 
-    def protect_hash(value, policy)
-      algo = policy['algorithm'].downcase.delete('-')
+    def protect_hash(value, configuration)
+      algo = configuration['algorithm'].downcase.delete('-')
       digest = case algo
       when 'sha256' then 'SHA256'
       when 'sha384' then 'SHA384'
       when 'sha512' then 'SHA512'
-      else raise ArgumentError, "Unsupported hash algorithm: #{policy['algorithm']}"
+      else raise ArgumentError, "Unsupported hash algorithm: #{configuration['algorithm']}"
       end
 
-      if policy['key_ref'] && !policy['key_ref'].empty?
-        key = resolve_key(policy['key_ref'])
+      if configuration['key_ref'] && !configuration['key_ref'].empty?
+        key = resolve_key(configuration['key_ref'])
         OpenSSL::HMAC.hexdigest(digest, key, value)
       else
         OpenSSL::Digest.hexdigest(digest, value)

data/lib/cyphera/ff1.rb

@@ -37,6 +37,8 @@ module Cyphera
     end
 
     def aes_ecb(block)
+      # NIST SP 800-38G requires AES-ECB as the PRF for FF1/FF3 Feistel rounds.
+      # This is single-block encryption used as a building block, not ECB mode applied to user data.
       cipher = OpenSSL::Cipher::AES.new(@key.bytesize * 8, :ECB)
       cipher.encrypt
       cipher.padding = 0

data/lib/cyphera/ff3.rb

@@ -38,6 +38,8 @@ module Cyphera
     end
 
     def aes_ecb(block)
+      # NIST SP 800-38G requires AES-ECB as the PRF for FF1/FF3 Feistel rounds.
+      # This is single-block encryption used as a building block, not ECB mode applied to user data.
       cipher = OpenSSL::Cipher::AES.new(@key.bytesize * 8, :ECB)
       cipher.encrypt
       cipher.padding = 0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cyphera
 version: !ruby/object:Gem::Version
-  version: 0.0.1.alpha.1
+  version: 0.0.1.alpha.2
 platform: ruby
 authors:
 - Horizon Digital Engineering
@@ -10,8 +10,8 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: Cyphera is an open-source data protection SDK for Ruby. Format-preserving
-  encryption (FF1/FF3), data masking, and hashing. Policy-driven protect/access API.
-  Cross-language compatible.
+  encryption (FF1/FF3), data masking, and hashing. Configuration-driven protect/access
+  API. Cross-language compatible.
 email: leslie.gutschow@horizondigital.dev
 executables: []
 extensions: []
@@ -41,7 +41,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Data protection SDK — format-preserving encryption (FF1/FF3), data masking,
   and hashing.