x25519 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 28376f61ba4f900dcd58030544eb00afebde6123
-  data.tar.gz: 6888c8dfa66915c4b467cc92bf0eb89a0347487e
+  metadata.gz: 15e4b54930cad9efae470089ed69b14837394163
+  data.tar.gz: b64d42b7a3d9f39ebc2668ce489799ba2f849bef
 SHA512:
-  metadata.gz: 00f25c71faeabe6e09dd6fed15d96a605c82d101a1c248d546bc3043f9f52c781e375e4d7d5f9a99555e04e5fc21ff10cf82fa08e92b20da2e56a32de6e23571
-  data.tar.gz: bcb6b64f41f196bcdeb3e59053732a8fb825619c03e958cb2bbc530d0be1971a8c82cfc7df1f525d10689ecb8b15b7f85b493ed6f48fab70d9974b91f697ad71
+  metadata.gz: f1ccbe8cf45e64fa096399e1814059078a52c0148f51e299abf3b6faeeea88b81c5e913c668a467df999393bbe99ba5dbb67914094b6eda2634bb52690d4421d
+  data.tar.gz: 910e1e2d8a354c4d19a0c8b4bba50f4e452c64addcf7119f9359786eb640d94f73abfd1916ebaeb48fef8c77e034798afb337b1a10c64ce74587880232f0d548

data/.gitignore

@@ -7,6 +7,9 @@
 /pkg/
 /spec/reports/
 /tmp/
+*.o
+*.so
+*.bundle
 
 # rspec failure tracking
 .rspec_status

data/.rubocop.yml

@@ -22,6 +22,9 @@ Metrics/CyclomaticComplexity:
 Metrics/PerceivedComplexity:
   Enabled: false
 
+Metrics/BlockLength:
+  Max: 100
+
 Metrics/ClassLength:
   Max: 100
 

data/CHANGES.md

@@ -0,0 +1,3 @@
+# 0.1.0 (2017-12-11)
+
+* Initial release

data/Gemfile

@@ -5,7 +5,8 @@ source "https://rubygems.org"
 gemspec
 
 group :development, :test do
-  gem "rake"
-  gem "rspec",   "~> 3.7", require: false
+  gem "rake", require: false
+  gem "rake-compiler", "~> 1.0", require: false
+  gem "rspec", "~> 3.7", require: false
   gem "rubocop", "0.51.0", require: false
 end

data/README.md

@@ -1,23 +1,35 @@
-# x25519.rb
+# x25519.rb [![Latest Version][gem-shield]][gem-link] [![Build Status][build-image]][build-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
+[license-image]: https://img.shields.io/badge/License-LGPL%20v3-blue.svg
+[license-link]: https://www.gnu.org/licenses/lgpl-3.0
 
 An efficient public key cryptography library for Ruby providing key
 exchange/agreement.
 
 This gem implements X25519 (a.k.a. Curve25519) Elliptic Curve Diffie-Hellman
 function as described in [RFC7748] as a C extension using the
-high performance [rfc7748-precomputed] implementation based on the paper
-[How to (pre-)compute a ladder].
+high performance [rfc7748_precomputed] implementation based on the paper
+[How to (pre-)compute a ladder]
+(with fallback to the ref10 C implementation).
 
 [RFC7748]: https://tools.ietf.org/html/rfc7748
 [How to (pre-)compute a ladder]: https://eprint.iacr.org/2017/264
 [rfc7748_precomputed]: https://github.com/armfazh/rfc7748_precomputed
 
