hpke 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c0ff20003913867f648466cb8136e73218c7dd917087c98f7d86ef8fd2049a11
+  data.tar.gz: 47901efa463ad51eebe04bface377e9dda4c24497a4b12039c64bc966b98c2d9
+SHA512:
+  metadata.gz: 1bbd503dd86c43bcb19fc188338cc9119b35a2bc5e6812a1404c19f8e198b7c71c0a18d3e1ff81d9ee3658575044995dba5ac092229b61298c7e79ed2e679faf
+  data.tar.gz: ac0ac0b079d9a8b8c3d7e60d6d90e0109d31150ae44f433b815d1a62fce9b3bb70dc707112c7a7155f94f3e7df171a11fa3ef97ba4fccbf509a7d911866b170b

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in hpke.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"

data/Gemfile.lock

@@ -0,0 +1,37 @@
+PATH
+  remote: .
+  specs:
+    hpke (0.1.0)
+      openssl (~> 3.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.5.0)
+    openssl (3.0.2)
+    rake (13.0.6)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.2)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.6)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.1)
+
+PLATFORMS
+  arm64-darwin-22
+  x86_64-linux
+
+DEPENDENCIES
+  hpke!
+  rake (~> 13.0)
+  rspec (~> 3.0)
+
+BUNDLED WITH
+   2.4.10

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Ryo Kajiwara
+
+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,120 @@
+# hpke-rb
+
+Hybrid Public Key Encryption (HPKE; [RFC 9180](https://datatracker.ietf.org/doc/html/rfc9180)) in Ruby
+
+## Note
+
+This is still in very early development, so:
+
+- APIs are subject to change
+    - Especially the instantation interface of KEM and HPKE suite
+- This is tested against test vectors supplied by the authors of the RFC, but is not formally audited for security. Please be aware of this when using in production.
+
+## Supported Features
+
+Supports all modes, KEMs, AEAD functions in RFC 9180.
+
+- HPKE Modes
+    - Base
+    - PSK
+    - Auth
+    - AuthPSK
+- Key Encapsulation Mechanisms (KEMs)
+    - DHKEM(P-256, HKDF-SHA256)
+    - DHKEM(P-384, HKDF-SHA384)
+    - DHKEM(P-521, HKDF-SHA512)
+    - DHKEM(X25519, HKDF-SHA256)
+    - DHKEM(X448, HKDF-SHA512)
+- Key Derivation Functions (KDFs)
+    - HKDF-SHA256
+    - HKDF-SHA384
+    - HKDF-SHA512
+- AEAD Functions
+    - AES-128-GCM
+    - AES-256-GCM
+    - ChaCha20-Poly1305
+    - Export Only
+
+## Supported Environments
+
+- OpenSSL 3.0 or higher
+    - This is due to the changes in instantiation of public/private key pairs from OpenSSL 1.1 series to OpenSSL 3.0 series
+- Ruby 3.1 or higher
+    - Ruby 3.1 comes with OpenSSL 3.0 support
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add hpke
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install hpke
+
+## Usage
+
+(example shows Base mode)
+
+```ruby
+# instantiate HPKE suite
+# first 2 parameters specify the curve and hash to be used in the KEM,
+# third parameter specifies the hash to be used in the KDF (of HPKE suite),
+# fourth parameter specifies the AEAD function
+
+# we will generate a different instance just for demonstration to show that nothing secret is stored in the HPKE suite instance
+hpke_s = HPKE.new(:x25519, :sha256, :sha256, :aes_128_gcm)
+hpke_r = HPKE.new(:x25519, :sha256, :sha256, :aes_128_gcm)
+
+# get a OpenSSL::PKey::PKey instance by either generating a key or loading a key from a PEM
+# see https://ruby-doc.org/3.2.2/exts/openssl/OpenSSL/PKey/PKey.html
+# on the sender's end
+sender_key_pair = OpenSSL::PKey.generate_key('X25519')
+receiver_key_pair = OpenSSL::PKey.generate_key('X25519')
+
+# Sender setup
+# Sender knows the receiver's public key (in PEM format, in most cases), so load that into a PKey
+receiver_public_key = OpenSSL::PKey.read(receiver_key_pair.public_to_pem)
+encap_result = hpke_s.setup_base_s(receiver_public_key, 'info')
+# This returns a hash where :enc key contains the key encapsulation,
+# and :context_s contains a HPKE::ContextS instance, which is used for encryption later on.
+context_s = encap_result[:context_s]
+# Note that :enc contains raw bytes, so when passing to the receiver, it is advised to pass the encapsulation using Base64-encoded values
+enc_base64 = Base64.encode64(encap_result[:enc])
+
+# Then on the receiver's end
+# decode the encapsulated value
+enc = Base64.decode64(enc_base64)
+# then use that value to generate a HPKE::ContextR instance to use for decryption
+context_r = hpke_r.setup_base_r(enc, receiver_key_pair, 'info')
+
+# sender encrypts a message
+# note that the "sequence number" is incremented each time `seal` and `open` is used
+ciphertext = context_s.seal('authentication_associated_data', 'plaintext')
+# this is also in raw bytes, so when sending, encoding with Base64 is advised
+
+# then receiver decrypts the ciphertext
+context_r.open('authentication_associated_data', ciphertext)
+```
+
+- Curve names (parameter 1)
+    - `:p_256`, `:p_384`, `:p_521`, `:x25519`, `:x448`
+        - Note: `:p_256` corresponds to `prime256v1`, `:p_384` corresponds to `secp384r1`, and `:p_521` corresponds to `secp521r1` in OpenSSL
+- Hash names (parameter 2 and 3)
+    - `:sha256`, `:sha384`, `:sha512`
+- AEAD function names (parameter 4)
+    - `:aes_128_gcm`, `:aes_256_gcm`, `:chacha20_poly1305`, `:`
+
+## 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`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/sylph01/hpke-rb.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/hpke/dhkem.rb

@@ -0,0 +1,368 @@
+require 'openssl'
+require 'securerandom'
+require_relative 'hkdf'
+require_relative 'util'
+
+class HPKE::DHKEM
+  include HPKE::Util
+
+  def initialize(hash_name)
+    @hkdf = HPKE::HKDF.new(hash_name)
+  end
+
+  def encap(pk_r)
+    pkey_e = generate_key_pair()
+    dh = pkey_e.derive(pk_r)
+    enc = serialize_public_key(pkey_e)
+
+    pkrm = serialize_public_key(pk_r)
+    kem_context = enc + pkrm
+
+    shared_secret = extract_and_expand(dh, kem_context, kem_suite_id)
+    {
+      shared_secret: shared_secret,
+      enc: enc
+    }
+  end
+
+  def auth_encap(pk_r, sk_s)
+    pkey_e = generate_key_pair()
+    dh = pkey_e.derive(pk_r) + sk_s.derive(pk_r)
+    enc = serialize_public_key(pkey_e)
+
+    pkrm = serialize_public_key(pk_r)
+    pksm = serialize_public_key(sk_s)
+    kem_context = enc + pkrm + pksm
+
+    shared_secret = extract_and_expand(dh, kem_context, kem_suite_id)
+    {
+      shared_secret: shared_secret,
+      enc: enc
+    }
+  end
+
+  def decap(enc, sk_r)
+    pk_e = deserialize_public_key(enc)
+    dh = sk_r.derive(pk_e)
+
+    pkrm = serialize_public_key(sk_r)
+    kem_context = enc + pkrm
+
+    shared_secret = extract_and_expand(dh, kem_context, kem_suite_id)
+    shared_secret
+  end
+
+  def auth_decap(enc, sk_r, pk_s)
+    pk_e = deserialize_public_key(enc)
+    dh = sk_r.derive(pk_e) + sk_r.derive(pk_s)
+
+    pkrm = serialize_public_key(sk_r)
+    pksm = serialize_public_key(pk_s)
+    kem_context = enc + pkrm + pksm
+
+    shared_secret = extract_and_expand(dh, kem_context, kem_suite_id)
+    shared_secret
+  end
+
+  def encap_fixed(pk_r, ikm_e)
+    pkey_e = derive_key_pair(ikm_e)
+    dh = pkey_e.derive(pk_r)
+    enc = serialize_public_key(pkey_e)
+
+    pkrm = serialize_public_key(pk_r)
+    kem_context = enc + pkrm
+
+    shared_secret = extract_and_expand(dh, kem_context, kem_suite_id)
+    {
+      shared_secret: shared_secret,
+      enc: enc
+    }
+  end
+
+  def auth_encap_fixed(pk_r, sk_s, ikm_e)
+    pkey_e = derive_key_pair(ikm_e)
+    dh = pkey_e.derive(pk_r) + sk_s.derive(pk_r)
+    enc = serialize_public_key(pkey_e)
+
+    pkrm = serialize_public_key(pk_r)
+    pksm = serialize_public_key(sk_s)
+    kem_context = enc + pkrm + pksm
+
+    shared_secret = extract_and_expand(dh, kem_context, kem_suite_id)
+    {
+      shared_secret: shared_secret,
+      enc: enc
+    }
+  end
+
+  def generate_key_pair
+    derive_key_pair(SecureRandom.random_bytes(n_sk))
+  end
+
+  # ---- functions for Edwards curves (X25519, X448) ----
+  def derive_key_pair(ikm)
+    dkp_prk = @hkdf.labeled_extract('', 'dkp_prk', ikm, kem_suite_id)
+    sk = @hkdf.labeled_expand(dkp_prk, 'sk', '', n_sk, kem_suite_id)
+
+    create_key_pair_from_secret(sk)
+  end
+
+  def serialize_public_key(pk)
+    pk.public_to_der[-n_pk, n_pk]
+  end
+
+  def deserialize_public_key(serialized_pk)
+    asn1_seq_pub = OpenSSL::ASN1.Sequence([
+      OpenSSL::ASN1.Sequence([
+        OpenSSL::ASN1.ObjectId(asn1_oid)
+      ]),
+      OpenSSL::ASN1.BitString(serialized_pk)
+    ])
+
+    OpenSSL::PKey.read(asn1_seq_pub.to_der)
+  end
+
+  private
+  
+  def kem_suite_id
+    'KEM' + i2osp(kem_id, 2)
+  end
+
+  def extract_and_expand(dh, kem_context, suite_id)
+    eae_prk = @hkdf.labeled_extract('', 'eae_prk', dh, suite_id)
+
+    @hkdf.labeled_expand(eae_prk, 'shared_secret', kem_context, n_secret, suite_id)
+  end
+end
+
+class HPKE::DHKEM::EC < HPKE::DHKEM
+  def derive_key_pair(ikm)
+    dkp_prk = @hkdf.labeled_extract('', 'dkp_prk', ikm, kem_suite_id)
+    sk = 0
+    counter = 0
+    while sk == 0 || sk >= order do
+      raise Exception.new('DeriveKeyPairError') if counter > 255
+
+      bytes = @hkdf.labeled_expand(dkp_prk, 'candidate', i2osp(counter, 1), n_sk, kem_suite_id)
+      bytes[0] = (bytes[0].ord & bitmask).chr
+      sk = os2ip(bytes)
+      counter += 1
+    end
+
+    create_key_pair_from_secret(bytes)
+  end
+
+  def create_key_pair_from_secret(secret)
+    asn1_seq = OpenSSL::ASN1.Sequence([
+      OpenSSL::ASN1.Integer(1),
+      OpenSSL::ASN1.OctetString(secret),
+      OpenSSL::ASN1.ObjectId(curve_name, 0, :EXPLICIT)
+    ])
+
+    OpenSSL::PKey.read(asn1_seq.to_der)
+  end
+
+  def serialize_public_key(pk)
+    pk.public_key.to_bn.to_s(2)
+  end
+
+  def deserialize_public_key(serialized_pk)
+    asn1_seq = OpenSSL::ASN1.Sequence([
+      OpenSSL::ASN1.Sequence([
+        OpenSSL::ASN1.ObjectId("id-ecPublicKey"),
+        OpenSSL::ASN1.ObjectId(curve_name)
+      ]),
+      OpenSSL::ASN1.BitString(serialized_pk)
+    ])
+
+    OpenSSL::PKey.read(asn1_seq.to_der)
+  end
+end
+
+class HPKE::DHKEM::EC::P_256 < HPKE::DHKEM::EC
+  def kem_id
+    0x0010
+  end
+
+  private
+
+  def n_secret
+    32
+  end
+
+  def n_enc
+    65
+  end
+
+  def n_pk
+    65
+  end
+
+  def n_sk
+    32
+  end
+
+  def order
+    0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551
+  end
+
+  def curve_name
+    'prime256v1'
+  end
+
+  def bitmask
+    0xff
+  end
+end
+
+class HPKE::DHKEM::EC::P_384 < HPKE::DHKEM::EC
+  def kem_id
+    0x0011
+  end
+
+  private
+
+  def n_secret
+    48
+  end
+
+  def n_enc
+    97
+  end
+
+  def n_pk
+    97
+  end
+
+  def n_sk
+    48
+  end
+
+  def order
+    0xffffffffffffffffffffffffffffffffffffffffffffffffc7634d81f4372ddf581a0db248b0a77aecec196accc52973
+  end
+
+  def curve_name
+    'secp384r1'
+  end
+
+  def bitmask
+    0xff
+  end
+end
+
+class HPKE::DHKEM::EC::P_521 < HPKE::DHKEM::EC
+  def kem_id
+    0x0012
+  end
+
+  private
+
+  def n_secret
+    64
+  end
+
+  def n_enc
+    133
+  end
+
+  def n_pk
+    133
+  end
+
+  def n_sk
+    66
+  end
+
+  def order
+    0x01fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffa51868783bf2f966b7fcc0148f709a5d03bb5c9b8899c47aebb6fb71e91386409
+  end
+
+  def curve_name
+    'secp521r1'
+  end
+
+  def bitmask
+    0x01
+  end
+end
+
+class HPKE::DHKEM::X25519 < HPKE::DHKEM
+  def kem_id
+    0x0020
+  end
+
+  def create_key_pair_from_secret(secret)
+    asn1_seq = OpenSSL::ASN1.Sequence([
+      OpenSSL::ASN1.Integer(0),
+      OpenSSL::ASN1.Sequence([
+        OpenSSL::ASN1.ObjectId(asn1_oid)
+      ]),
+      OpenSSL::ASN1.OctetString("\x04\x20" + secret)
+    ])
+
+    OpenSSL::PKey.read(asn1_seq.to_der)
+  end
+
+  private
+
+  def n_secret
+    32
+  end
+
+  def n_enc
+    32
+  end
+
+  def n_pk
+    32
+  end
+
+  def n_sk
+    32
+  end
+
+  def asn1_oid
+    '1.3.101.110'
+  end
+end
+
+class HPKE::DHKEM::X448 < HPKE::DHKEM
+  def kem_id
+    0x0021
+  end
+
+  def create_key_pair_from_secret(secret)
+    asn1_seq = OpenSSL::ASN1.Sequence([
+      OpenSSL::ASN1.Integer(0),
+      OpenSSL::ASN1.Sequence([
+        OpenSSL::ASN1.ObjectId(asn1_oid)
+      ]),
+      OpenSSL::ASN1.OctetString("\x04\x38" + secret)
+    ])
+
+    OpenSSL::PKey.read(asn1_seq.to_der)
+  end
+
+  private
+
+  def n_secret
+    64
+  end
+
+  def n_enc
+    56
+  end
+
+  def n_pk
+    56
+  end
+
+  def n_sk
+    56
+  end
+
+  def asn1_oid
+    '1.3.101.111'
+  end
+end

data/lib/hpke/hkdf.rb

@@ -0,0 +1,100 @@
+require 'openssl'
+require_relative 'util'
+
+class HPKE::HKDF
+  include HPKE::Util
+
+  attr_reader :kdf_id
+
+  ALGORITHMS = {
+    sha256: {
+      name: 'SHA256',
+      kdf_id: 1
+    },
+    sha384: {
+      name: 'SHA384',
+      kdf_id: 2
+    },
+    sha512: {
+      name: 'SHA512',
+      kdf_id: 3
+    }
+  }
+
+  def n_h
+    @digest.digest_length
+  end
+
+  def initialize(alg_name)
+    if algorithm = ALGORITHMS[alg_name]
+      @digest = OpenSSL::Digest.new(algorithm[:name])
+      @kdf_id = algorithm[:kdf_id]
+    else
+      raise Exception.new('Unknown hash algorithm')
+    end
+  end
+
+  def hmac(key, data)
+    OpenSSL::HMAC.digest(@digest, key, data)
+  end
+
+  def extract(salt, ikm)
+    hmac(salt, ikm)
+  end
+
+  def expand(prk, info, len)
+    n = (len.to_f / @digest.digest_length).ceil
+    t = ['']
+    for i in 0..n do
+      t << hmac(prk, t[i] + info + (i + 1).chr)
+    end
+    t_concat = t.join
+    t_concat[0..(len - 1)]
+  end
+
+  def labeled_extract(salt, label, ikm, suite_id)
+    labeled_ikm = 'HPKE-v1' + suite_id + label + ikm
+    extract(salt, labeled_ikm)
+  end
+
+  def labeled_expand(prk, label, info, l, suite_id)
+    labeled_info = i2osp(l, 2) + 'HPKE-v1' + suite_id + label + info
+    expand(prk, labeled_info, l)
+  end
+end
+
+class HPKE::HKDF::HMAC_SHA256 < HPKE::HKDF
+  private
+
+  def digest_algorithm
+    'SHA256'
+  end
+
+  def kdf_id
+    1
+  end
+end
+
+class HPKE::HKDF::HMAC_SHA384 < HPKE::HKDF
+  private
+
+  def digest_algorithm
+    'SHA384'
+  end
+
+  def kdf_id
+    2
+  end
+end
+
+class HPKE::HKDF::HMAC_SHA512 < HPKE::HKDF
+  private
+  
+  def digest_algorithm
+    'SHA512'
+  end
+
+  def kdf_id
+    3
+  end
+end

data/lib/hpke/util.rb

@@ -0,0 +1,26 @@
+module HPKE::Util
+  def i2osp(n, w)
+    # check n > 0 and n < 256 ** w
+    ret = []
+    for i in 0..(w - 1)
+      ret[w - (i + 1)] = n % 256
+      n = n >> 8
+    end
+    ret.map(&:chr).join
+  end
+
+  def os2ip(x)
+    x.bytes.reduce { |a, b| a * 256 + b }
+  end
+
+  def xor(a, b)
+    if a.bytesize != b.bytesize
+      return false
+    end
+    c = ""
+    for i in 0 .. (a.bytesize - 1)
+      c += (a.bytes[i] ^ b.bytes[i]).chr
+    end
+    c
+  end
+end

data/lib/hpke/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class HPKE
+  VERSION = "0.1.0"
+end

data/lib/hpke.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require_relative "hpke/version"
+
+require 'openssl'
+require_relative './hpke/dhkem'
+require_relative './hpke/util'
+
+class HPKE
+  include HPKE::Util
+
+  attr_reader :kem, :hkdf, :aead_name, :n_k, :n_n, :n_t
+
+  MODES = {
+    base: 0x00,
+    psk: 0x01,
+    auth: 0x02,
+    auth_psk: 0x03
+  }
+  CIPHERS = {
+    aes_128_gcm: {
+      name: 'aes-128-gcm',
+      aead_id: 0x0001,
+      n_k: 16,
+      n_n: 12,
+      n_t: 16
+    },
+    aes_256_gcm: {
+      name: 'aes-256-gcm',
+      aead_id: 0x0002,
+      n_k: 32,
+      n_n: 12,
+      n_t: 16
+    },
+    chacha20_poly1305: {
+      name: 'chacha20-poly1305',
+      aead_id: 0x0003,
+      n_k: 32,
+      n_n: 12,
+      n_t: 16
+    },
+    export_only: {
+      aead_id: 0xffff
+    }
+  }
+  HASHES = {
+    sha256: {
+      name: 'SHA256',
+      kdf_id: 1
+    },
+    sha384: {
+      name: 'SHA384',
+      kdf_id: 2
+    },
+    sha512: {
+      name: 'SHA512',
+      kdf_id: 3
+    }
+  }
+  KEM_CURVES = {
+    p_256: DHKEM::EC::P_256,
+    p_384: DHKEM::EC::P_384,
+    p_521: DHKEM::EC::P_521,
+    x25519: DHKEM::X25519,
+    x448: DHKEM::X448
+  }
+
+  def initialize(kem_curve_name, kem_hash, kdf_hash, aead_cipher)
+    raise Exception.new('Unsupported KEM curve name') if KEM_CURVES[kem_curve_name].nil?
+    raise Exception.new('Unsupported AEAD cipher name') if CIPHERS[aead_cipher].nil?
+
+    @kem = KEM_CURVES[kem_curve_name].new(kem_hash)
+    @hkdf = HKDF.new(kdf_hash)
+    @aead_name = CIPHERS[aead_cipher][:name]
+    @aead_id = CIPHERS[aead_cipher][:aead_id]
+    @n_k = CIPHERS[aead_cipher][:n_k]
+    @n_n = CIPHERS[aead_cipher][:n_n]
+    @n_t = CIPHERS[aead_cipher][:n_t]
+  end
+
+  # public facing APIs
+  def setup_base_s(pk_r, info)
+    encap_result = @kem.encap(pk_r)
+    {
+      enc: encap_result[:enc],
+      context_s: key_schedule_s(MODES[:base], encap_result[:shared_secret], info, DEFAULT_PSK, DEFAULT_PSK_ID)
+    }
+  end
+
+  def setup_base_r(enc, sk_r, info)
+    shared_secret = @kem.decap(enc, sk_r)
+    key_schedule_r(MODES[:base], shared_secret, info, DEFAULT_PSK, DEFAULT_PSK_ID)
+  end
+
+  def setup_psk_s(pk_r, info, psk, psk_id)
+    encap_result = @kem.encap(pk_r)
+    {
+      enc: encap_result[:enc],
+      context_s: key_schedule_s(MODES[:psk], encap_result[:shared_secret], info, psk, psk_id)
+    }
+  end
+
+  def setup_psk_r(enc, sk_r, info, psk, psk_id)
+    shared_secret = @kem.decap(enc, sk_r)
+    key_schedule_r(MODES[:psk], shared_secret, info, psk, psk_id)
+  end
+
+  def setup_auth_s(pk_r, info, sk_s)
+    encap_result = @kem.auth_encap(pk_r, sk_s)
+    {
+      enc: encap_result[:enc],
+      context_s: key_schedule_s(MODES[:auth], encap_result[:shared_secret], info, DEFAULT_PSK, DEFAULT_PSK_ID)
+    }
+  end
+
+  def setup_auth_r(enc, sk_r, info, pk_s)
+    shared_secret = @kem.auth_decap(enc, sk_r, pk_s)
+    key_schedule_r(MODES[:auth], shared_secret, info, DEFAULT_PSK, DEFAULT_PSK_ID)
+  end
+
+  def setup_auth_psk_s(pk_r, info, psk, psk_id, sk_s)
+    encap_result = @kem.auth_encap(pk_r, sk_s)
+    {
+      enc: encap_result[:enc],
+      context_s: key_schedule_s(MODES[:auth_psk], encap_result[:shared_secret], info, psk, psk_id)
+    }
+  end
+
+  def setup_auth_psk_r(enc, sk_r, info, psk, psk_id, pk_s)
+    shared_secret = @kem.auth_decap(enc, sk_r, pk_s)
+    key_schedule_r(MODES[:auth_psk], shared_secret, info, psk, psk_id)
+  end
+
+  # for testing purposes
+  def setup_base_s_fixed(pk_r, info, ikm_e)
+    encap_result = @kem.encap_fixed(pk_r, ikm_e)
+    {
+      enc: encap_result[:enc],
+      context_s: key_schedule_s(MODES[:base], encap_result[:shared_secret], info, DEFAULT_PSK, DEFAULT_PSK_ID)
+    }
+  end
+
+  def setup_psk_s_fixed(pk_r, info, psk, psk_id, ikm_e)
+    encap_result = @kem.encap_fixed(pk_r, ikm_e)
+    {
+      enc: encap_result[:enc],
+      context_s: key_schedule_s(MODES[:psk], encap_result[:shared_secret], info, psk, psk_id)
+    }
+  end
+
+  def setup_auth_s_fixed(pk_r, info, sk_s, ikm_e)
+    encap_result = @kem.auth_encap_fixed(pk_r, sk_s, ikm_e)
+    {
+      enc: encap_result[:enc],
+      context_s: key_schedule_s(MODES[:auth], encap_result[:shared_secret], info, DEFAULT_PSK, DEFAULT_PSK_ID)
+    }
+  end
+
+  def setup_auth_psk_s_fixed(pk_r, info, psk, psk_id, sk_s, ikm_e)
+    encap_result = @kem.auth_encap_fixed(pk_r, sk_s, ikm_e)
+    {
+      enc: encap_result[:enc],
+      context_s: key_schedule_s(MODES[:auth_psk], encap_result[:shared_secret], info, psk, psk_id)
+    }
+  end
+
+  def export(exporter_secret, exporter_context, len)
+    @hkdf.labeled_expand(exporter_secret, 'sec', exporter_context, len, suite_id)
+  end
+
+  private
+
+  def suite_id
+    'HPKE' + i2osp(@kem.kem_id, 2) + i2osp(@hkdf.kdf_id, 2) + i2osp(@aead_id, 2)
+  end
+
+  DEFAULT_PSK = ''
+  DEFAULT_PSK_ID = ''
+
+  def verify_psk_inputs(mode, psk, psk_id)
+    got_psk = (psk != DEFAULT_PSK)
+    got_psk_id = (psk_id != DEFAULT_PSK_ID)
+
+    raise Exception.new('Inconsistent PSK inputs') if got_psk != got_psk_id
+    raise Exception.new('PSK input provided when not needed') if got_psk && [MODES[:base], MODES[:auth]].include?(mode)
+    raise Exception.new('Missing required PSK input') if !got_psk && [MODES[:psk], MODES[:auth_psk]].include?(mode)
+
+    true
+  end
+
+  def key_schedule(mode, shared_secret, info, psk = '', psk_id = '')
+    verify_psk_inputs(mode, psk, psk_id)
+
+    psk_id_hash = @hkdf.labeled_extract('', 'psk_id_hash', psk_id, suite_id)
+    info_hash = @hkdf.labeled_extract('', 'info_hash', info, suite_id)
+    key_schedule_context = mode.chr + psk_id_hash + info_hash
+
+    secret = @hkdf.labeled_extract(shared_secret, 'secret', psk, suite_id)
+
+    unless @aead_id == CIPHERS[:export_only][:aead_id]
+      key = @hkdf.labeled_expand(secret, 'key', key_schedule_context, @n_k, suite_id)
+      base_nonce = @hkdf.labeled_expand(secret, 'base_nonce', key_schedule_context, @n_n, suite_id)
+    end
+    exporter_secret = @hkdf.labeled_expand(secret, 'exp', key_schedule_context, @hkdf.n_h, suite_id)
+
+    {
+      key: key,
+      base_nonce: base_nonce,
+      sequence_number: 0,
+      exporter_secret: exporter_secret
+    }
+  end
+
+  def key_schedule_s(mode, shared_secret, info, psk = '', psk_id = '')
+    ks = key_schedule(mode, shared_secret, info, psk, psk_id)
+    HPKE::ContextS.new(ks, self)
+  end
+
+  def key_schedule_r(mode, shared_secret, info, psk = '', psk_id = '')
+    ks = key_schedule(mode, shared_secret, info, psk, psk_id)
+    HPKE::ContextR.new(ks, self)
+  end
+end
+
+class HPKE::Context
+  include HPKE::Util
+  attr_reader :key, :base_nonce, :sequence_number, :exporter_secret
+
+  def initialize(initializer_hash, hpke)
+    @hpke = hpke
+    @key = initializer_hash[:key]
+    @base_nonce = initializer_hash[:base_nonce]
+    @sequence_number = initializer_hash[:sequence_number]
+    @exporter_secret = initializer_hash[:exporter_secret]
+  end
+
+  def compute_nonce(seq)
+    seq_bytes = i2osp(seq, @hpke.n_n)
+    xor(@base_nonce, seq_bytes)
+  end
+
+  def increment_seq
+    raise Exception.new('MessageLimitReachedError') if @sequence_number >= (1 << (8 * @hpke.n_n)) - 1
+
+    @sequence_number += 1
+  end
+
+  def export(exporter_context, len)
+    @hpke.export(@exporter_secret, exporter_context, len)
+  end
+end
+
+class HPKE::ContextS < HPKE::Context
+  def seal(aad, pt)
+    raise Exception.new('AEAD is export only') if @hpke.aead_name == :export_only
+
+    ct = cipher_seal(@key, compute_nonce(@sequence_number), aad, pt)
+    increment_seq
+    ct
+  end
+
+  private
+
+  def cipher_seal(key, nonce, aad, pt)
+    cipher = OpenSSL::Cipher.new(@hpke.aead_name)
+    cipher.encrypt
+    cipher.key = key
+    cipher.iv = nonce
+    cipher.auth_data = aad
+    cipher.padding = 0
+    s = cipher.update(pt) << cipher.final
+    s + cipher.auth_tag
+  end
+end
+
+class HPKE::ContextR < HPKE::Context
+  def open(aad, ct)
+    raise Exception.new('AEAD is export only') if @hpke.aead_name == :export_only
+
+    pt = cipher_open(@key, compute_nonce(@sequence_number), aad, ct)
+    # TODO: catch openerror then send out own openerror
+    increment_seq
+    pt
+  end
+
+  private
+
+  def cipher_open(key, nonce, aad, ct)
+    ct_body = ct[0, ct.length - @hpke.n_t]
+    tag = ct[-@hpke.n_t, @hpke.n_t]
+    cipher = OpenSSL::Cipher.new(@hpke.aead_name)
+    cipher.decrypt
+    cipher.key = key
+    cipher.iv = nonce
+    cipher.auth_tag = tag
+    cipher.auth_data = aad
+    cipher.padding = 0
+    cipher.update(ct_body) << cipher.final
+  end
+end

data/sig/hpke.rbs

@@ -0,0 +1,4 @@
+class HPKE
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: hpke
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ryo Kajiwara
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-07-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: openssl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+description: Hybrid Public Key Encryption (HPKE; RFC 9180) on Ruby
+email:
+- sylph01@s01.ninja
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/hpke.rb
+- lib/hpke/dhkem.rb
+- lib/hpke/hkdf.rb
+- lib/hpke/util.rb
+- lib/hpke/version.rb
+- sig/hpke.rbs
+homepage: https://github.com/sylph01/hpke-rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/sylph01/hpke-rb
+  source_code_uri: https://github.com/sylph01/hpke-rb
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Hybrid Public Key Encryption (HPKE; RFC 9180) on Ruby
+test_files: []