cyphera 0.0.1.alpha.1

checksums.yaml

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

data/lib/cyphera/cyphera.rb

@@ -0,0 +1,212 @@
+require 'json'
+require 'openssl'
+
+module Cyphera
+  ALPHABETS = {
+    'digits' => '0123456789',
+    'alpha_lower' => 'abcdefghijklmnopqrstuvwxyz',
+    'alpha_upper' => 'ABCDEFGHIJKLMNOPQRSTUVWXYZ',
+    'alpha' => 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ',
+    'alphanumeric' => '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
+  }.freeze
+
+  class Client
+    def self.load
+      env = ENV['CYPHERA_POLICY_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'
+    end
+
+    def self.from_file(path)
+      config = JSON.parse(File.read(path))
+      from_config(config)
+    end
+
+    def self.from_config(config)
+      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']}"
+      end
+    end
+
+    def access(protected_value, policy_name = nil)
+      if policy_name
+        policy = get_policy(policy_name)
+        return access_fpe(protected_value, policy)
+      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)
+        end
+      end
+
+      raise ArgumentError, 'No matching tag found. Use access(value, policy_name) for untagged values.'
+    end
+
+    private
+
+    def initialize(config)
+      @policies = {}
+      @tag_index = {}
+      @keys = {}
+
+      (config['keys'] || {}).each do |name, val|
+        material = val.is_a?(String) ? val : val['material']
+        @keys[name] = [material].pack('H*')
+      end
+
+      (config['policies'] || {}).each do |name, pol|
+        tag_enabled = pol.fetch('tag_enabled', true)
+        tag = pol['tag']
+
+        if tag_enabled && (tag.nil? || tag.empty?)
+          raise ArgumentError, "Policy '#{name}' has tag_enabled=true but no tag specified"
+        end
+
+        if tag_enabled && tag
+          if @tag_index.key?(tag)
+            raise ArgumentError, "Tag collision: '#{tag}' used by both '#{@tag_index[tag]}' and '#{name}'"
+          end
+          @tag_index[tag] = 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')
+        }
+      end
+    end
+
+    def get_policy(name)
+      @policies.fetch(name) { raise ArgumentError, "Unknown policy: #{name}" }
+    end
+
+    def resolve_key(key_ref)
+      raise ArgumentError, 'No key_ref in policy' if key_ref.nil? || key_ref.empty?
+      @keys.fetch(key_ref) { raise ArgumentError, "Unknown key: #{key_ref}" }
+    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']
+      encryptable, positions, chars = extract_passthroughs(value, alphabet)
+      raise ArgumentError, 'No encryptable characters in input' if encryptable.empty?
+
+      encrypted = if is_ff3
+        FF3.new(key, "\x00" * 8, alphabet).encrypt(encryptable)
+      else
+        FF1.new(key, '', alphabet).encrypt(encryptable)
+      end
+
+      result = reinsert_passthroughs(encrypted, positions, chars)
+      if policy['tag_enabled'] && policy['tag']
+        policy['tag'] + 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"
+      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
+
+      encryptable, positions, chars = extract_passthroughs(without_tag, alphabet)
+
+      decrypted = if policy['engine'] == 'ff3'
+        FF3.new(key, "\x00" * 8, alphabet).decrypt(encryptable)
+      else
+        FF1.new(key, '', alphabet).decrypt(encryptable)
+      end
+
+      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?
+      len = value.length
+      case pattern
+      when 'last4', 'last_4' then ('*' * [0, len - 4].max) + value[[0, len - 4].max..]
+      when 'last2', 'last_2' then ('*' * [0, len - 2].max) + value[[0, len - 2].max..]
+      when 'first1', 'first_1' then value[0, [1, len].min] + ('*' * [0, len - 1].max)
+      when 'first3', 'first_3' then value[0, [3, len].min] + ('*' * [0, len - 3].max)
+      else '*' * len
+      end
+    end
+
+    def protect_hash(value, policy)
+      algo = policy['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']}"
+      end
+
+      if policy['key_ref'] && !policy['key_ref'].empty?
+        key = resolve_key(policy['key_ref'])
+        OpenSSL::HMAC.hexdigest(digest, key, value)
+      else
+        OpenSSL::Digest.hexdigest(digest, value)
+      end
+    end
+
+    def extract_passthroughs(value, alphabet)
+      encryptable = ''
+      positions = []
+      chars = []
+      value.each_char.with_index do |c, i|
+        if alphabet.include?(c)
+          encryptable << c
+        else
+          positions << i
+          chars << c
+        end
+      end
+      [encryptable, positions, chars]
+    end
+
+    def reinsert_passthroughs(encrypted, positions, chars)
+      result = encrypted.chars
+      positions.each_with_index do |pos, i|
+        if pos <= result.length
+          result.insert(pos, chars[i])
+        else
+          result << chars[i]
+        end
+      end
+      result.join
+    end
+  end
+end