+## Requirements
+
+* MRI 2.2+
+
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'x25519'
+gem "x25519"
 ```
 
 And then execute:
@@ -30,7 +42,165 @@ Or install it yourself as:
 
 ## Usage
 
-Coming soon!
+The example below shows how to perform a full Diffie-Hellman key exchange:
+
+```ruby
+require "x25519"
+
+# Alice generates random scalar (private key)
+alice_sk = X25519::Scalar.generate
+
+# Alice obtains public key for her private key/scalar
+alice_pk = alice_sk.public_key
+
+# Bob generates random scalar (private key)
+# Ostensibly this would be on a different computer somewhere
+bob_sk = X25519::Scalar.generate
+bob_pk = bob_sk.public_key
+
+# Alice can perform Diffie-Hellman with Bob's public key
+alice_secret = alice_sk.diffie_hellman(bob_pk).to_bytes
+
+# Bob can perform Diffie-Hellman with Alice's public key
+bob_secret = bob_sk.diffie_hellman(alice_pk).to_bytes
+
+# The resulting secrets should be the same
+alice_secret == bob_secret # true
+```
+
+## API
+
+### `X25519::Scalar`: private keys
+
+The `X25519::Scalar` class represents secret integers used as X25519 private
+keys. These secret integers are multiplied by a well-known base point to
+obtain X25519 public keys (`X25519::MontgomeryU`).
+
+#### `X25519::Scalar.generate()`: make a random private key
+
+Generate a random private scalar (using `SecureRandom`)
+
+##### Example
+
+```ruby
+secret_key = X25519::Scalar.generate
+```
+
+#### `X25519::Scalar.new(bytes)`: load existing private key
+
+* `bytes`: a 32-byte `String` value containing the private key
+
+##### Example
+
+```ruby
+secret_key = X25519::Scalar.new(File.read("alice.key"))
+```
+
+#### `X25519::Scalar#public_key()`: obtain public key for this scalar
+
+NOTE: The `#multiply_base` method is an alias of this one.
+
+Performs fixed-base scalar multiplication (i.e. calculates public key)
+
+##### Return Value
+
+Returns a `X25519::MontgomeryU` object which represents the public key for this private key/scalar.
+
+##### Example
+
+```ruby
+secret_key = X25519::Scalar.generate
+public_key = secret_key.public_key
+```
+
+#### `X25519::Scalar#diffie_hellman(other_public_key)`: obtain public key for this scalar
+
+NOTE: The `#multiply` method is an alias of this one.
+
+Performs variable-base scalar multiplication, computing a shared secret between
+our private scalar and someone else's public key/point.
+
+##### Return Value
+
+Returns a `X25519::MontgomeryU` object which represents the shared secret.
+
+##### Arguments
+
+* `other_public_key`: a `X25519::MontgomeryU` object containing the public key
+  with which we'd like to compute a shared secret.
+
+##### Example
+
+```ruby
+secret_key = X25519::Scalar.generate
+public_key = X25519::MontgomeryU.new(File.read("bob.pub"))
+
+# Returns an X25519::MontgomeryU
+shared_secret = secret_key.multiply(public_key)
+
+# Obtain the shared secret as a serialized byte representation
+shared_secret_bytes = shared_secret.to_bytes
+```
+
+#### `X25519::Scalar#to_bytes`: serialize a scalar as a `String`
+
+##### Return Value
+
+Returns a `String` containing a byte representation of this scalar:
+
+##### Example
+
+```ruby
+secret_key = X25519::Scalar.new(...)
+File.write("alice.key", secret_key.to_bytes)
+```
+
+### `X25519::MontgomeryU`: public keys and shared secrets
+
+The `X25519::MontgomeryU` class represents a coordinate (specifically a
+Montgomery-u coordinate) on the elliptic curve. In the X25519 Diffie-Hellman
+function, these serve both as public keys and as shared secrets.
+
+#### `X25519::MontgomeryU.new(bytes)`: load existing public key
+
+##### Arguments
+
+* `bytes`: a 32-byte `String` value containing the public key
+
+##### Example
+
+```ruby
+public_key = X25519::MontgomeryU.new(File.read("bob.pub"))
+```
+
+#### `X25519::MontgomeryU#to_bytes`: serialize a Montgomery-u coordinate as a `String`
+
+##### Return Value
+
+Returns a `String` containing a byte representation of a compressed Montgomery-u coordinate:
+
+##### Example
+
+```ruby
+public_key = X25519::MontgomeryU..new(...)
+File.write("bob.pub", public_key.to_bytes)
+```
+
+### `X25519`: module-level functionality
+
+#### `X25519.diffie_hellman(secret_key, public_key)`: shorthand `String`-oriented API
+
+If you'd like to avoid the object-oriented API, you can use a simplified API which
+acts entirely on bytestrings.
+
+##### Arguments
+
+* `secret_key`: a 32-byte `String` containing a private scalar
+* `public_key`: a 32-byte `String` containing a compressed Montgomery-u coordinate
+
+##### Return Value
+
+Returns a `String` containing a 32-byte compressed Montgomery-u coordinate
 
 ## Contributing
 
