hpke 0.3.1 → 1.0.0.pre.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9172f40ce30fde1a8dc74e45379371d3dcb85ffc28502fe3ff3c3e845b169a94
-  data.tar.gz: 1caa20117210b78f224146272cad6b63c1a6abdbcf1315752063d44f20f7cdd8
+  metadata.gz: af90c4d6df46848b41461a37d6026d06984109712489219d17d27fddf4abf1f5
+  data.tar.gz: eaac6a6353c644133d964131d4f2ed3d09e901e9b7c12863522252c9c80ad190
 SHA512:
-  metadata.gz: a4bfef8659dbed463b0c4f6eead0881f20fd74bc05519ab73b1f8e4661a0bd054eb4a1224bbf1b1a91c4b2572b60d131e0861a14722cf39b20e259b57982ca62
-  data.tar.gz: '00398459076f9dbccbf85f530ae071835456c11b6de178f0fe7347f5ca9584cdc6cde4aadee28d9dbfb28b99d745d3dc9d5b2253485cd3237c17ec3831002aa9'
+  metadata.gz: 2a16070a91990a059c8bdcde394b7cd8b2644a3dcc6675833dfda59a7298380d37a24838026f65f25a3ac7cbb25012ec2d33986da58f8e564fd2b2c242113a0d
+  data.tar.gz: 279298ae5d3dd40645f9bc5254b9c88d961493fdf5c2f64280b69858a7202d21e52a3e63c0e68cf7611edea3f625bd1e2be9453f1cbb7a015df50104d8001b06

data/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: .
   specs:
