sekishiki 20260821

data/README.org

@@ -0,0 +1,84 @@
+#+title: README
+#+author: Sidney PEPO
+#+date: [2026-08-21 Fri]
+
+#+begin_center
+#+html: <div align="center">
+#+html: <img src="res/logo/logo.png" alt="Sekishiki logo" height="250">
+#+html: </div>
+#+end_center
+
+* Sekishiki (Ruby)
+The Ruby implementation of /Sekishiki: The Secure Purpose-Agnostic Network
+Protocol/.
+
+* Why "Sekishiki"?
+This question is answered in [[file:why_sekishiki.org][why_sekishiki.org]], but note that it *contains
+spoilers* from Saint Seiya (aka Knights of the Zodiac), so read it *ONLY* if you
+are okay with that!
+
+#+begin_quote
+TL;DR: it is a Saint Seiya reference.
+#+end_quote
+
+* Installation
+Install the gem and add to the application's Gemfile by executing:
+
+#+begin_src sh
+bundle add sekishiki
+#+end_src
+
+If bundler is not being used to manage dependencies, install the gem by
+executing:
+
+#+begin_src sh
+gem install sekishiki
+#+end_src
+
+* Usage
+:PROPERTIES:
+:CUSTOM_ID: usage
+:END:
+TODO: Write (better) usage instructions here. Since I just wanted to publish
+this Gem as soon as possible, currently, the only available way to learn how to
+use Sekishiki is by reading its test files located at the ~spec~ directory. For
+an actual full usage example, check the ~spec/sekishiki_spec.rb~ test.
+
+** Packet format
+The Sekishiki packet format has the following structure:
+
+#+begin_center
+#+html: <div align="center">
+#+html: <img src="res/img/packet_format.png" alt="Sekishiki packet format" width="400">
+#+html: </div>
+#+end_center
+
+where
+
+- The information inside parenthesis are the size of each field in *bytes*;
+
+- The header of Sekishiki packets are 76 bytes long;
+
+- Green fields should *always* be filled, since they are required for all
+  Sekishiki packets;
+
+- The yellow field (~OTP code~) might be left untouched. However, since it is
+  what provides protection against [[https://en.wikipedia.org/wiki/Replay_attack][replay attacks]], *its usage is highly
+  encouraged*. This Sekishiki implementation ships with built-in features to
+  fill it with valid data (check the [[#usage][Usage]] section); and
+
+- Blue fields often can be filled with zeros (~\x00~), since they are reserved
+  for applications which implements Sekishiki. Such fields are handy for
+  transporting feature-specific information or application checks;
+
+* Development
+After checking out the repo, run ~bin/setup~ 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 install this gem onto your local machine, run ~bundle exec rake install~.
+
+* Contributing
+This section is at TODO state, but the tl;dr is: it is a good practice to first
+write and test your code by creating [[https://rspec.info][RSpec tests]] at the ~spec~ directory, but
+this procedure is not mandatory (just do not submit broken code).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/sekishiki/crypto.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "rbnacl"
+
+require "sekishiki/utils"
+
+module SEKISHIKI
+  # Wrapper for RbNaCl
+  class CRYPTO
+    attr_reader :box
+
+    def initialize(private_key = "", peer_public_key = "")
+      reset
+      self.private_key = private_key
+      self.peer_public_key = peer_public_key
+      box_create
+    end
+
+    def reset
+      @private_key = ""
+      @public_key = ""
+      @peer_public_key = ""
+
+      @box = nil
+    end
+
+    def public_key
+      SEKISHIKI.bin2hex @public_key
+    end
+
+    def private_key
+      SEKISHIKI.bin2hex @private_key
+    end
+
+    def private_key=(private_key)
+      return unless public_key.instance_of?(String) ||
+                    public_key.instance_of?(RbNaCl::PrivateKey)
+
+      @private_key = if private_key.instance_of?(String) && !private_key.empty?
+                       RbNaCl::PrivateKey.new(
+                         SEKISHIKI.to_bin(private_key, 32)
+                       )
+                     elsif private_key.instance_of?(RbNaCl::PrivateKey)
+                       private_key
+                     end
+
+      return unless @private_key.instance_of?(RbNaCl::PrivateKey)
+
+      @public_key = @private_key.public_key.to_bytes
+      @private_key = @private_key.to_bytes
+    end
+
+    def peer_public_key
+      SEKISHIKI.bin2hex @peer_public_key
+    end
+
+    def peer_public_key=(public_key)
+      return unless public_key.instance_of?(String) ||
+                    public_key.instance_of?(RbNaCl::PublicKey)
+
+      @peer_public_key = if public_key.instance_of?(String) &&
+                            !public_key.empty?
+                           RbNaCl::PublicKey.new(
+                             SEKISHIKI.to_bin(public_key, 32)
+                           )
+                         elsif public_key.instance_of?(RbNaCl::PublicKey)
+                           public_key
+                         end
+
+      return unless @peer_public_key.instance_of?(RbNaCl::PublicKey)
+
+      @peer_public_key = @peer_public_key.to_bytes
+    end
+
+    def private_key_create
+      @private_key = RbNaCl::PrivateKey.generate
+
+      @public_key = @private_key.public_key.to_bytes
+      @private_key = @private_key.to_bytes
+    end
+
+    def box_create
+      return unless @peer_public_key.instance_of?(String) ||
+                    @private_key.instance_of?(String)
+
+      @box = !(@peer_public_key.empty? || @private_key.empty?) &&
+             RbNaCl::SimpleBox.from_keypair(@peer_public_key, @private_key)
+    end
+
+    def encrypt(plaintext)
+      self.class.encrypt @box, plaintext
+    end
+
+    def decrypt(ciphertext)
+      self.class.decrypt @box, ciphertext
+    end
+
+    # NOTE: avoid using any of the following class methods! Instead, use their
+    # equivalent instance methods
+
+    def self.encrypt(box, plaintext)
+      (box.instance_of?(RbNaCl::SimpleBox) && box.encrypt(plaintext)) || ""
+    end
+
+    def self.decrypt(box, ciphertext)
+      (box.instance_of?(RbNaCl::SimpleBox) && box.decrypt(ciphertext)) || ""
+    end
+  end
+end

data/lib/sekishiki/packet.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "rotp"
+
+require "sekishiki/version"
+require "sekishiki/utils"
+
+module SEKISHIKI
+  # Packet implementation
+  class PACKET
+    attr_accessor :extension, :payload, :padding
+
+    attr_reader :otp
+
+    def initialize(**args)
+      reset
+      parse args[:pkt]
+      create args
+    end
+
+    def reset
+      self.version  = VERSION                      # 4
+      @flags        = SEKISHIKI.data_gen 1, false  # 1
+
+      @otp          = nil
+      @otp_code     = SEKISHIKI.data_gen 3, false  # 3
+
+      @dst          = SEKISHIKI.data_gen 32, false # 32
+      @src          = SEKISHIKI.data_gen 32, false # 32
+
+      @sz_extension = SEKISHIKI.data_gen 2, false  # 2
+      @sz_payload   = SEKISHIKI.data_gen 2, false  # 2
+
+      @extension    = ""                  # @sz_extension
+      @payload      = ""                  # @sz_payload
+      @padding      = ""                  # random
+    end
+
+    def parse(pkt)
+      return unless pkt.instance_of?(String)
+
+      self.version = pkt[0..3]
+      self.flags = pkt[4]
+      self.otp_code = pkt[5..7]
+
+      self.dst = pkt[8..39]
+      self.src = pkt[40..71]
+
+      self.sz_extension = pkt[72..73]
+      self.sz_payload = pkt[74..75]
+
+      @extension = pkt[76..(76 + sz_extension - 1)]
+      @payload = pkt[(76 + sz_extension)..(76 + sz_extension + sz_payload - 1)]
+      @padding = pkt[(76 + sz_extension + sz_payload)..]
+    end
+
+    def create(args)
+      self.version  = args[:version]
+      self.flags    = args[:flags]
+      self.otp      = args[:otp_secret]
+      self.otp_code = args[:otp_code]
+
+      self.dst      = args[:dst]
+      self.src      = args[:src]
+
+      @extension        = SEKISHIKI.to_bin args[:extension] if
+        args[:extension].instance_of?(String)
+      self.sz_extension = @extension.length
+
+      @payload        = SEKISHIKI.to_bin args[:payload] if
+        args[:payload].instance_of?(String)
+      self.sz_payload = @payload.length
+
+      @padding = SEKISHIKI.to_bin args[:padding] if
+        args[:padding].instance_of?(String)
+    end
+
+    def header
+      @version + @flags + @otp_code + @dst + @src + @sz_extension + @sz_payload
+    end
+
+    def packet
+      header + @extension + @payload + @padding
+    end
+
+    def pkt
+      packet
+    end
+
+    def version
+      SEKISHIKI.bin2hex @version
+    end
+
+    def version=(version)
+      return unless version.instance_of?(String)
+
+      @version = SEKISHIKI.to_bin version, 4
+    end
+
+    def flags
+      SEKISHIKI.bin2int @flags
+    end
+
+    def flags=(flags)
+      return unless flags.instance_of?(String) || flags.instance_of?(Integer)
+
+      @flags = SEKISHIKI.to_bin flags, 1
+    end
+
+    def otp_code
+      format "%06d", SEKISHIKI.bin2hex(@otp_code).to_i
+    end
+
+    def otp_code=(code)
+      return unless code.instance_of?(String) || code.instance_of?(Integer)
+
+      @otp_code = SEKISHIKI.to_bin code, 3
+    end
+
+    def otp_now
+      return unless @otp.instance_of?(ROTP::TOTP)
+
+      self.otp_code = @otp.now
+    end
+
+    def otp_secret
+      (@otp.instance_of?(ROTP::TOTP) && @otp.secret) || ""
+    end
+
+    def otp=(secret)
+      return unless secret.instance_of?(String) ||
+                    secret.instance_of?(ROTP::TOTP)
+
+      @otp = if secret.instance_of?(String) && !secret.empty?
+               ROTP::TOTP.new(secret)
+             elsif secret.instance_of?(ROTP::TOTP)
+               secret
+             end
+    end
+
+    def otp_verify
+      self.class.otp_verify @otp, otp_code
+    end
+
+    def dst
+      SEKISHIKI.bin2hex @dst
+    end
+
+    def dst=(key)
+      return unless key.instance_of?(String)
+
+      @dst = SEKISHIKI.to_bin key, 32
+    end
+
+    def src
+      SEKISHIKI.bin2hex @src
+    end
+
+    def src=(key)
+      return unless key.instance_of?(String)
+
+      @src = SEKISHIKI.to_bin key, 32
+    end
+
+    def sz_extension
+      SEKISHIKI.bin2int @sz_extension
+    end
+
+    def sz_extension=(size)
+      return unless size.instance_of?(String) || size.instance_of?(Integer)
+
+      @sz_extension = SEKISHIKI.to_bin size, 2
+    end
+
+    def sz_payload
+      SEKISHIKI.bin2int @sz_payload
+    end
+
+    def sz_payload=(size)
+      return unless size.instance_of?(String) || size.instance_of?(Integer)
+
+      @sz_payload = SEKISHIKI.to_bin size, 2
+    end
+
+    def padding_zero(amount)
+      return unless amount.instance_of?(Integer)
+
+      @padding = SEKISHIKI.data_gen amount, false
+    end
+
+    def padding_random(amount)
+      return unless amount.instance_of?(Integer)
+
+      @padding = SEKISHIKI.data_gen amount, true
+    end
+
+    # NOTE: avoid using any of the following class methods! Instead, use their
+    # equivalent instance methods
+
+    def self.otp_verify(otp, otp_code)
+      (otp.instance_of?(ROTP::TOTP) && otp_code.instance_of?(String) &&
+        !otp_code.empty? && otp.verify(otp_code)) || nil
+    end
+  end
+end

data/lib/sekishiki/utils.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "rbnacl"
+
+# Utils for data conversion and encoding
+module SEKISHIKI
+  def data_gen(amount, random)
+    return "" unless amount.instance_of?(Integer)
+
+    return "\x00".b * amount unless random
+
+    data = String.new
+    (1..amount).each do |_|
+      data.insert(-1, rand(0xFF).chr)
+    end
+    data.b
+  end
+
+  def hex2bin(hex)
+    prefix = "0" if hex.instance_of?(String) && hex.length.odd?
+    RbNaCl::Util.hex2bin(prefix.to_s + hex)
+  end
+
+  def int2bin(int)
+    hex2bin(int.to_s(16))
+  end
+
+  def to_bin(data, length = 0)
+    return "" unless data.instance_of?(String) || data.instance_of?(Integer)
+
+    ret = if data.instance_of?(String)
+            if data.encoding == Encoding::ASCII_8BIT
+              data
+            else
+              hex2bin data
+            end
+          elsif data.instance_of?(Integer)
+            int2bin data
+          end
+
+    if length > ret.length
+      data_gen(length - ret.length, false) + ret
+    elsif length.positive? && length < ret.length
+      ret[-length..]
+    else
+      ret
+    end
+  end
+
+  def bin2hex(bin)
+    RbNaCl::Util.bin2hex(bin)
+  end
+
+  def bin2int(bin)
+    bin2hex(bin).to_i 16
+  end
+
+  module_function :data_gen, :hex2bin, :int2bin, :to_bin, :bin2hex, :bin2int
+end

data/lib/sekishiki/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SEKISHIKI
+  VERSION = "20260821"
+end

data/lib/sekishiki.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "sekishiki/crypto"
+require "sekishiki/packet"
+require "sekishiki/utils"
+require "sekishiki/version"
+
+module SEKISHIKI
+  class Error < StandardError; end
+  # TODO: add wrappers and/or other needed features/methods. This might be
+  # handful for a CLI version of Sekishiki
+end