@@ -41,27 +211,48 @@ code of conduct.
 
 ## Implementation Details
 
+This gem contains two implementations of X25519: an optimized assembly
+implementation and a portable C implementation. Implementations are selected
+based on available CPU features.
+
+### [rfc7748_precomputed]: optimized assembly implementation
+
 * Prime field arithmetic is optimized for the 4th and 6th generation of Intel Core processors (Haswell and Skylake micro-architectures).
 * Efficient integer multiplication using MULX instruction.
 * Integer additions accelerated with ADCX/ADOX instructions.
-* Key generation uses a read-only table of 8 KB (25 KB) for X25519 (X448).
+* Key generation uses a read-only table of 8 KB for X25519.
+
+### ref10: portable C implementation
+
+* Taken from the [SUPERCOP] cryptographic benchmarking suite (supercop-20171020)
+* Portable C code which should compile on any architecture
+
+[SUPERCOP]: https://bench.cr.yp.to/supercop.html
 
 ## Designers
 
-Thomaz Oliveira, Computer Science Department, Cinvestav-IPN, Mexico.
-Julio López, University of Campinas, Brazil.
-Hüseyin Hisil, Yasar University, Turkey.
-Armando Faz-Hernández, University of Campinas, Brazil.
-Francisco Rodríguez-Henríquez, Computer Science Department, Cinvestav-IPN, Mexico.
+The X25519 Diffie-Hellman function was originally designed by Dan Bernstein:
+
+https://cr.yp.to/ecdh.html
+
+The optimized [rfc7748_precomputed] implementation was designed by:
+
+* Thomaz Oliveira, Computer Science Department, Cinvestav-IPN, Mexico.
+* Julio López, University of Campinas, Brazil.
+* Hüseyin Hisil, Yasar University, Turkey.
+* Armando Faz-Hernández, University of Campinas, Brazil.
+* Francisco Rodríguez-Henríquez, Computer Science Department, Cinvestav-IPN, Mexico.
+
+## Copyright and License
 
-## License
+Copyright (c) 2017 Armando Faz, Tony Arcieri
 
