x25519 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 25356788bb752f943f14d47eb09477c80e8831f3
-  data.tar.gz: c90ad445482d6d376bb957187ba1c01a4ade1c7d
+  metadata.gz: 4e14a38927066f9bf0bb89efc17aa433b42d3fbd
+  data.tar.gz: 7ccda465a96b34ada8f593b1461861a72f2ec253
 SHA512:
-  metadata.gz: e16c1bfd49e7dd844676159714e6145d357259002800a1033b7993c7ac4049e238dba7c5b8aa1bdff12dced90dfc5a5e70caaf054a3f401eed6efdcd9da7d12f
-  data.tar.gz: 173e2fecb31f6b0bc09287fe9d7b7bba563e2cac1ca8b9877290b86241cd7cbbb0b4c8d20f212c2dfd777327a50ef6ac403966f9babac4ced0c38fddc4bfba60
+  metadata.gz: 0540a115042091e9bd19b45db8b44fa3e0453720ed5d03cb0379e217ebe7a75b784df3510118820fe4e5277de369dfb3c095b1bb4f57975aa2876dff3445be39
+  data.tar.gz: 3b230f900fac4f7b183b62a7e53c2385b9e7581fc39ded633a8f0e766f68a5f06805421b0c16f7cb38cad14ed430659a4eed845f8cee02ecfab6aa0ef2e0f78e

data/CHANGES.md

