melos 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 85db7b48fd128cb7bb205689c66ae391964b16228d21d3cd7b1e2f941d332a31
+  data.tar.gz: d324b915daf2f12f9226f690e9e2a577ab9a34e7235d9088e181e46ffb7d563c
+SHA512:
+  metadata.gz: b0c1e2b24240f32c119d10c09f16ccebe2c3442ec6422df9d85d8669dba4b058d331bc22d8eff36aafda228bd86c0d9d75a8f83d4fce8e2ad9727537ee54593d
+  data.tar.gz: 3fe93f19e872cb70e313714008065026e41ddc0374029a5d0f50b9f843d24f4b394cae6974205098fbfdde36cbdcd979ddd8c4bf73ce721181b1c602877e1a22

data/.rspec

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 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,5 @@
+# Melos
+
+a [Messaging Layer Security Protocol](https://www.rfc-editor.org/rfc/rfc9420.html) implementation in Ruby
+
+(yes, [an mls gem](https://rubygems.org/gems/mls) happened to exist since 2014, so...)

data/Rakefile

@@ -0,0 +1,10 @@
+require 'rake/testtask'
+require "bundler/gem_tasks"
+
+task :default => [:test]
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.test_files = FileList['test/test*.rb']
+  t.verbose = true
+end

data/lib/melos/constants.rb

@@ -0,0 +1,84 @@
+module Melos::Constants
+  module Version
+    MLS10 = 0x01
+  end
+
+  module WireFormat
+    #  17.2. MLS Wire Formats
+    MLS_PUBLIC_MESSAGE = 0x0001
+    MLS_PRIVATE_MESSAGE = 0x0002
+    MLS_WELCOME = 0x0003
+    MLS_GROUP_INFO = 0x0004
+    MLS_KEY_PACKAGE = 0x0005
+  end
+
+  module ExtensionType
+    # 17.3. MLS Extension Types
+    APPLICATION_ID = 0x0001
+    RATCHET_TREE = 0x0002
+    REQUIRED_CAPABILITIES = 0x0003
+    EXTERNAL_PUB = 0x0004
+    EXTERNAL_SENDERS = 0x0005
+  end
+
+  module CredentialType
+    #  17.5. MLS Credential Types
+    BASIC = 0x0001
+    X509 = 0x0002
+  end
+
+  module ContentType
+    APPLICATION = 0x01
+    PROPOSAL = 0x02
+    COMMIT = 0x03
+  end
+
+  module SenderType
+    MEMBER = 0x01
+    EXTERNAL = 0x02
+    NEW_MEMBER_PROPOSAL = 0x03
+    NEW_MEMBER_COMMIT = 0x04
+  end
+
+  module LeafNodeSource
+    KEY_PACKAGE = 0x01
+    UPDATE = 0x02
+    COMMIT = 0x03
+  end
+
+  module ProposalType
+    ADD = 0x0001
+    UPDATE = 0x0002
+    REMOVE = 0x0003
+    PSK = 0x0004
+    REINIT = 0x0005
+    EXTERNAL_INIT = 0x0006
+    GROUP_CONTEXT_EXTENSIONS = 0x0007
+
+    # used for debug purposes
+    NAMES = [
+      nil, 'add', 'update', 'remove', 'psk', 'reinit', 'external_init', 'group_context_extensions'
+    ]
+  end
+
+  module NodeType
+    LEAF = 0x01
+    PARENT = 0x02
+  end
+
+  module PSKType
+    EXTERNAL = 0x01
+    RESUMPTION = 0x02
+  end
+
+  module ResumptionPSKUsage
+    APPLICATION = 0x01
+    REINIT = 0x02
+    BRANCH = 0x03
+  end
+
+  module ProposalOrRefType
+    PROPOSAL = 0x01
+    REFERENCE = 0x02
+  end
+end

data/lib/melos/crypto.rb

@@ -0,0 +1,307 @@
+require 'openssl'
+require 'hpke'
+require_relative 'vec'
+
+class Melos::Crypto
+  class CipherSuite
+    module X25519
+      def self.deserialize_public_encapsulation_key(raw)
+        OpenSSL::PKey.new_raw_public_key('X25519', raw)
+      end
+
+      def self.deserialize_private_encapsulation_key(raw)
+        OpenSSL::PKey.new_raw_private_key('X25519', raw)
+      end
+
+      def self.deserialize_public_signature_key(raw)
+        OpenSSL::PKey.new_raw_public_key('ED25519', raw)
+      end
+
+      def self.deserialize_private_signature_key(raw)
+        OpenSSL::PKey.new_raw_private_key('ED25519', raw)
+      end
+
+      def self.hash_algorithm
+        nil
+      end
+    end
+
+    module X448
+      def self.deserialize_public_encapsulation_key(raw)
+        OpenSSL::PKey.new_raw_public_key('X448', raw)
+      end
+
+      def self.deserialize_private_encapsulation_key(raw)
+        OpenSSL::PKey.new_raw_private_key('X448', raw)
+      end
+
+      def self.deserialize_public_signature_key(raw)
+        OpenSSL::PKey.new_raw_public_key('ED448', raw)
+      end
+
+      def self.deserialize_private_signature_key(raw)
+        OpenSSL::PKey.new_raw_private_key('ED448', raw)
+      end
+
+      def self.hash_algorithm
+        nil
+      end
+    end
+
+    class EC
+      # also would like to depend on HPKE gem...
+      def self.deserialize_private_key(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 self.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
+
+      def self.deserialize_private_encapsulation_key(raw)
+        self.deserialize_private_key(raw)
+      end
+      def self.deserialize_private_signature_key(raw)
+        self.deserialize_private_key(raw)
+      end
+      def self.deserialize_public_encapsulation_key(raw)
+        self.deserialize_public_key(raw)
+      end
+      def self.deserialize_public_signature_key(raw)
+        self.deserialize_public_key(raw)
+      end
+    end
+
+    class P256 < EC
+      def self.curve_name
+        'prime256v1'
+      end
+
+      def self.hash_algorithm
+        'sha256'
+      end
+    end
+
+    class P384 < EC
+      def self.curve_name
+        'secp384r1'
+      end
+
+      def self.hash_algorithm
+        'sha384'
+      end
+    end
+
+    class P521 < EC
+      def self.curve_name
+        'secp521r1'
+      end
+
+      def self.hash_algorithm
+        'sha512'
+      end
+    end
+
+    attr_accessor :level, :digest, :hpke, :kdf, :pkey
+    def initialize(suite_id)
+      case suite_id
+      when 1 # MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519
+        @level = 128
+        @digest = OpenSSL::Digest.new('sha256')
+        @hpke = HPKE.new(:x25519, :sha256, :sha256, :aes_128_gcm)
+        @kdf = @hpke.hkdf
+        @pkey = Melos::Crypto::CipherSuite::X25519
+      when 2 # MLS_128_DHKEMP256_AES128GCM_SHA256_P256
+        @level = 128
+        @digest = OpenSSL::Digest.new('sha256')
+        @hpke = HPKE.new(:p_256, :sha256, :sha256, :aes_128_gcm)
+        @kdf = @hpke.hkdf
+        @pkey = Melos::Crypto::CipherSuite::P256
+      when 3 # MLS_128_DHKEMX25519_CHACHA20POLY1305_SHA256_Ed25519
+        @level = 128
+        @digest = OpenSSL::Digest.new('sha256')
+        @hpke = HPKE.new(:x25519, :sha256, :sha256, :chacha20_poly1305)
+        @kdf = @hpke.hkdf
+        @pkey = Melos::Crypto::CipherSuite::X25519
+      when 4 # MLS_256_DHKEMX448_AES256GCM_SHA512_Ed448
+        @level = 256
+        @digest = OpenSSL::Digest.new('sha512')
+        @hpke = HPKE.new(:x448, :sha512, :sha512, :aes_256_gcm)
+        @kdf = @hpke.hkdf
+        @pkey = Melos::Crypto::CipherSuite::X448
+      when 5 # MLS_256_DHKEMP521_AES256GCM_SHA512_P521
+        @level = 256
+        @digest = OpenSSL::Digest.new('sha512')
+        @hpke = HPKE.new(:p_521, :sha512, :sha512, :aes_256_gcm)
+        @kdf = @hpke.hkdf
+        @pkey = Melos::Crypto::CipherSuite::P521
+      when 6 # MLS_256_DHKEMX448_CHACHA20POLY1305_SHA512_Ed448
+        @level = 256
+        @digest = OpenSSL::Digest.new('sha512')
+        @hpke = HPKE.new(:x448, :sha512, :sha512, :chacha20_poly1305)
+        @kdf = @hpke.hkdf
+        @pkey = Melos::Crypto::CipherSuite::X448
+      when 7 # MLS_256_DHKEMP384_AES256GCM_SHA384_P384
+        @level = 256
+        @digest = OpenSSL::Digest.new('sha384')
+        @hpke = HPKE.new(:p_384, :sha384, :sha384, :aes_256_gcm)
+        @kdf = @hpke.hkdf
+        @pkey = Melos::Crypto::CipherSuite::P384
+      end
+    end
+  end
+
+  module Util
+    def self.zero_vector(length)
+      ([0] * length).pack('C*')
+    end
+  end
+
+  def self.ref_hash(suite, label, value)
+    ref_hash_input = Melos::Vec.from_string(label) + Melos::Vec.from_string(value)
+    suite.digest.digest(ref_hash_input)
+  end
+
+  def self.make_keypackage_ref(suite, value)
+    self.ref_hash(suite, "MLS 1.0 KeyPackage Reference", value)
+  end
+
+  def self.make_proposal_ref(suite, value)
+    self.ref_hash(suite, "MLS 1.0 Proposal Reference", value)
+  end
+
+  def self.kdf_extract(suite, salt, ikm)
+    suite.kdf.extract(salt, ikm)
+  end
+
+  def self.expand_with_label(suite, secret, label, context, length)
+    kdf_label = [length].pack('S>') + Melos::Vec.from_string("MLS 1.0 " + label) + Melos::Vec.from_string(context)
+    suite.kdf.expand(secret, kdf_label, length)
+  end
+
+  def self.derive_secret(suite, secret, label)
+    expand_with_label(suite, secret, label, "", suite.kdf.n_h)
+  end
+
+  def self.derive_tree_secret(suite, secret, label, generation, length)
+    generation_in_uint32 = [generation].pack('L>')
+    expand_with_label(suite, secret, label, generation_in_uint32, length)
+  end
+
+  def self.derive_key_pair(suite, secret)
+    pkey = suite.hpke.kem.derive_key_pair(secret)
+    if suite.pkey.equal?(Melos::Crypto::CipherSuite::X25519) || suite.pkey.equal?(Melos::Crypto::CipherSuite::X448)
+      # is an Edwards curve
+      [pkey.raw_private_key, pkey.raw_public_key]
+    else
+      # is an EC
+      [pkey.private_key.to_s(2), pkey.public_key.to_bn.to_s(2)]
+    end
+  end
+
+  def self.seal_base(suite, pkr, info, aad, pt)
+    context = suite.hpke.setup_base_s(pkr, info)
+    enc = context[:enc]
+    ctx = context[:context_s]
+    ct = ctx.seal(aad, pt)
+    [enc, ct]
+  end
+
+  def self.open_base(suite, enc, skr, info, aad, ct)
+    ctx = suite.hpke.setup_base_r(enc, skr, info)
+    ctx.open(aad, ct)
+  end
+
+  def self.encrypt_with_label(suite, public_key, label, context, plaintext)
+    encrypt_context = Melos::Vec.from_string("MLS 1.0 " + label) + Melos::Vec.from_string(context)
+    pkey = suite.pkey.deserialize_public_encapsulation_key(public_key)
+    seal_base(suite, pkey, encrypt_context, "", plaintext)
+  end
+
+  def self.decrypt_with_label(suite, private_key, label, context, kem_output, ciphertext)
+    encrypt_context = Melos::Vec.from_string("MLS 1.0 " + label) + Melos::Vec.from_string(context)
+    pkey = suite.pkey.deserialize_private_encapsulation_key(private_key)
+    open_base(suite, kem_output, pkey, encrypt_context, "", ciphertext)
+  end
+
+  def self.sign_with_label(suite, signature_key, label, content)
+    skey = suite.pkey.deserialize_private_signature_key(signature_key)
+    sign_content = Melos::Vec.from_string("MLS 1.0 " + label) + Melos::Vec.from_string(content)
+    skey.sign(suite.pkey.hash_algorithm, sign_content)
+  end
+
+  def self.verify_with_label(suite, verification_key, label, content, signature_value)
+    vkey = suite.pkey.deserialize_public_signature_key(verification_key)
+    sign_content = Melos::Vec.from_string("MLS 1.0 " + label) + Melos::Vec.from_string(content)
+    vkey.verify(suite.pkey.hash_algorithm, signature_value, sign_content)
+  end
+
+  def self.mac(suite, key, data)
+    OpenSSL::HMAC.digest(suite.digest, key, data)
+  end
+
+  def self.hash(suite, data)
+    suite.digest.digest(data)
+  end
+
+  def self.aead_encrypt(suite, key, nonce, aad, plaintext)
+    suite.hpke.aead_encrypt(key, nonce, aad, plaintext)
+  end
+
+  def self.aead_decrypt(suite, key, nonce, aad, ciphertext)
+    suite.hpke.aead_decrypt(key, nonce, aad, ciphertext)
+  end
+
+  def self.sender_data_key(suite, sender_data_secret, ciphertext)
+    ciphertext_sample = ciphertext[0..(suite.kdf.n_h - 1)]
+    expand_with_label(suite, sender_data_secret, "key", ciphertext_sample, suite.hpke.n_k)
+  end
+
+  def self.sender_data_nonce(suite, sender_data_secret, ciphertext)
+    ciphertext_sample = ciphertext[0..(suite.kdf.n_h - 1)]
+    expand_with_label(suite, sender_data_secret, "nonce", ciphertext_sample, suite.hpke.n_n)
+  end
+
+  def self.encapsulation_key_pair_corresponds?(suite, private_key, public_key)
+    private_pkey = suite.pkey.deserialize_private_encapsulation_key(private_key)
+    public_pkey  = suite.pkey.deserialize_public_encapsulation_key(public_key)
+    if suite.pkey.equal?(Melos::Crypto::CipherSuite::X25519) || suite.pkey.equal?(Melos::Crypto::CipherSuite::X448)
+      # is an Edwards curve; check equality of the raw public key
+      private_pkey.raw_public_key == public_pkey.raw_public_key
+    else
+      # is an EC; check equality of the public key Point
+      private_pkey.public_key == public_pkey.public_key
+    end
+  end
+
+  def self.signature_key_pair_corresponds?(suite, private_key, public_key)
+    private_pkey = suite.pkey.deserialize_private_signature_key(private_key)
+    public_pkey  = suite.pkey.deserialize_public_signature_key(public_key)
+    if suite.pkey.equal?(Melos::Crypto::CipherSuite::X25519) || suite.pkey.equal?(Melos::Crypto::CipherSuite::X448)
+      # is an Edwards curve; check equality of the raw public key
+      private_pkey.raw_public_key == public_pkey.raw_public_key
+    else
+      # is an EC; check equality of the public key Point
+      private_pkey.public_key == public_pkey.public_key
+    end
+  end
+
+  def self.parent_hash(suite, encryption_key, ph_of_parent, sibling_hash)
+    parent_hash_input = Melos::Vec.from_string(encryption_key) + Melos::Vec.from_string(ph_of_parent) + Melos::Vec.from_string(sibling_hash)
+    Melos::Crypto.hash(suite, parent_hash_input)
+  end
+end

data/lib/melos/key_schedule.rb

@@ -0,0 +1,62 @@
+require_relative 'crypto'
+
+module Melos::KeySchedule
+  extend self
+
+  def joiner_secret(suite, init_secret, commit_secret, group_context)
+    Melos::Crypto.expand_with_label(
+      suite,
+      Melos::Crypto.kdf_extract(suite, init_secret, commit_secret),
+      "joiner",
+      group_context.raw,
+      suite.kdf.n_h
+    )
+  end
+
+  def welcome_secret(suite, joiner_secret, psk_secret)
+    Melos::Crypto.derive_secret(
+      suite,
+      Melos::Crypto.kdf_extract(suite, joiner_secret, psk_secret), # sometimes written as `member_secret`
+      "welcome"
+    )
+  end
+
+  def welcome_key_and_nonce(suite, joiner_secret, psk_secret)
+    ws = welcome_secret(suite, joiner_secret, psk_secret)
+    [
+      Melos::Crypto.expand_with_label(suite, ws, "key",   "", suite.hpke.n_k),
+      Melos::Crypto.expand_with_label(suite, ws, "nonce", "", suite.hpke.n_n)
+    ]
+  end
+
+  def epoch_secret(suite, joiner_secret, psk_secret, group_context)
+    Melos::Crypto.expand_with_label(
+      suite,
+      Melos::Crypto.kdf_extract(suite, joiner_secret, psk_secret),
+      "epoch",
+      group_context.raw,
+      suite.kdf.n_h
+    )
+  end
+
+  # epoch-derived secrets, from Table 4 in Section 8
+  # will be defined as something like:
+  # Melos::KeySchedule.sender_data_secret(suite, epoch_secret)
+  [
+    ['sender data', 'sender_data_secret'],
+    ['encryption',  'encryption_secret'],
+    ['exporter',    'exporter_secret'],
+    ['external',    'external_secret'],
+    ['confirm',     'confirmation_key'],
+    ['membership',  'membership_key'],
+    ['resumption',  'resumption_psk'],
+    ['authentication', 'epoch_authenticator'],
+    ['init', 'init_secret'] # this is not part of the table but is defined in the same way
+  ].each do |tuple|
+    label = tuple[0]
+    name  = tuple[1]
+    define_method(name.to_sym, ->(suite, epoch_secret){
+      Melos::Crypto.derive_secret(suite, epoch_secret, label)
+    })
+  end
+end

data/lib/melos/psk.rb

@@ -0,0 +1,35 @@
+require_relative 'crypto'
+
+module Melos::PSK
+  extend self
+
+  # input: array of [(raw PSK ID), (PSK value)]
+  def psk_secret(suite, psk_array)
+    secret = Melos::Crypto::Util.zero_vector(suite.kdf.n_h)
+
+    psk_array.each_with_index do |tuple, idx|
+      psk_id = Melos::Struct::PreSharedKeyID.new(tuple[0])
+      psk_label = Melos::Struct::PSKLabel.create(
+        id: psk_id,
+        index: idx,
+        count: psk_array.count
+      )
+
+      extracted = Melos::Crypto.kdf_extract(
+        suite,
+        Melos::Crypto::Util.zero_vector(suite.kdf.n_h),
+        tuple[1]
+      )
+      input = Melos::Crypto.expand_with_label(
+        suite,
+        extracted,
+        "derived psk",
+        psk_label.raw,
+        suite.kdf.n_h
+      )
+      secret = Melos::Crypto.kdf_extract(suite, input, secret)
+    end
+
+    return secret
+  end
+end

data/lib/melos/secret_tree.rb

@@ -0,0 +1,109 @@
+require_relative 'tree'
+require_relative 'crypto'
+
+module Melos::SecretTree
+  def self.create(suite, n_leaves, encryption_secret)
+    st = Melos::Tree.empty_tree(n_leaves)
+    populate_tree(suite, st, encryption_secret)
+    st
+  end
+
+  def self.populate_tree(suite, tree, root_secret)
+    populate_tree_impl(suite, tree, tree.root, root_secret)
+  end
+
+  def self.populate_tree_impl(suite, tree, index, secret)
+    tree.array[index] = {
+      'handshake_ratchet_secret' => Melos::Crypto.expand_with_label(suite, secret, "handshake",   "", suite.kdf.n_h),
+      'application_ratchet_secret' => Melos::Crypto.expand_with_label(suite, secret, "application", "", suite.kdf.n_h),
+      'next_handshake_ratchet_secret_generation' => 0,
+      'next_application_ratchet_secret_generation' => 0
+    }
+    unless Melos::Tree.leaf?(index)
+      left_secret  = Melos::Crypto.expand_with_label(suite, secret, "tree", "left", suite.kdf.n_h)
+      right_secret = Melos::Crypto.expand_with_label(suite, secret, "tree", "right", suite.kdf.n_h)
+      populate_tree_impl(suite, tree, Melos::Tree.left(index), left_secret)
+      populate_tree_impl(suite, tree, Melos::Tree.right(index), right_secret)
+    end
+  end
+
+  def self.ratchet_until_and_get(suite, content_type, tree, leaf_index, generation)
+    # TODO: clear the value on tree when getting
+    case content_type
+    when 0x02, 0x03
+      ratchet_handshake_until(suite, tree, leaf_index, generation)
+      [
+        tree.leaf_at(leaf_index)['handshake_key'],
+        tree.leaf_at(leaf_index)['handshake_nonce'],
+        generation
+      ]
+    else
+      ratchet_application_until(suite, tree, leaf_index, generation)
+      [
+        tree.leaf_at(leaf_index)['application_key'],
+        tree.leaf_at(leaf_index)['application_nonce'],
+        generation
+      ]
+    end
+  end
+
+  def self.ratchet_and_get(suite, content_type, tree, leaf_index)
+    # TODO: clear the value on tree when getting
+    case content_type
+    when 0x02, 0x03
+      ratchet_handshake(suite, tree, leaf_index)
+      [
+        tree.leaf_at(leaf_index)['handshake_key'],
+        tree.leaf_at(leaf_index)['handshake_nonce'],
+        tree.leaf_at(leaf_index)['next_handshake_ratchet_secret_generation'] - 1, # returns current generation
+      ]
+    else
+      ratchet_application(suite, tree, leaf_index)
+      [
+        tree.leaf_at(leaf_index)['application_key'],
+        tree.leaf_at(leaf_index)['application_nonce'],
+        tree.leaf_at(leaf_index)['next_application_ratchet_secret_generation'] - 1, # returns current generation
+      ]
+    end
+  end
+
+  def self.ratchet_application_until(suite, tree, leaf_index, generation)
+    while (tree.leaf_at(leaf_index)['next_application_ratchet_secret_generation'] <= generation)
+      ratchet_application(suite, tree, leaf_index)
+    end
+  end
+
+  def self.ratchet_handshake_until(suite, tree, leaf_index, generation)
+    raise ArgumentError.new('cannot generate past generation') if generation < tree.leaf_at(leaf_index)['next_handshake_ratchet_secret_generation'] - 1
+    # if current generation, do nothing
+    while (tree.leaf_at(leaf_index)['next_handshake_ratchet_secret_generation'] <= generation)
+      ratchet_handshake(suite, tree, leaf_index)
+    end
+  end
+
+  def self.ratchet_application(suite, tree, leaf_index)
+    node_index = leaf_index * 2
+    generation = tree.array[node_index]['next_application_ratchet_secret_generation']
+    application_ratchet_secret = tree.array[node_index]['application_ratchet_secret']
+    application_nonce = Melos::Crypto.derive_tree_secret(suite, application_ratchet_secret, "nonce", generation, suite.hpke.n_n)
+    application_key   = Melos::Crypto.derive_tree_secret(suite, application_ratchet_secret, "key",   generation, suite.hpke.n_k)
+    next_application_ratchet_secret = Melos::Crypto.derive_tree_secret(suite, application_ratchet_secret, "secret", generation, suite.kdf.n_h)
+    tree.array[node_index]['next_application_ratchet_secret_generation'] = generation + 1
+    tree.array[node_index]['application_ratchet_secret'] = next_application_ratchet_secret
+    tree.array[node_index]['application_nonce'] = application_nonce
+    tree.array[node_index]['application_key']   = application_key
+  end
+
+  def self.ratchet_handshake(suite, tree, leaf_index)
+    node_index = leaf_index * 2
+    generation = tree.array[node_index]['next_handshake_ratchet_secret_generation']
+    handshake_ratchet_secret = tree.array[node_index]['handshake_ratchet_secret']
+    handshake_nonce = Melos::Crypto.derive_tree_secret(suite, handshake_ratchet_secret, "nonce", generation, suite.hpke.n_n)
+    handshake_key   = Melos::Crypto.derive_tree_secret(suite, handshake_ratchet_secret, "key",   generation, suite.hpke.n_k)
+    next_handshake_ratchet_secret = Melos::Crypto.derive_tree_secret(suite, handshake_ratchet_secret, "secret", generation, suite.kdf.n_h)
+    tree.array[node_index]['next_handshake_ratchet_secret_generation'] = generation + 1
+    tree.array[node_index]['handshake_ratchet_secret'] = next_handshake_ratchet_secret
+    tree.array[node_index]['handshake_nonce'] = handshake_nonce
+    tree.array[node_index]['handshake_key']   = handshake_key
+  end
+end