-    hpke (0.1.0)
-      openssl (~> 3.0.0)
+    hpke (1.0.0.pre.rc1)
+      openssl (~> 3.3.0, >= 3.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     diff-lcs (1.5.0)
-    openssl (3.0.2)
+    openssl (3.3.0)
     rake (13.0.6)
     rspec (3.12.0)
       rspec-core (~> 3.12.0)

data/README.md

@@ -6,11 +6,26 @@ Hybrid Public Key Encryption (HPKE; [RFC 9180](https://datatracker.ietf.org/doc/
 
 ## Note
 
-This is still in very early development, so:
+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.
 
-- 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.
+### Breaking Changes in Version 1.0.0(-rc1)
+
+Previously, the instantiation of HPKE instance took four arguments, the curve for DHKEM, the hash function for DHKEM's HKDF, the hash function for the HKDF of HPKE, and the AEAD algorithm:
+
+```ruby
+hpke = HPKE.new(:x25519, :sha256, :sha256, :aes_128_gcm)
+```
+
+From 1.0.0, the instantiation of the HPKE instance will be done by passing algorithm identifiers (specified in the RFC, in Section 7.1, 7.2, and 7.3):
+
+```ruby
+hpke = HPKE.new(HPKE::DHKEM_X25519_HKDF_SHA256, HPKE::HKDF_SHA256, HPKE::AES_128_GCM)
+
+# also equivalent to:
+hpke = HPKE.new(0x0020, 0x0001, 0x0001)
+```
+
+The name of constants (and its values) are listed in the next section.
 
 ## Supported Features
 
@@ -22,20 +37,20 @@ Supports all modes, KEMs, AEAD functions in RFC 9180.
     - 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)
+    - DHKEM(P-256, HKDF-SHA256) `DHKEM_P256_HKDF_SHA256` (= `0x0010`)
+    - DHKEM(P-384, HKDF-SHA384) `DHKEM_P384_HKDF_SHA384` (= `0x0011`)
+    - DHKEM(P-521, HKDF-SHA512) `DHKEM_P521_HKDF_SHA512` (= `0x0012`)
+    - DHKEM(X25519, HKDF-SHA256) `DHKEM_X25519_HKDF_SHA256` (= `0x0020`)
+    - DHKEM(X448, HKDF-SHA512) `DHKEM_X448_HKDF_SHA512` (= `0x0021`)
 - Key Derivation Functions (KDFs)
-    - HKDF-SHA256
-    - HKDF-SHA384
-    - HKDF-SHA512
+    - HKDF-SHA256 `HKDF_SHA256` (= `0x0001`)
+    - HKDF-SHA384 `HKDF_SHA384` (= `0x0002`)
+    - HKDF-SHA512 `HKDF_SHA512` (= `0x0003`)
 - AEAD Functions
-    - AES-128-GCM
-    - AES-256-GCM
-    - ChaCha20-Poly1305
-    - Export Only
+    - AES-128-GCM `AES_128_GCM` (= `0x0001`)
+    - AES-256-GCM `AES_256_GCM` (= `0x0002`)
+    - ChaCha20-Poly1305 `CHACHA20_POLY1305` (= `0x0003`)
+    - Export Only `EXPORT_ONLY`(= `0xffff`)
 
 ## Supported Environments
 
@@ -65,8 +80,8 @@ If bundler is not being used to manage dependencies, install the gem by executin
 # 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)
+hpke_s = HPKE.new(HPKE::DHKEM_X25519_HKDF_SHA256, HPKE::HKDF_SHA256, HPKE::AES_128_GCM)
+hpke_r = HPKE.new(HPKE::DHKEM_X25519_HKDF_SHA256, HPKE::HKDF_SHA256, HPKE::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
@@ -99,14 +114,6 @@ ciphertext = context_s.seal('authentication_associated_data', 'plaintext')
 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`, `:export_only`
-
 ## 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.

data/lib/hpke/dhkem.rb

@@ -6,8 +6,11 @@ require_relative 'util'
 class HPKE::DHKEM
   include HPKE::Util
 
-  def initialize(hash_name)
-    @hkdf = HPKE::HKDF.new(hash_name)
+  def initialize(kdf_id)
+    # Currently all KDFs are HKDF so this works fine,
+    # but when other KDFs are added, this should be fixed
+    @hkdf = HPKE::HKDF.new(kdf_id)
+    raise Exception.new('KDF not compatible with DHKEM curve') unless @hkdf.n_h == self.n_secret
   end
 
   def encap(pk_r)

data/lib/hpke/hkdf.rb

@@ -6,32 +6,22 @@ class HPKE::HKDF
 
   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]
+  def initialize(kdf_id)
+    case kdf_id
+    when HPKE::HKDF_SHA256
+      @digest = OpenSSL::Digest.new('SHA256')
+    when HPKE::HKDF_SHA384
+      @digest = OpenSSL::Digest.new('SHA384')
+    when HPKE::HKDF_SHA512
+      @digest = OpenSSL::Digest.new('SHA512')
     else
       raise Exception.new('Unknown hash algorithm')
     end
+    @kdf_id = kdf_id
   end
 
   def hmac(key, data)
@@ -62,39 +52,3 @@ class HPKE::HKDF
     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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class HPKE
-  VERSION = "0.3.1"
+  VERSION = "1.0.0-rc1"
 end

data/lib/hpke.rb

@@ -9,73 +9,90 @@ 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
-  }
+  attr_reader :kem, :hkdf, :aead_id, :aead_name, :n_k, :n_n, :n_t
+
+  # Algorithm Identifiers
+  # DHKEM
+  # RFC 9180, Section 7.1 Table 2
+  DHKEM_P256_HKDF_SHA256 = 0x0010
+  DHKEM_P384_HKDF_SHA384 = 0x0011
+  DHKEM_P521_HKDF_SHA512 = 0x0012
+  DHKEM_X25519_HKDF_SHA256 = 0x0020
+  DHKEM_X448_HKDF_SHA512 = 0x0021
+  AVAILABLE_KEM = [
+    DHKEM_P256_HKDF_SHA256, DHKEM_P384_HKDF_SHA384, DHKEM_P521_HKDF_SHA512, DHKEM_X25519_HKDF_SHA256, DHKEM_X448_HKDF_SHA512
+  ]
+
+  # HKDF
+  # RFC 9180, Section 7.2, Table 3
+  HKDF_SHA256 = 0x0001
+  HKDF_SHA384 = 0x0002
+  HKDF_SHA512 = 0x0003
+  AVAILABLE_KDF = [
+    HKDF_SHA256, HKDF_SHA384, HKDF_SHA512
+  ]
+
+  # AEAD
+  # RFC 9180, Section 7.3, Table 5
+  AES_128_GCM = 0x0001
+  AES_256_GCM = 0x0002
+  CHACHA20_POLY1305 = 0x0003
+  EXPORT_ONLY = 0xffff
+  AVAILABLE_AEAD = [
+    AES_128_GCM, AES_256_GCM, CHACHA20_POLY1305, EXPORT_ONLY
+  ]
   CIPHERS = {
-    aes_128_gcm: {
+    AES_128_GCM => {
       name: 'aes-128-gcm',
-      aead_id: 0x0001,
       n_k: 16,
       n_n: 12,
       n_t: 16
     },
-    aes_256_gcm: {
+    AES_256_GCM => {
       name: 'aes-256-gcm',
-      aead_id: 0x0002,
       n_k: 32,
       n_n: 12,
       n_t: 16
     },
-    chacha20_poly1305: {
+    CHACHA20_POLY1305 => {
       name: 'chacha20-poly1305',
-      aead_id: 0x0003,
       n_k: 32,
       n_n: 12,
       n_t: 16
     },
-    export_only: {
-      aead_id: 0xffff
+    EXPORT_ONLY => {
     }
   }
-  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
+
+  MODES = {
+    base: 0x00,
+    psk: 0x01,
+    auth: 0x02,
+    auth_psk: 0x03
   }
 
-  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]
+  def initialize(kem_id, kdf_id, aead_id)
+    raise Exception.new('Unsupported AEAD') unless AVAILABLE_AEAD.include?(aead_id)
+
+    @kem = case kem_id
+            when DHKEM_P256_HKDF_SHA256 then DHKEM::EC::P_256.new(HKDF_SHA256)
+            when DHKEM_P384_HKDF_SHA384 then DHKEM::EC::P_384.new(HKDF_SHA384)
+            when DHKEM_P521_HKDF_SHA512 then DHKEM::EC::P_521.new(HKDF_SHA512)
+            when DHKEM_X25519_HKDF_SHA256 then DHKEM::X25519.new(HKDF_SHA256)
+            when DHKEM_X448_HKDF_SHA512 then DHKEM::X448.new(HKDF_SHA512)
+            else raise Exception.new('Unsupported KEM')
+            end
+    @hkdf = case kdf_id
+             when HKDF_SHA256 then HKDF.new(HKDF_SHA256)
+             when HKDF_SHA384 then HKDF.new(HKDF_SHA384)
+             when HKDF_SHA512 then HKDF.new(HKDF_SHA512)
+             else raise Exception.new('Unsupported KDF')
+             end
+    @aead_id = aead_id
+    @aead_name = CIPHERS[aead_id][:name]
+    @n_k = CIPHERS[aead_id][:n_k]
+    @n_n = CIPHERS[aead_id][:n_n]
+    @n_t = CIPHERS[aead_id][:n_t]
   end
 
   # public facing APIs
@@ -221,7 +238,7 @@ class HPKE
 
     secret = @hkdf.labeled_extract(shared_secret, 'secret', psk, suite_id)
 
-    unless @aead_id == CIPHERS[:export_only][:aead_id]
+    unless @aead_id == EXPORT_ONLY
       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
@@ -276,7 +293,7 @@ end
 
 class HPKE::ContextS < HPKE::Context
   def seal(aad, pt)
-    raise Exception.new('AEAD is export only') if @hpke.aead_name == :export_only
+    raise Exception.new('AEAD is export only') if @hpke.aead_id == HPKE::EXPORT_ONLY
 
     ct = @hpke.aead_encrypt(@key, compute_nonce(@sequence_number), aad, pt)
     increment_seq
@@ -286,7 +303,7 @@ end
 
 class HPKE::ContextR < HPKE::Context
   def open(aad, ct)
-    raise Exception.new('AEAD is export only') if @hpke.aead_name == :export_only
+    raise Exception.new('AEAD is export only') if @hpke.aead_id == HPKE::EXPORT_ONLY
 
     pt = @hpke.aead_decrypt(@key, compute_nonce(@sequence_number), aad, ct)
     # TODO: catch openerror then send out own openerror

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: hpke
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 1.0.0.pre.rc1
 platform: ruby
 authors:
 - Ryo Kajiwara
 bindir: exe
 cert_chain: []
-date: 2025-04-04 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: openssl
@@ -69,7 +69,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.5
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Hybrid Public Key Encryption (HPKE; RFC 9180) on Ruby
 test_files: []