@@ -1,3 +1,13 @@
+# [1.0.0] (2017-12-12)
+
+[1.0.0]: https://github.com/cryptosphere/x25519/compare/v0.2.0...v1.0.0
+
+* [#8](https://github.com/cryptosphere/x25519/pull/8)
+  Add self-test
+
+* [#7](https://github.com/cryptosphere/x25519/pull/7)
+  Factor providers into the `X25519::Provider` namespace
+
 # [0.2.0] (2017-12-12)
 
 [0.2.0]: https://github.com/cryptosphere/x25519/compare/v0.1.0...v0.2.0

data/README.md

@@ -1,9 +1,11 @@
-# x25519.rb [![Latest Version][gem-shield]][gem-link] [![Build Status][build-image]][build-link] [![License: LGPL v3][license-image]][license-link]
+# x25519.rb [![Latest Version][gem-shield]][gem-link] [![Build Status][build-image]][build-link] [![Yard Docs][docs-image]][docs-link] [![License: LGPL v3][license-image]][license-link]
 
 [gem-shield]: https://badge.fury.io/rb/x25519.svg
 [gem-link]: https://rubygems.org/gems/x25519
 [build-image]: https://travis-ci.org/cryptosphere/x25519.svg?branch=master
 [build-link]: https://travis-ci.org/cryptosphere/x25519
+[docs-image]: https://img.shields.io/badge/yard-docs-blue.svg
+[docs-link]: http://www.rubydoc.info/gems/x25519
 [license-image]: https://img.shields.io/badge/License-LGPL%20v3-blue.svg
 [license-link]: https://www.gnu.org/licenses/lgpl-3.0
 

data/ext/x25519_precomputed/x25519_precomputed.c

@@ -7,25 +7,27 @@ the X25519 Diffie-Hellman algorithm
 #include "x25519_precomputed.h"
 
 static VALUE mX25519 = Qnil;
-static VALUE mX25519_Precomputed = Qnil;
+static VALUE mX25519_Provider = Qnil;
+static VALUE mX25519_Provider_Precomputed = Qnil;
 
-static VALUE mX25519_Scalar_multiply(VALUE self, VALUE scalar, VALUE montgomery_u);
-static VALUE mX25519_Scalar_multiply_base(VALUE self, VALUE scalar);
+static VALUE mX25519_Provider_Precomputed_scalarmult(VALUE self, VALUE scalar, VALUE montgomery_u);
+static VALUE mX25519_Provider_Precomputed_scalarmult_base(VALUE self, VALUE scalar);
 static VALUE mX25519_is_available(VALUE self);
 
 /* Initialize the x25519_precomputed C extension */
 void Init_x25519_precomputed()
 {
     mX25519 = rb_define_module("X25519");
-    mX25519_Precomputed = rb_define_module_under(mX25519, "Precomputed");
+    mX25519_Provider = rb_define_module_under(mX25519, "Provider");
+    mX25519_Provider_Precomputed = rb_define_module_under(mX25519_Provider, "Precomputed");
 
-    rb_define_singleton_method(mX25519_Precomputed, "multiply", mX25519_Scalar_multiply, 2);
-    rb_define_singleton_method(mX25519_Precomputed, "multiply_base", mX25519_Scalar_multiply_base, 1);
-    rb_define_singleton_method(mX25519_Precomputed, "available?", mX25519_is_available, 0);
+    rb_define_singleton_method(mX25519_Provider_Precomputed, "scalarmult", mX25519_Provider_Precomputed_scalarmult, 2);
+    rb_define_singleton_method(mX25519_Provider_Precomputed, "scalarmult_base", mX25519_Provider_Precomputed_scalarmult_base, 1);
+    rb_define_singleton_method(mX25519_Provider_Precomputed, "available?", mX25519_is_available, 0);
 }
 
 /* Variable-base scalar multiplication */
-static VALUE mX25519_Scalar_multiply(VALUE self, VALUE scalar, VALUE montgomery_u)
+static VALUE mX25519_Provider_Precomputed_scalarmult(VALUE self, VALUE scalar, VALUE montgomery_u)
 {
     /* X25519_KEY ensures inputs are aligned at 32-bytes */
     X25519_KEY raw_scalar, raw_montgomery_u, product;
@@ -58,7 +60,7 @@ static VALUE mX25519_Scalar_multiply(VALUE self, VALUE scalar, VALUE montgomery_
 }
 
 /* Fixed-base scalar multiplication */
-static VALUE mX25519_Scalar_multiply_base(VALUE self, VALUE scalar)
+static VALUE mX25519_Provider_Precomputed_scalarmult_base(VALUE self, VALUE scalar)
 {
     /* X25519_KEY ensures inputs are aligned at 32-bytes */
     X25519_KEY raw_scalar, product;

data/ext/x25519_ref10/x25519_ref10.c

@@ -7,23 +7,25 @@ X25519 Diffie-Hellman algorithm
 #include "x25519_ref10.h"
 
 static VALUE mX25519 = Qnil;
-static VALUE mX25519_Ref10 = Qnil;
+static VALUE mX25519_Provider = Qnil;
+static VALUE mX25519_Provider_Ref10 = Qnil;
 
-static VALUE mX25519_Scalar_multiply(VALUE self, VALUE scalar, VALUE montgomery_u);
-static VALUE mX25519_Scalar_multiply_base(VALUE self, VALUE scalar);
+static VALUE mX25519_Provider_Ref10_scalarmult(VALUE self, VALUE scalar, VALUE montgomery_u);
+static VALUE mX25519_Provider_Ref10_scalarmult_base(VALUE self, VALUE scalar);
 
 /* Initialize the x25519_ref10 C extension */
 void Init_x25519_ref10()
 {
     mX25519 = rb_define_module("X25519");
-    mX25519_Ref10 = rb_define_module_under(mX25519, "Ref10");
+    mX25519_Provider = rb_define_module_under(mX25519, "Provider");
+    mX25519_Provider_Ref10 = rb_define_module_under(mX25519_Provider, "Ref10");
 
-    rb_define_singleton_method(mX25519_Ref10, "multiply", mX25519_Scalar_multiply, 2);
-    rb_define_singleton_method(mX25519_Ref10, "multiply_base", mX25519_Scalar_multiply_base, 1);
+    rb_define_singleton_method(mX25519_Provider_Ref10, "scalarmult", mX25519_Provider_Ref10_scalarmult, 2);
+    rb_define_singleton_method(mX25519_Provider_Ref10, "scalarmult_base", mX25519_Provider_Ref10_scalarmult_base, 1);
 }
 
 /* Variable-base scalar multiplication */
-static VALUE mX25519_Scalar_multiply(VALUE self, VALUE scalar, VALUE montgomery_u)
+static VALUE mX25519_Provider_Ref10_scalarmult(VALUE self, VALUE scalar, VALUE montgomery_u)
 {
     X25519_KEY product;
 
@@ -57,7 +59,7 @@ static VALUE mX25519_Scalar_multiply(VALUE self, VALUE scalar, VALUE montgomery_
 }
 
 /* Fixed-base scalar multiplication */
-static VALUE mX25519_Scalar_multiply_base(VALUE self, VALUE scalar)
+static VALUE mX25519_Provider_Ref10_scalarmult_base(VALUE self, VALUE scalar)
 {
     X25519_KEY product;
 

data/lib/x25519/scalar.rb

@@ -16,7 +16,7 @@ module X25519
     # @param bytes [String] 32-byte random secret scalar
     def initialize(bytes)
       X25519.validate_key_bytes(bytes)
-      @bytes = bytes
+      @scalar_bytes = bytes
     end
 
     # Variable-base scalar multiplication a.k.a. Diffie-Hellman
@@ -28,7 +28,7 @@ module X25519
     # @return [X25519::MontgomeryU] resulting point (i.e. D-H shared secret)
     def multiply(montgomery_u)
       raise TypeError, "expected X25519::MontgomeryU, got #{montgomery_u}" unless montgomery_u.is_a?(MontgomeryU)
-      MontgomeryU.new(X25519.provider.multiply(@bytes, montgomery_u.to_bytes))
+      MontgomeryU.new(X25519.provider.scalarmult(@scalar_bytes, montgomery_u.to_bytes))
     end
     alias diffie_hellman multiply
 
@@ -37,7 +37,7 @@ module X25519
     #
     # @return [X25519::MontgomeryU] resulting point (i.e. public key)
     def multiply_base
-      MontgomeryU.new(X25519.provider.multiply_base(@bytes))
+      MontgomeryU.new(X25519.provider.scalarmult_base(@scalar_bytes))
     end
     alias public_key multiply_base
 
@@ -45,7 +45,7 @@ module X25519
     #
     # @return [String] scalar converted to a bytestring
     def to_bytes
-      @bytes
+      @scalar_bytes
     end
 
     # String inspection that does not leak the private scalar

data/lib/x25519/test_vectors.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module X25519
+  # Known-good inputs and outputs for X25519 functions
+  module TestVectors
+    # Test vector for variable-base scalar multiplication
+    VariableBaseVector = Struct.new(:scalar, :input_coord, :output_coord)
+
+    # X25519 variable-base test vectors from RFC 7748
+    VARIABLE_BASE = [
+      VariableBaseVector.new(
+        "a546e36bf0527c9d3b16154b82465edd62144c0ac1fc5a18506a2244ba449ac4",
+        "e6db6867583030db3594c1a424b15f7c726624ec26b3353b10a903a6d0ab1c4c",
+        "c3da55379de9c6908e94ea4df28d084f32eccf03491c71f754b4075577a28552"
+      ),
+      VariableBaseVector.new(
+        "4b66e9d4d1b4673c5ad22691957d6af5c11b6421e0ea01d42ca4169e7918ba0d",
+        "e5210f12786811d3f4b7959d0538ae2c31dbe7106fc03c3efc4cd549c715a493",
+        "95cbde9476e8907d7aade45cb4b873f88b595a68799fa152e6f8f7647aac7957"
+      )
+    ].freeze
+
+    # Test vector for fixed-base scalar multiplication
+    FixedBaseVector = Struct.new(:scalar, :output_coord)
+
+    # X25519 fixed-base test vectors, generated via RbNaCl/libsodium
+    FIXED_BASE = [
+      FixedBaseVector.new(
+        "a546e36bf0527c9d3b16154b82465edd62144c0ac1fc5a18506a2244ba449ac4",
+        "1c9fd88f45606d932a80c71824ae151d15d73e77de38e8e000852e614fae7019"
+      ),
+      FixedBaseVector.new(
+        "4b66e9d4d1b4673c5ad22691957d6af5c11b6421e0ea01d42ca4169e7918ba0d",
+        "ff63fe57bfbf43fa3f563628b149af704d3db625369c49983650347a6a71e00e"
+      )
+    ].freeze
+  end
+end

data/lib/x25519/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module X25519
-  VERSION = "0.2.0"
+  VERSION = "1.0.0"
 end

data/lib/x25519.rb

@@ -6,6 +6,7 @@ require "x25519/version"
 
 require "x25519/montgomery_u"
 require "x25519/scalar"
+require "x25519/test_vectors"
 
 # Native extension backends
 require "x25519_ref10"
@@ -18,14 +19,13 @@ module X25519
   # Size of an X25519 key (public or private) in bytes
   KEY_SIZE = 32
 
+  # ref10 is the default provider
+  @provider = X25519::Provider::Ref10
+
   # X25519::Precomputed requires a 4th generation Intel Core CPU or newer,
   # so only enable it if we detect we're on a supported platform. Otherwise,
   # fall back to the ref10 portable C implementation.
-  @provider = if X25519::Precomputed.available?
-                X25519::Precomputed
-              else
-                X25519::Ref10
-              end
+  @provider = X25519::Provider::Precomputed if X25519::Provider::Precomputed.available?
 
   # Selected provider based on the logic above
   def provider
@@ -42,7 +42,7 @@ module X25519
   def diffie_hellman(scalar_bytes, montgomery_u_bytes)
     validate_key_bytes(scalar_bytes)
     validate_key_bytes(montgomery_u_bytes)
-    X25519.provider.multiply(scalar_bytes, montgomery_u_bytes)
+    X25519.provider.scalarmult(scalar_bytes, montgomery_u_bytes)
   end
 
   # Ensure a serialized key meets the requirements
@@ -51,4 +51,20 @@ module X25519
     return true if key_bytes.bytesize == KEY_SIZE
     raise ArgumentError, "expected #{KEY_SIZE}-byte String, got #{key_bytes.bytesize}"
   end
+
+  # Perform a self-test to ensure the selected provider is working
+  def self_test
+    X25519::TestVectors::VARIABLE_BASE.each do |v|
+      shared_secret = provider.scalarmult([v.scalar].pack("H*"), [v.input_coord].pack("H*"))
+      raise "self test failed!" unless shared_secret.unpack("H*").first == v.output_coord
+    end
+
+    X25519::TestVectors::FIXED_BASE.each do |v|
+      public_key = provider.scalarmult_base([v.scalar].pack("H*"))
+      raise "self test failed!" unless public_key.unpack("H*").first == v.output_coord
+    end
+  end
 end
+
+# Automatically run self-test when library loads
+X25519.self_test

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: x25519
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Tony Arcieri
@@ -77,6 +77,7 @@ files:
 - lib/x25519.rb
 - lib/x25519/montgomery_u.rb
 - lib/x25519/scalar.rb
+- lib/x25519/test_vectors.rb
 - lib/x25519/version.rb
 - x25519.gemspec
 homepage: https://github.com/cryptosphere/x25519