-The gem is available as open source under the terms of the
+This gem is available as open source under the terms of the
 GNU Lesser General Public License v3.0 ([LICENSE](https://www.gnu.org/licenses/lgpl-3.0.txt))
 
 ## Code of Conduct
 
-Everyone interacting in the X25519 project’s codebases, issue trackers, chat
+Everyone interacting in the x25519.rb project’s codebases, issue trackers, chat
 rooms and mailing lists is expected to follow the [code of conduct].
 
 [code of conduct]: https://github.com/cryptosphere/x25519/blob/master/CODE_OF_CONDUCT.md

data/Rakefile

@@ -2,10 +2,18 @@
 
 require "bundler/gem_tasks"
 
+require "rake/clean"
+CLEAN.include("**/*.o", "**/*.so", "**/*.bundle", "pkg", "tmp")
+
+require "rake/extensiontask"
+Rake::ExtensionTask.new("x25519") do |ext|
+  ext.ext_dir = "ext/x25519"
+end
+
 require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new
 
 require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
-task default: %w[spec rubocop]
+task default: %w[compile spec rubocop]

data/ext/x25519/cputest.c

@@ -0,0 +1,68 @@
+/*
+Test for 4th generation Intel Core processor family features (e.g. Haswell)
+From https://software.intel.com/en-us/articles/how-to-detect-new-instruction-support-in-the-4th-generation-intel-core-processor-family
+*/
+
+#include <stdint.h>
+#if defined(_MSC_VER)
+# include <intrin.h>
+#endif
+
+static void run_cpuid(uint32_t eax, uint32_t ecx, uint32_t* abcd)
+{
+#if defined(_MSC_VER)
+    __cpuidex(abcd, eax, ecx);
+#else
+    uint32_t ebx = 0, edx;
+# if defined( __i386__ ) && defined ( __PIC__ )
+     /* in case of PIC under 32-bit EBX cannot be clobbered */
+    __asm__ ( "movl %%ebx, %%edi \n\t cpuid \n\t xchgl %%ebx, %%edi" : "=D" (ebx),
+# else
+    __asm__ ( "cpuid" : "+b" (ebx),
+# endif
+              "+a" (eax), "+c" (ecx), "=d" (edx) );
+    abcd[0] = eax; abcd[1] = ebx; abcd[2] = ecx; abcd[3] = edx;
+#endif
+}
+
+static int check_xcr0_ymm()
+{
+    uint32_t xcr0;
+#if defined(_MSC_VER)
+    xcr0 = (uint32_t)_xgetbv(0);  /* min VS2010 SP1 compiler is required */
+#else
+    __asm__ ("xgetbv" : "=a" (xcr0) : "c" (0) : "%edx" );
+#endif
+    return ((xcr0 & 6) == 6); /* checking if xmm and ymm state are enabled in XCR0 */
+}
+
+int check_4th_gen_intel_core_features()
+{
+    uint32_t abcd[4];
+    uint32_t fma_movbe_osxsave_mask = ((1 << 12) | (1 << 22) | (1 << 27));
+    uint32_t avx2_bmi12_mask = (1 << 5) | (1 << 3) | (1 << 8);
+
+    /* CPUID.(EAX=01H, ECX=0H):ECX.FMA[bit 12]==1   &&
+       CPUID.(EAX=01H, ECX=0H):ECX.MOVBE[bit 22]==1 &&
+       CPUID.(EAX=01H, ECX=0H):ECX.OSXSAVE[bit 27]==1 */
+    run_cpuid( 1, 0, abcd );
+    if ( (abcd[2] & fma_movbe_osxsave_mask) != fma_movbe_osxsave_mask )
+        return 0;
+
+    if ( ! check_xcr0_ymm() )
+        return 0;
+
+    /*  CPUID.(EAX=07H, ECX=0H):EBX.AVX2[bit 5]==1  &&
+        CPUID.(EAX=07H, ECX=0H):EBX.BMI1[bit 3]==1  &&
+        CPUID.(EAX=07H, ECX=0H):EBX.BMI2[bit 8]==1  */
+    run_cpuid( 7, 0, abcd );
+    if ( (abcd[1] & avx2_bmi12_mask) != avx2_bmi12_mask )
+        return 0;
+
+    /* CPUID.(EAX=80000001H):ECX.LZCNT[bit 5]==1 */
+    run_cpuid( 0x80000001, 0, abcd );
+    if ( (abcd[2] & (1 << 5)) == 0)
+        return 0;
+
+    return 1;
+}

data/ext/x25519/extconf.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/GlobalVars
+
+require "mkmf"
+
+abort("missing posix_memalign()") unless have_func("posix_memalign", "stdlib.h")
+
+$INCFLAGS << " -I$(srcdir)/ref10 -I$(srcdir)/rfc7748_precomputed"
+
+# Check for Intel 4th Gen Core CPU features
+# TODO: move this detection completely to runtime
+cputest_c = <<SRC
+  #{File.read(File.expand_path('cputest.c', __dir__))}
+  int main() {
+    return check_4th_gen_intel_core_features() != 1;
+  }
+SRC
+
+if try_run(cputest_c)
+  $defs.push("-DHAVE_4TH_GEN_INTEL_CORE")
+  $CFLAGS << " -Wall -O3 -pedantic -std=c99 -mbmi -mbmi2 -march=native -mtune=native"
+  $srcs = Dir.glob(File.join(__dir__, "**", "*.c"))
+else
+  # Do not include the rfc7748_precomputed sources if we do not have a 4th gen+ Core CPU
+  $srcs = Dir.glob(File.join(__dir__, "*.c")) + Dir.glob(File.expand_path("ref10/*.c", __dir__))
+end
+
+$objs = $srcs.map { |src| src.sub(/\.c$/, ".o") }
+
+create_makefile "x25519"

data/ext/x25519/ref10/api.h

@@ -0,0 +1,2 @@
+#define CRYPTO_BYTES 32
+#define CRYPTO_SCALARBYTES 32

data/ext/x25519/ref10/base.c

@@ -0,0 +1,12 @@
+#include "fe.h"
+
+int x25519_ref10_scalarmult(uint8_t *q,
+  const uint8_t *n,
+  const uint8_t *p);
+
+static const uint8_t x25519_basepoint[32] = {9};
+
+int x25519_ref10_scalarmult_base(uint8_t *q, const uint8_t *n)
+{
+  return x25519_ref10_scalarmult(q,n,x25519_basepoint);
+}