eciesrb 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8853c211ef575ae689839e550d6db8afd07a5442d7ac38ba459148cf72f9e6fb
+  data.tar.gz: 65b75a723ae0d3411064286a1e2d6637c12c20a1909581bc6a16f102e3bf801e
+SHA512:
+  metadata.gz: cacd472056489a127ca14ebf199b7804ea5aedd67880cc7fc34becfb85579f3899d64750e2a64cb1d18a65f171de7792e0f5e5600f0c88e468c56e965adf8e06
+  data.tar.gz: 3de9f4265d674d6e285c9be76956ca615255cd6f339526b7ca3ecf9fe31fea9f985d7df25e3f521f60a616d48a5cd5d1db82dca2c46d6b88b72c465e31103297

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.0.1
+
+- First alpha release

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Weiliang Li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,102 @@
+# eciesrb
+
+[![Gem Version](https://badge.fury.io/rb/eciesrb.svg)](https://badge.fury.io/rb/eciesrb)
+[![License](https://img.shields.io/github/license/ecies/rb.svg)](https://github.com/ecies/rb)
+[![CI](https://img.shields.io/github/actions/workflow/status/ecies/rb/ci.yml)](https://github.com/ecies/rb/actions)
+
+Elliptic Curve Integrated Encryption Scheme for secp256k1 in Ruby.
+
+This is a Ruby port of [eciespy](https://github.com/ecies/py).
+
+## Prerequisite
+
+Make sure you have secp256k1 and openssl installed, if not:
+
+```bash
+brew install secp256k1 openssl
+```
+
+Then set environment variables:
+
+```bash
+export C_INCLUDE_PATH=$(brew --prefix secp256k1)/include
+```
+
+## Install
+
+```bash
+gem install eciesrb
+```
+
+## Quick Start
+
+```ruby
+# examples/quickstart.rb
+require "ecies"
+
+# Generate a secret key
+sk = Ecies.generate_key
+raw_sk = Ecies.decode_hex(sk.send(:serialize))
+raw_pk = sk.pubkey.serialize(compressed: false)
+
+# Encrypt data with the receiver's public key
+plaintext = "Hello, World!"
+encrypted = Ecies.encrypt(raw_pk, plaintext)
+
+# Decrypt data with the receiver's secret key
+decrypted = Ecies.decrypt(raw_sk, encrypted)
+puts decrypted  # => "Hello, World!"
+```
+
+## Sponsors
+
+<a href="https://dotenvx.com"><img alt="dotenvx" src="https://dotenvx.com/logo.png" width="200" height="200"/></a>
+
+## Configuration
+
+You can customize the encryption behavior using a `Config` object:
+
+```ruby
+# examples/config.rb
+require "ecies"
+
+Ecies::DEFAULT_CONFIG.is_ephemeral_key_compressed = true   # Use compressed ephemeral public key
+Ecies::DEFAULT_CONFIG.is_hkdf_key_compressed = true        # Use compressed key for HKDF
+Ecies::DEFAULT_CONFIG.symmetric_nonce_length = 16          # Nonce length for AES-GCM (default: 16)
+```
+
+### Configuration Parameters
+
+- `is_ephemeral_key_compressed` (Boolean): Whether to use compressed format for the ephemeral public key. Default: `false`
+- `is_hkdf_key_compressed` (Boolean): Whether to use compressed format for HKDF key derivation. Default: `false`
+- `symmetric_nonce_length` (Integer): The nonce length for AES-GCM encryption. Options: `12`, `16`. Default: `16`
+
+## API Reference
+
+### `encrypt(receiver_pk, data, config = DEFAULT_CONFIG)`
+
+Encrypts data using the receiver's public key.
+
+**Parameters:**
+
+- `receiver_pk` (String): The receiver's public key (raw bytes, serialized)
+- `data` (String): The plaintext data to encrypt (raw bytes)
+- `config` (Ecies::Config): Optional configuration object
+
+**Returns:** (String) The encrypted data (ephemeral public key + encrypted data)
+
+### `decrypt(receiver_sk, data, config = DEFAULT_CONFIG)`
+
+Decrypts data using the receiver's secret key.
+
+**Parameters:**
+
+- `receiver_sk` (String): The receiver's secret key (raw bytes, serialized)
+- `data` (String): The encrypted data (ephemeral public key + encrypted data)
+- `config` (Ecies::Config): Optional configuration object
+
+**Returns:** (String) The decrypted plaintext data (raw bytes)
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md).

data/eciesrb.gemspec

@@ -0,0 +1,14 @@
+Gem::Specification.new do |s|
+  s.name = "eciesrb"
+  s.version = "0.0.1"
+  s.summary = "Elliptic Curve Integrated Encryption Scheme for secp256k1 in Ruby"
+  s.description = "Elliptic Curve Integrated Encryption Scheme for secp256k1 in Ruby, based on libsecp256k1 and OpenSSL."
+  s.authors = ["Weiliang Li"]
+  s.email = "to.be.impressive@gmail.com"
+  s.files = Dir["lib/**/**.rb"] + ["eciesrb.gemspec", "README.md", "LICENSE", "CHANGELOG.md"]
+  s.homepage = "https://github.com/ecies/rb"
+  s.license = "MIT"
+  s.add_dependency "libsecp256k1", "~> 0.6.1"
+  s.add_dependency "openssl", "~> 3.3"
+  s.required_ruby_version = ">= 3.2"
+end

data/lib/ecies/config.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Ecies
+  # Configuration class for ECIES settings.
+  class Config
+    attr_accessor :is_ephemeral_key_compressed, :is_hkdf_key_compressed, :symmetric_nonce_length
+
+    def initialize(
+      is_ephemeral_key_compressed: false,
+      is_hkdf_key_compressed: false,
+      symmetric_nonce_length: 16
+    )
+      @is_ephemeral_key_compressed = is_ephemeral_key_compressed
+      @is_hkdf_key_compressed = is_hkdf_key_compressed
+      @symmetric_nonce_length = symmetric_nonce_length
+    end
+  end
+
+  DEFAULT_CONFIG = Config.new
+end

data/lib/ecies/elliptic.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "secp256k1"
+require_relative "symmetric"
+require_relative "hash"
+
+module Ecies
+  # Generates a new random Secp256k1 private key.
+  # @return [Secp256k1::PrivateKey] The generated private key.
+  def generate_key
+    loop do
+      sk = Secp256k1::PrivateKey.new
+      return sk
+    rescue ArgumentError
+    end
+  end
+
+  # Performs elliptic key encapsulation.
+  #
+  # @param private_key [String] Private key bytes
+  # @param peer_public_key [String] Peer's public key bytes
+  # @param is_compressed [Boolean] Whether to use compressed format (default: false)
+  #
+  # @return [String] HKDF-SHA256 derived 32-byte key
+  def encapsulate(private_key, peer_public_key, is_compressed = false)
+    sk = Secp256k1::PrivateKey.new(privkey: private_key, raw: true)
+    peer_pk = Secp256k1::PublicKey.new(pubkey: peer_public_key, raw: true)
+    shared_point = peer_pk.tweak_mul(private_key)
+
+    master = sk.pubkey.serialize(compressed: is_compressed) +
+      shared_point.serialize(compressed: is_compressed)
+    derive_key(master)
+  end
+
+  # Performs elliptic key decapsulation.
+  # @param public_key [String] Public key bytes
+  # @param peer_private_key [String] Peer's private key bytes
+  # @param is_compressed [Boolean] Whether to use compressed format (default: false)
+  # @return [String] HKDF-SHA256 derived 32-byte key
+  def decapsulate(public_key, peer_private_key, is_compressed = false)
+    pk = Secp256k1::PublicKey.new(pubkey: public_key, raw: true)
+    shared_point = pk.tweak_mul(peer_private_key)
+    master = pk.serialize(compressed: is_compressed) +
+      shared_point.serialize(compressed: is_compressed)
+    derive_key(master)
+  end
+
+  module_function :generate_key, :encapsulate, :decapsulate
+end

data/lib/ecies/hash.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Ecies
+  # Derives a 32-byte key from the given master key using HKDF with SHA256.
+  #
+  # @param master [String] The input master key (binary string).
+  # @return [String] The derived 32-byte key (binary string).
+  def derive_key(master)
+    OpenSSL::KDF.hkdf(master, salt: "", info: "", length: 32, hash: "SHA256")
+  end
+
+  module_function :derive_key
+end

data/lib/ecies/hex.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Ecies
+  # Decodes a hex string (with optional "0x" prefix) into raw bytes.
+  # @param [String] str The hex string to decode.
+  # return [String] The decoded raw bytes.
+  def decode_hex(str)
+    if str.start_with?("0x", "0X")
+      str = str[2..]
+    end
+    [str].pack("H*")
+  end
+
+  # Encodes raw bytes into a hex string without "0x" prefix.
+  # @param [String] bytes The raw bytes to encode.
+  # @return [String] The encoded hex string without "0x" prefix.
+  def encode_hex(bytes)
+    bytes.unpack1("H*")
+  end
+
+  module_function :decode_hex, :encode_hex
+end

data/lib/ecies/symmetric.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Ecies
+  AEAD_TAG_LENGTH = 16
+
+  # Encrypts plain text using symmetric AES-256-GCM encryption.
+  #
+  # @param algorithm [Symbol] The encryption algorithm to use (must be :aes-256-gcm)
+  # @param key [String] The encryption key (must be 32 bytes for AES-256)
+  # @param plain_text [String] The data to encrypt
+  # @param nonce_length [Integer] The length of the nonce/IV to generate
+  # @param aad [String] Additional authenticated data (optional, defaults to empty string)
+  #
+  # @return [String] The encrypted data formatted as: nonce + auth_tag + cipher_text
+  #
+  # @raise [ArgumentError] If the algorithm is not :aes-256-gcm
+  #
+  # @example
+  #   key = OpenSSL::Random.random_bytes(32)
+  #   encrypted = Ecies.sym_encrypt(:"aes-256-gcm", key, "Hello World", 12)
+  def sym_encrypt(algorithm, key, plain_text, nonce_length, aad = "")
+    if algorithm != :"aes-256-gcm"
+      raise ArgumentError, "Unsupported algorithm: #{algorithm}"
+    end
+
+    nonce = OpenSSL::Random.random_bytes(nonce_length)
+    cipher = OpenSSL::Cipher.new(algorithm.to_s).encrypt
+    cipher.key = key
+    cipher.iv_len = nonce_length
+    cipher.iv = nonce
+    cipher.auth_data = aad
+
+    cipher_text = cipher.update(plain_text) + cipher.final
+    tag = cipher.auth_tag
+    nonce + tag + cipher_text
+  end
+
+  # Decrypts cipher text that was encrypted using symmetric AES-256-GCM encryption.
+  #
+  # @param algorithm [Symbol] The encryption algorithm to use (must be :aes-256-gcm)
+  # @param key [String] The decryption key (must match the encryption key)
+  # @param cipher_text [String] The encrypted data (formatted as: nonce + auth_tag + cipher_text)
+  # @param nonce_length [Integer] The length of the nonce/IV used during encryption
+  # @param aad [String] Additional authenticated data (must match the value used during encryption)
+  #
+  # @return [String] The decrypted plain text
+  #
+  # @raise [ArgumentError] If the algorithm is not :aes-256-gcm
+  # @raise [OpenSSL::Cipher::CipherError] If authentication fails or decryption fails
+  #
+  # @example
+  #   key = OpenSSL::Random.random_bytes(32)
+  #   encrypted = Ecies.sym_encrypt(:"aes-256-gcm", key, "Hello World", 12)
+  #   decrypted = Ecies.sym_decrypt(:"aes-256-gcm", key, encrypted, 12)
+  def sym_decrypt(algorithm, key, cipher_text, nonce_length, aad = "")
+    if algorithm != :"aes-256-gcm"
+      raise ArgumentError, "Unsupported algorithm: #{algorithm}"
+    end
+
+    nonce = cipher_text[0, nonce_length]
+    tag = cipher_text[nonce_length, AEAD_TAG_LENGTH]
+    encrypted = cipher_text[nonce_length + AEAD_TAG_LENGTH..]
+    decipher = OpenSSL::Cipher.new(algorithm.to_s).decrypt
+    decipher.key = key
+    decipher.iv_len = nonce_length
+    decipher.iv = nonce
+    decipher.auth_tag = tag
+    decipher.auth_data = aad
+    decipher.update(encrypted) + decipher.final
+  end
+
+  module_function :sym_encrypt, :sym_decrypt
+end

data/lib/ecies.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "ecies/config"
+require "ecies/hex"
+require "ecies/hash"
+require "ecies/elliptic"
+require "ecies/symmetric"
+
+module Ecies
+  COMPRESSED_PUBLIC_KEY_SIZE = 33
+  UNCOMPRESSED_PUBLIC_KEY_SIZE = 65
+
+  # Encrypt with receiver's public key
+  #
+  # @param [String] receiver_pk The receiver's public key (serialized, raw bytes).
+  # @param [String] data The plaintext data to encrypt (raw bytes).
+  # @param [Ecies::Config] config The configuration object (optional).
+  # @return [String] The encrypted data (ephemeral public key + encrypted data).
+  def encrypt(receiver_pk, data, config = DEFAULT_CONFIG)
+    ephemeral_sk = generate_key
+    raw_ephemeral_sk = decode_hex(ephemeral_sk.send(:serialize))
+    ephemeral_pk = ephemeral_sk.pubkey.serialize(compressed: config.is_ephemeral_key_compressed)
+    sym_key = encapsulate(raw_ephemeral_sk, receiver_pk, config.is_hkdf_key_compressed)
+    encrypted = sym_encrypt(:"aes-256-gcm", sym_key, data, config.symmetric_nonce_length)
+    ephemeral_pk + encrypted
+  end
+
+  # Decrypt with receiver's secret key
+  #
+  # @param [String] receiver_sk The receiver's secret key (serialized, raw bytes).
+  # @param [String] data The encrypted data (ephemeral public key + encrypted data).
+  # @param [Ecies::Config] config The configuration object (optional).
+  # @return [String] The decrypted plaintext data (raw bytes).
+  def decrypt(receiver_sk, data, config = DEFAULT_CONFIG)
+    pk_size = config.is_ephemeral_key_compressed ?
+      COMPRESSED_PUBLIC_KEY_SIZE : UNCOMPRESSED_PUBLIC_KEY_SIZE
+    ephemeral_pk = data[0, pk_size]
+    encrypted = data[pk_size..]
+    sym_key = decapsulate(ephemeral_pk, receiver_sk, config.is_hkdf_key_compressed)
+    sym_decrypt(:"aes-256-gcm", sym_key, encrypted, config.symmetric_nonce_length)
+  end
+
+  module_function :encrypt, :decrypt
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: eciesrb
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Weiliang Li
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: libsecp256k1
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.1
+- !ruby/object:Gem::Dependency
+  name: openssl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+description: Elliptic Curve Integrated Encryption Scheme for secp256k1 in Ruby, based
+  on libsecp256k1 and OpenSSL.
+email: to.be.impressive@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- eciesrb.gemspec
+- lib/ecies.rb
+- lib/ecies/config.rb
+- lib/ecies/elliptic.rb
+- lib/ecies/hash.rb
+- lib/ecies/hex.rb
+- lib/ecies/symmetric.rb
+homepage: https://github.com/ecies/rb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Elliptic Curve Integrated Encryption Scheme for secp256k1 in Ruby
+test_files: []