data/lib/cyphera/ff1.rb

@@ -0,0 +1,173 @@
+require 'openssl'
+
+module Cyphera
+  class FF1
+    def initialize(key, tweak, alphabet = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ')
+      raise ArgumentError, "Key must be 16, 24, or 32 bytes" unless [16, 24, 32].include?(key.bytesize)
+      raise ArgumentError, "Alphabet must have >= 2 characters" if alphabet.length < 2
+
+      @key = key
+      @tweak = tweak
+      @alphabet = alphabet
+      @radix = alphabet.length
+      @char_map = {}
+      alphabet.each_char.with_index { |c, i| @char_map[c] = i }
+    end
+
+    def encrypt(plaintext)
+      digits = to_digits(plaintext)
+      result = ff1_encrypt(digits, @tweak)
+      from_digits(result)
+    end
+
+    def decrypt(ciphertext)
+      digits = to_digits(ciphertext)
+      result = ff1_decrypt(digits, @tweak)
+      from_digits(result)
+    end
+
+    private
+
+    def to_digits(s)
+      s.each_char.map { |c| @char_map.fetch(c) { raise ArgumentError, "Character '#{c}' not in alphabet" } }
+    end
+
+    def from_digits(d)
+      d.map { |i| @alphabet[i] }.join
+    end
+
+    def aes_ecb(block)
+      cipher = OpenSSL::Cipher::AES.new(@key.bytesize * 8, :ECB)
+      cipher.encrypt
+      cipher.padding = 0
+      cipher.key = @key
+      cipher.update(block) + cipher.final
+    end
+
+    def prf(data)
+      y = "\x00" * 16
+      (0...data.bytesize).step(16) do |off|
+        block = y.bytes.zip(data.byteslice(off, 16).bytes).map { |a, b| a ^ b }.pack('C*')
+        y = aes_ecb(block)
+      end
+      y
+    end
+
+    def expand_s(r, d)
+      blocks = (d + 15) / 16
+      out = r.dup
+      (1...blocks).each do |j|
+        x = ([0] * 12 + [(j >> 24) & 0xFF, (j >> 16) & 0xFF, (j >> 8) & 0xFF, j & 0xFF]).pack('C*')
+        # XOR with R (not previous block) per NIST SP 800-38G
+        x = x.bytes.zip(r.bytes).map { |a, b| a ^ b }.pack('C*')
+        out << aes_ecb(x)
+      end
+      out.byteslice(0, d)
+    end
+
+    def num(digits)
+      r = 0
+      digits.each { |d| r = r * @radix + d }
+      r
+    end
+
+    def str(n, len)
+      result = Array.new(len, 0)
+      (len - 1).downto(0) do |i|
+        result[i] = n % @radix
+        n /= @radix
+      end
+      result
+    end
+
+    def compute_b(v)
+      (Math.log2(@radix) * v / 8.0).ceil
+    end
+
+    def build_p(u, n, t)
+      [1, 2, 1, (@radix >> 16) & 0xFF, (@radix >> 8) & 0xFF, @radix & 0xFF, 10, u,
+       (n >> 24) & 0xFF, (n >> 16) & 0xFF, (n >> 8) & 0xFF, n & 0xFF,
+       (t >> 24) & 0xFF, (t >> 16) & 0xFF, (t >> 8) & 0xFF, t & 0xFF].pack('C*')
+    end
+
+    def build_q(t, i, num_bytes, b)
+      pad = (16 - ((t.bytesize + 1 + b) % 16)) % 16
+      q = t.dup
+      q << ("\x00" * pad)
+      q << [i].pack('C')
+      if num_bytes.bytesize < b
+        q << ("\x00" * (b - num_bytes.bytesize))
+      end
+      start = [0, num_bytes.bytesize - b].max
+      q << num_bytes.byteslice(start..)
+      q
+    end
+
+    def bigint_to_bytes(val, len)
+      hex = val.to_s(16)
+      hex = "0#{hex}" if hex.length.odd?
+      bytes = [hex].pack('H*')
+      if bytes.bytesize < len
+        bytes = ("\x00" * (len - bytes.bytesize)) + bytes
+      elsif bytes.bytesize > len
+        bytes = bytes.byteslice(-len, len)
+      end
+      bytes
+    end
+
+    def ff1_encrypt(pt, t)
+      n = pt.length
+      u = n / 2
+      v = n - u
+      a = pt[0...u]
+      b = pt[u..]
+
+      bval = compute_b(v)
+      d = 4 * ((bval + 3) / 4) + 4
+      p = build_p(u, n, t.bytesize)
+
+      10.times do |i|
+        num_b = bigint_to_bytes(num(b), [bval, 1].max)
+        q = build_q(t, i, num_b, bval)
+        r = prf(p + q)
+        s = expand_s(r, d)
+        y = s.unpack1('H*').to_i(16)
+
+        m = i.even? ? u : v
+        c = (num(a) + y) % (@radix ** m)
+        a = b
+        b = str(c, m)
+      end
+
+      a + b
+    end
+
+    def ff1_decrypt(ct, t)
+      n = ct.length
+      u = n / 2
+      v = n - u
+      a = ct[0...u]
+      b = ct[u..]
+
+      bval = compute_b(v)
+      d = 4 * ((bval + 3) / 4) + 4
+      p = build_p(u, n, t.bytesize)
+
+      9.downto(0) do |i|
+        num_a = bigint_to_bytes(num(a), [bval, 1].max)
+        q = build_q(t, i, num_a, bval)
+        r = prf(p + q)
+        s = expand_s(r, d)
+        y = s.unpack1('H*').to_i(16)
+
+        m = i.even? ? u : v
+        mod = @radix ** m
+        c = (num(b) - y) % mod
+        b = a
+        a = str(c, m)
+      end
+
+      a + b
+    end
+  end
+end

data/lib/cyphera/ff3.rb

@@ -0,0 +1,148 @@
+require 'openssl'
+
+module Cyphera
+  class FF3
+    def initialize(key, tweak, alphabet = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ')
+      raise ArgumentError, "Key must be 16, 24, or 32 bytes" unless [16, 24, 32].include?(key.bytesize)
+      raise ArgumentError, "Tweak must be exactly 8 bytes" unless tweak.bytesize == 8
+      raise ArgumentError, "Alphabet must have >= 2 characters" if alphabet.length < 2
+
+      @key = key.reverse
+      @tweak = tweak
+      @alphabet = alphabet
+      @radix = alphabet.length
+      @char_map = {}
+      alphabet.each_char.with_index { |c, i| @char_map[c] = i }
+    end
+
+    def encrypt(plaintext)
+      digits = to_digits(plaintext)
+      result = ff3_encrypt(digits)
+      from_digits(result)
+    end
+
+    def decrypt(ciphertext)
+      digits = to_digits(ciphertext)
+      result = ff3_decrypt(digits)
+      from_digits(result)
+    end
+
+    private
+
+    def to_digits(s)
+      s.each_char.map { |c| @char_map.fetch(c) { raise ArgumentError, "Character '#{c}' not in alphabet" } }
+    end
+
+    def from_digits(d)
+      d.map { |i| @alphabet[i] }.join
+    end
+
+    def aes_ecb(block)
+      cipher = OpenSSL::Cipher::AES.new(@key.bytesize * 8, :ECB)
+      cipher.encrypt
+      cipher.padding = 0
+      cipher.key = @key
+      cipher.update(block) + cipher.final
+    end
+
+    def num(digits)
+      r = 0
+      digits.each { |d| r = r * @radix + d }
+      r
+    end
+
+    def str(n, len)
+      result = Array.new(len, 0)
+      (len - 1).downto(0) do |i|
+        result[i] = n % @radix
+        n /= @radix
+      end
+      result
+    end
+
+    def calc_p(round, w, half)
+      inp = Array.new(16, 0)
+      inp[0] = w.getbyte(0)
+      inp[1] = w.getbyte(1)
+      inp[2] = w.getbyte(2)
+      inp[3] = w.getbyte(3) ^ round
+
+      rev_half = half.reverse
+      half_num = num(rev_half)
+      half_hex = half_num.to_s(16)
+      half_hex = "0#{half_hex}" if half_hex.length.odd?
+      half_bytes = [half_hex].pack('H*')
+      half_bytes = "\x00" if half_bytes.empty?
+
+      if half_bytes.bytesize <= 12
+        pos = 16 - half_bytes.bytesize
+        half_bytes.bytes.each_with_index { |b, k| inp[pos + k] = b }
+      else
+        start = half_bytes.bytesize - 12
+        12.times { |k| inp[4 + k] = half_bytes.getbyte(start + k) }
+      end
+
+      rev_inp = inp.pack('C*').reverse
+      aes_out = aes_ecb(rev_inp)
+      rev_out = aes_out.reverse
+
+      rev_out.unpack1('H*').to_i(16)
+    end
+
+    def ff3_encrypt(pt)
+      n = pt.length
+      u = (n + 1) / 2
+      v = n - u
+      a = pt[0...u].dup
+      b = pt[u..].dup
+
+      8.times do |i|
+        if i.even?
+          w = @tweak.byteslice(4, 4)
+          p = calc_p(i, w, b)
+          m = @radix ** u
+          a_num = num(a.reverse)
+          y = (a_num + p) % m
+          a = str(y, u).reverse
+        else
+          w = @tweak.byteslice(0, 4)
+          p = calc_p(i, w, a)
+          m = @radix ** v
+          b_num = num(b.reverse)
+          y = (b_num + p) % m
+          b = str(y, v).reverse
+        end
+      end
+
+      a + b
+    end
+
+    def ff3_decrypt(ct)
+      n = ct.length
+      u = (n + 1) / 2
+      v = n - u
+      a = ct[0...u].dup
+      b = ct[u..].dup
+
+      7.downto(0) do |i|
+        if i.even?
+          w = @tweak.byteslice(4, 4)
+          p = calc_p(i, w, b)
+          m = @radix ** u
+          a_num = num(a.reverse)
+          y = (a_num - p) % m
+          a = str(y, u).reverse
+        else
+          w = @tweak.byteslice(0, 4)
+          p = calc_p(i, w, a)
+          m = @radix ** v
+          b_num = num(b.reverse)
+          y = (b_num - p) % m
+          b = str(y, v).reverse
+        end
+      end
+
+      a + b
+    end
+  end
+end

data/lib/cyphera.rb

@@ -0,0 +1,6 @@
+require_relative 'cyphera/ff1'
+require_relative 'cyphera/ff3'
+require_relative 'cyphera/cyphera'
+
+module Cyphera
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: cyphera
+version: !ruby/object:Gem::Version
+  version: 0.0.1.alpha.1
+platform: ruby
+authors:
+- Horizon Digital Engineering
+bindir: bin
+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.
+email: leslie.gutschow@horizondigital.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/cyphera.rb
+- lib/cyphera/cyphera.rb
+- lib/cyphera/ff1.rb
+- lib/cyphera/ff3.rb
+homepage: https://cyphera.io
+licenses:
+- Apache-2.0
+metadata:
+  source_code_uri: https://github.com/cyphera-labs/cyphera-ruby
+  homepage_uri: https://cyphera.io
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Data protection SDK — format-preserving encryption (FF1/FF3), data masking,
+  and hashing.
+test_files: []