rbnacl 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5f8462f580b5f1517e510c7cf5137b4dc5edec1f
-  data.tar.gz: e6ef35925227eeb5e49edb8868ab1f375002fa3a
+  metadata.gz: 4868c75138fed2d13cc2c2e101961e5149a2f950
+  data.tar.gz: 9b2bc9e35ff45cf67715ae49a86f3667dff2609a
 SHA512:
-  metadata.gz: 3f66ffdf3087fd9f5b77f85c0e87f68825ed7c9c4cfe07c45d37cab48f299971cd4e07e0a443dde9fa7d7bf245df0834eda82cc4a9f1c4afc52c10cc0602b184
-  data.tar.gz: a25f2a0fbed4b8b09a9c8bbb4e2d4029e0327684483b1aabf7f2ac8d7023cab716b51a78a38c5531c786f9a143ad6b8c5176a6aafa27ca6347a34f4379aaf06c
+  metadata.gz: 6667126547e0562e40b3d653b998058a4cc2f4dab18063d636285ca957d5b3c500eac93966946bcf9989bcad24c312208edbb856b34d53391d6ce7d2eec97932
+  data.tar.gz: 4e2d2f6ac34fa25972361afa81e8d0ae1c08f6b344e3fba43cdba92790daf1b00c824b564f4c5a3a64070fb2b7a6f9698e546ede8ec9088295a43355528958cd

data/.travis.yml

@@ -1,15 +1,11 @@
 script: "LD_LIBRARY_PATH=lib bundle exec rake ci"
 
 rvm:
-  - 1.8.7
   - 1.9.3
   - 2.0.0
-  - ree
   - ruby-head
-  - jruby-18mode
-  - jruby-19mode
+  - jruby
   - jruby-head
-  - rbx-18mode
   - rbx-19mode 
 
 matrix:

data/CHANGES.md

@@ -1,3 +1,30 @@
+2.0.0 (2013-11-07)
+------------------
+* Add encrypt/decrypt aliases for Crypto::RandomNonceBox
+* Rename Crypto module to RbNaCl module
+* RbNaCl::VerifyKey#verify operand order was reversed. New operand order is
+  signature, message instead of message, signature
+* RbNaCL::SecretBox#open, RbNaCl::Box#open, Auth#verify and VerifyKey#verify 
+  all now raise a (descendent of) CryptoError if the check fails.  This ensures
+  failures are handled by the program.
+* RbNaCl::SecretBox, Box, etc. are all now aliases for the real implementations,
+  which are named after the primitives they provide
+* Encoders have now gone.
+* Add support for the Blake2b cryptographic hash algorithm.
+* Add checks that we have a sufficiently recent version of libsodium (0.4.3+)
+* Dropped ruby-1.8 support
+* Call the `sodium_init()` function, to select the best algorithms.
+* Fix some typos in the documentation
+* Changes in the low level binding for libsodium and removal of the NaCl module
+* Add a mutex around calls to randombytes in libsodium
+
+1.1.0 (2013-04-19)
+------------------
+
+* Provide API for querying primitives and details about them, such as key
+  lengths, nonce lengths, etc.
+* Fixed bug on passing null bytes to sha256, sha512 functions.
+
 1.0.0 (2013-03-08)
 ------------------
 * Initial release

data/Gemfile

@@ -3,7 +3,10 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in rbnacl.gemspec
 gemspec
 
+group :development do
+  gem 'guard-rspec'
+end
+
 group :test do
-  gem 'base32'
   gem 'coveralls', :require => false
 end

data/Guardfile

@@ -0,0 +1,8 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :rspec do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/README.md

@@ -2,7 +2,6 @@
 ======
 [![Gem Version](https://badge.fury.io/rb/rbnacl.png)](http://badge.fury.io/rb/rbnacl)
 [![Build Status](https://travis-ci.org/cryptosphere/rbnacl.png?branch=master)](https://travis-ci.org/cryptosphere/rbnacl)
-[![Dependency Status](https://gemnasium.com/cryptosphere/rbnacl.png)](https://gemnasium.com/cryptosphere/rbnacl)
 [![Code Climate](https://codeclimate.com/github/cryptosphere/rbnacl.png)](https://codeclimate.com/github/cryptosphere/rbnacl)
 [![Coverage Status](https://coveralls.io/repos/cryptosphere/rbnacl/badge.png?branch=master)](https://coveralls.io/r/cryptosphere/rbnacl)
 
@@ -47,6 +46,10 @@ is extremely fast with comparatively small cryptographic keys.
 For more information on NaCl's goals, see Dan Bernstein's presentation
 [Blaming the Cryptographic User](http://cr.yp.to/talks/2012.08.08/slides.pdf)
 
+### Is it any good?
+
+[Yes.](http://news.ycombinator.com/item?id=3067434)
+
 ## Supported platforms
 
 You can use RbNaCl anywhere you can get libsodium installed (see below).
@@ -54,7 +57,6 @@ RbNaCl is continuously integration tested on the following Ruby VMs:
 
 * MRI 2.0
 * MRI 1.9 (YARV)
-* MRI 1.8 / REE
 * JRuby 1.7 (in both 1.8/1.9 mode)
 * Rubinius HEAD (in both 1.8/1.9 mode)
 
@@ -200,6 +202,53 @@ Coursera offers from Stanford University Professor Dan Boneh:
 
 [http://crypto-class.org](http://crypto-class.org)
 
+## Important Questions
+
+### Is it "Military Grade™"?
+
+Only if your military understands twisted Edwards curves
+
+### Does it have a lock with a checkmark?
+
+Sure, here you go:
+
+![Checkmarked Lock](http://i.imgur.com/dwA0Ffi.png)
+
+### Is it full of NSA backdoors?
+
+![No NIST](http://i.imgur.com/HSxeAmp.png)
+
+The design of RbNaCl's primitives is completely free from NIST (and by
+association, NSA) influence, with the following minor exceptions:
+
+* The Poly1305 MAC, used for authenticating integrity of ciphertexts, uses AES
+  as a replaceable component
+* The Ed25519 digital signature algorithm uses SHA-512 for both key derivation
+  and computing message digests
+* APIs are provided to certain NIST hash functions, including SHA-256, SHA-512,
+  and their associated HMAC counterparts
+
+Otherwise, all of the algorithms in NaCl were designed by Dan Bernstein and his
+collaborators.
+
+The design choices in NaCl, particularly in regard to the Curve25519
+Diffie-Hellman function, emphasize security (whereas [NIST curves emphasize
+"performance" at the cost of security][nist-security-dangers]), and "magic
+constants" in NaCl are picked by theorems designed to maximize security.
+The same cannot be said of NIST curves, where the specific origins of certain
+constants are not described by the standards and may be subject to malicious
+influence by the NSA.
+
+It is the opinion of this library's authors that Dan Bernstein is unlikely to be
+subject to NSA influence (although we have no way of actually knowing this).
+
+Dan Bernstein's designs have been well-scrutinized both as part of the [ESTREAM
+Project](https://en.wikipedia.org/wiki/ESTREAM) and the cryptographic community
+as a whole. And despite the emphasis on higher security, NaCl's primitives are
+faster across-the-board than most implementations of the NIST standards.
+
+[nist-security-dangers]: http://www.hyperelliptic.org/tanja/vortraege/20130531.pdf
+
 ## Contributing
 
 * Fork this repository on Github
@@ -208,5 +257,5 @@ Coursera offers from Stanford University Professor Dan Boneh:
 
 ## License
 
-Copyright (c) 2013 Tony Arcieri, Jonathan Stott.
+Copyright (c) 2013 Jonathan Stott, Tony Arcieri.
 Distributed under the MIT License. See LICENSE.txt for further details.

data/lib/rbnacl/auth.rb

@@ -1,5 +1,6 @@
 # encoding: binary
-module Crypto
+module RbNaCl
+
   # Secret Key Authenticators
   #
   # These provide a means of verifying the integrity of a message, but only
@@ -18,10 +19,8 @@ module Crypto
     # A new authenticator, ready for auth and verification
     #
     # @param [#to_str] key the key used for authenticators, 32 bytes.
-    # @param [#to_sym] encoding decode key from this format (default raw)
-    def initialize(key, encoding = :raw)
-      @key = Encoder[encoding].decode(key)
-      Util.check_length(@key, key_bytes, "#{self.class} key")
+    def initialize(key)
+      @key = Util.check_string(key, key_bytes, "#{self.class} key")
     end
 
     # Compute authenticator for message
@@ -37,38 +36,42 @@ module Crypto
     # Verifies the given authenticator with the message.
     #
     # @param [#to_str] key the key used for the authenticator
-    # @param [#to_str] message the message to be authenticated
     # @param [#to_str] authenticator to be checked
+    # @param [#to_str] message the message to be authenticated
+    #
+    # @raise [BadAuthenticatorError] if the tag isn't valid
+    # @raise [LengthError]  if the tag is of the wrong length
     #
     # @return [Boolean] Was it valid?
-    def self.verify(key, message, authenticator)
-      new(key).verify(message, authenticator)
+    def self.verify(key, authenticator, message)
+      new(key).verify(authenticator, message)
     end
 
     # Compute authenticator for message
     #
     # @param [#to_str] message the message to authenticate
-    # @param [#to_sym] authenticator_encoding format of the authenticator (default raw)
     #
     # @return [String] The authenticator in the requested encoding (default raw)
-    def auth(message, authenticator_encoding = :raw)
+    def auth(message)
       authenticator = Util.zeros(tag_bytes)
       message = message.to_str
-      compute_authenticator(message, authenticator)
-      Encoder[authenticator_encoding].encode(authenticator)
+      compute_authenticator(authenticator, message)
+      authenticator
     end
 
     # Verifies the given authenticator with the message.
     #
     # @param [#to_str] authenticator to be checked
     # @param [#to_str] message the message to be authenticated
-    # @param [#to_sym] authenticator_encoding format of the authenticator (default raw)
+    #
+    # @raise [BadAuthenticatorError] if the tag isn't valid
+    # @raise [LengthError]  if the tag is of the wrong length
     #
     # @return [Boolean] Was it valid?
-    def verify(message, authenticator, authenticator_encoding = :raw)
-      auth = Encoder[authenticator_encoding].decode(authenticator)
-      return false unless auth.bytesize == tag_bytes
-      verify_message(message, auth)
+    def verify(authenticator, message)
+      auth = authenticator.to_s
+      Util.check_length(auth, tag_bytes, "Provided authenticator")
+      verify_message(auth, message) || raise(BadAuthenticatorError, "Invalid authenticator provided, message is corrupt")
     end
 
     # The crypto primitive for this authenticator instance
@@ -99,7 +102,7 @@ module Crypto
     def tag_bytes; self.class.tag_bytes; end
 
     private
-    def compute_authenticator(message, authenticator); raise NotImplementedError; end
-    def verify_message(message, authenticator);        raise NotImplementedError; end
+    def compute_authenticator(authenticator, message); raise NotImplementedError; end
+    def verify_message(authenticator, message);        raise NotImplementedError; end
   end
 end

data/lib/rbnacl/{keys → boxes/curve25519xsalsa20poly1305}/private_key.rb

@@ -1,6 +1,7 @@
 # encoding: binary
-module Crypto
-  # Crypto::Box private key. Keep it safe
+
+module RbNaCl
+  # RbNaCl::Box private key. Keep it safe
   #
   # This class generates and stores NaCL private keys, as well as providing a
   # reference to the public key associated with this private key, if that's
@@ -9,12 +10,22 @@ module Crypto
   # Note that the documentation for NaCl refers to this as a secret key, but in
   # this library its a private key, to avoid confusing the issue with the
   # SecretBox, which does symmetric encryption.
-  class PrivateKey
+  class Boxes::Curve25519XSalsa20Poly1305::PrivateKey
+
     include KeyComparator
     include Serializable
+      
+    extend Sodium
+
+    sodium_type      :box
+    sodium_primitive :curve25519xsalsa20poly1305
+
+    sodium_function :box_curve25519xsalsa20poly1305_keypair,
+                    :crypto_box_curve25519xsalsa20poly1305_keypair,
+                    [:pointer, :pointer]
 
     # The size of the key, in bytes
-    BYTES = NaCl::CURVE25519_XSALSA20_POLY1305_SECRETKEY_BYTES
+    BYTES = Boxes::Curve25519XSalsa20Poly1305::PRIVATEKEYBYTES
 
     # Initializes a new PrivateKey for key operations.
     #
@@ -25,23 +36,23 @@ module Crypto
     # @param private_key [String] The private key
     # @param key_encoding [Symbol] The encoding of the key
     #
-    # @raise [Crypto::LengthError] If the key is not valid after decoding.
+    # @raise [TypeError] If the key is nil
+    # @raise [RbNaCl::LengthError] If the key is not valid after decoding.
     #
     # @return A new PrivateKey
-    def initialize(private_key, key_encoding = :raw)
-      @private_key = Crypto::Encoder[key_encoding].decode(private_key)
-      Util.check_length(@private_key, BYTES, "Private key")
+    def initialize(private_key)
+      @private_key = Util.check_string(private_key, BYTES, "Private key")
     end
 
     # Generates a new keypair
     #
-    # @raise [Crypto::CryptoError] if key generation fails, due to insufficient randomness.
+    # @raise [RbNaCl::CryptoError] if key generation fails, due to insufficient randomness.
     #
-    # @return [Crypto::PrivateKey] A new private key, with the associated public key also set.
+    # @return [RbNaCl::PrivateKey] A new private key, with the associated public key also set.
     def self.generate
-      pk = Util.zeros(NaCl::CURVE25519_XSALSA20_POLY1305_PUBLICKEY_BYTES)
-      sk = Util.zeros(NaCl::CURVE25519_XSALSA20_POLY1305_SECRETKEY_BYTES)
-      NaCl.crypto_box_curve25519xsalsa20poly1305_keypair(pk, sk) || raise(CryptoError, "Failed to generate a key pair")
+      pk = Util.zeros(Boxes::Curve25519XSalsa20Poly1305::PUBLICKEYBYTES)
+      sk = Util.zeros(Boxes::Curve25519XSalsa20Poly1305::PRIVATEKEYBYTES)
+      self.box_curve25519xsalsa20poly1305_keypair(pk, sk) || raise(CryptoError, "Failed to generate a key pair")
       new(sk)
     end
 
@@ -56,22 +67,14 @@ module Crypto
     #
     # @return [PublicKey] the key
     def public_key
-      @public_key ||= PublicKey.new(Point.base.mult(to_bytes))
-    end
-
-    # The crypto primitive the PrivateKey class is to be used for
-    #
-    # @return [Symbol] The primitive
-    def self.primitive
-      :curve25519_xsalsa20_poly1305
+      @public_key ||= PublicKey.new GroupElements::Curve25519.base.mult(to_bytes)
     end
-
+    
     # The crypto primitive this PrivateKey is to be used for.
     #
     # @return [Symbol] The primitive
     def primitive
       self.class.primitive
     end
-
   end
 end

data/lib/rbnacl/{keys → boxes/curve25519xsalsa20poly1305}/public_key.rb

@@ -1,31 +1,31 @@
 # encoding: binary
-module Crypto
-  # Crypto::Box public key. Send to your friends.
+
+module RbNaCl
+  # RbNaCl::Box public key. Send it (securely!) to your friends.
   #
-  # This class stores the NaCL public key, and provides some convience
+  # This class stores the NaCL public key, and provides some convenience
   # functions for working with it.
-  class PublicKey
+  class Boxes::Curve25519XSalsa20Poly1305::PublicKey
+
     include KeyComparator
     include Serializable
 
     # The size of the key, in bytes
-    BYTES = NaCl::CURVE25519_XSALSA20_POLY1305_PUBLICKEY_BYTES
+    BYTES = Boxes::Curve25519XSalsa20Poly1305::PUBLICKEYBYTES
 
     # Initializes a new PublicKey for key operations.
     #
     # Takes the (optionally encoded) public key bytes.  This can be shared with
     # many people and used to establish key pairs with their private key, for
-    # the exchanging of messages using a Crypto::Box
+    # the exchanging of messages using a RbNaCl::Box
     #
     # @param public_key [String] The public key
-    # @param key_encoding [Symbol] The encoding of the key
     #
-    # @raise [Crypto::LengthError] If the key is not valid after decoding.
+    # @raise [RbNaCl::LengthError] If the key is not valid after decoding.
     #
     # @return A new PublicKey
-    def initialize(public_key, key_encoding = :raw)
-      @public_key = Crypto::Encoder[key_encoding].decode(public_key)
-      Util.check_length(@public_key, BYTES, "Public key")
+    def initialize(public_key)
+      @public_key = Util.check_string(public_key, BYTES, "Public key")
     end
 
     # The raw bytes of the key
@@ -39,7 +39,7 @@ module Crypto
     #
     # @return [Symbol] The primitive
     def self.primitive
-      :curve25519_xsalsa20_poly1305
+      :curve25519xsalsa20poly1305
     end
 
     # The crypto primitive this PublicKey is to be used for.
@@ -49,4 +49,5 @@ module Crypto
       self.class.primitive
     end
   end
+
 end

data/lib/rbnacl/boxes/curve25519xsalsa20poly1305.rb

@@ -0,0 +1,185 @@
+# encoding: binary
+module RbNaCl
+  module Boxes
+    # The Box class boxes and unboxes messages between a pair of keys
+    #
+    # This class uses the given public and secret keys to derive a shared key,
+    # which is used with the nonce given to encrypt the given messages and
+    # decrypt the given ciphertexts.  The same shared key will generated from
+    # both pairing of keys, so given two keypairs belonging to alice (pkalice,
+    # skalice) and bob(pkbob, skbob), the key derived from (pkalice, skbob) with
+    # equal that from (pkbob, skalice).  This is how the system works:
+    #
+    # @example
+    #   # On bob's system
+    #   bobkey = RbNaCl::PrivateKey.generate
+    #   #=> #<RbNaCl::PrivateKey ...>
+    #
+    #   # send bobkey.public_key to alice
+    #   # recieve alice's public key, alicepk
+    #   # NB: This is actually the hard part of the system.  How to do it securely
+    #   # is left as an exercise to for the reader.
+    #   alice_pubkey = "..."
+    #
+    #   # make a box
+    #   alicebob_box = RbNaCl::Box.new(alice_pubkey, bobkey)
+    #   #=> #<RbNaCl::Box ...>
+    #
+    #   # encrypt a message to alice
+    #   cipher_text = alicebob_box.box("A bad example of a nonce", "Hello, Alice!")
+    #   #=> "..." # a string of bytes, 29 bytes long
+    #
+    #   # send ["A bad example of a nonce", cipher_text] to alice
+    #   # note that nonces don't have to be secret
+    #   # receive [nonce, cipher_text_to_bob] from alice
+    #
+    #   # decrypt the reply
+    #   # Alice has been a little more sensible than bob, and has a random nonce
+    #   # that is too fiddly to type here.  But there are other choices than just
+    #   # random
+    #   plain_text = alicebob_box.open(nonce, cipher_text_to_bob)
+    #   #=> "Hey there, Bob!"
+    #
+    #   # we have a new message!
+    #   # But Eve has tampered with this message, by flipping some bytes around!
+    #   # [nonce2, cipher_text_to_bob_honest_love_eve]
+    #   alicebob_box.open(nonce2, cipher_text_to_bob_honest_love_eve)
+    #
+    #   # BOOM!
+    #   # Bob gets a RbNaCl::CryptoError to deal with!
+    #
+    # It is VITALLY important that the nonce is a nonce, i.e. it is a number used
+    # only once for any given pair of keys.  If you fail to do this, you
+    # compromise the privacy of the the messages encrypted.  Also, bear in mind
+    # the property mentioned just above. Give your nonces a different prefix, or
+    # have one side use an odd counter and one an even counter.  Just make sure
+    # they are different.
+    #
+    # The ciphertexts generated by this class include a 16-byte authenticator which
+    # is checked as part of the decryption.  An invalid authenticator will cause
+    # the unbox function to raise.  The authenticator is not a signature.  Once
+    # you've looked in the box, you've demonstrated the ability to create
+    # arbitrary valid messages, so messages you send are repudiable.  For
+    # non-repudiable messages, sign them before or after encryption.
+    class Curve25519XSalsa20Poly1305
+      extend Sodium
+
+      sodium_type      :box
+      sodium_primitive :curve25519xsalsa20poly1305
+      sodium_constant  :NONCEBYTES
+      sodium_constant  :ZEROBYTES
+      sodium_constant  :BOXZEROBYTES
+      sodium_constant  :BEFORENMBYTES
+      sodium_constant  :PUBLICKEYBYTES
+      sodium_constant  :SECRETKEYBYTES, :PRIVATEKEYBYTES
+
+      sodium_function :box_curve25519xsalsa20poly1305_beforenm,
+                      :crypto_box_curve25519xsalsa20poly1305_beforenm,
+                      [:pointer, :pointer, :pointer]
+
+      sodium_function :box_curve25519xsalsa20poly1305_open_afternm,
+                      :crypto_box_curve25519xsalsa20poly1305_open_afternm,
+                      [:pointer, :pointer, :ulong_long, :pointer, :pointer]
+      
+      sodium_function :box_curve25519xsalsa20poly1305_afternm,
+                      :crypto_box_curve25519xsalsa20poly1305_afternm,
+                      [:pointer, :pointer, :ulong_long, :pointer, :pointer]
+
+      # Create a new Box
+      #
+      # Sets up the Box for deriving the shared key and encrypting and
+      # decrypting messages.
+      #
+      # @param public_key [String,RbNaCl::PublicKey] The public key to encrypt to
+      # @param private_key [String,RbNaCl::PrivateKey] The private key to encrypt with
+      # @param encoding [Symbol] Parse keys from the given encoding
+      #
+      # @raise [RbNaCl::LengthError] on invalid keys
+      #
+      # @return [RbNaCl::Box] The new Box, ready to use
+      def initialize(public_key, private_key, encoding = :raw)
+        @public_key   = PublicKey  === public_key  ? public_key  : PublicKey.new(public_key)
+        @private_key  = PrivateKey === private_key ? private_key : PrivateKey.new(private_key)
+        raise IncorrectPrimitiveError unless @public_key.primitive == primitive && @private_key.primitive == primitive
+      end
+
+      # Encrypts a message
+      #
+      # Encrypts the message with the given nonce to the keypair set up when
+      # initializing the class.  Make sure the nonce is unique for any given
+      # keypair, or you might as well just send plain text.
+      #
+      # This function takes care of the padding required by the NaCL C API.
+      #
+      # @param nonce [String] A 24-byte string containing the nonce.
+      # @param message [String] The message to be encrypted.
+      #
+      # @raise [RbNaCl::LengthError] If the nonce is not valid
+      #
+      # @return [String] The ciphertext without the nonce prepended (BINARY encoded)
+      def box(nonce, message)
+        Util.check_length(nonce, nonce_bytes, "Nonce")
+        msg = Util.prepend_zeros(ZEROBYTES, message)
+        ct  = Util.zeros(msg.bytesize)
+
+        self.class.box_curve25519xsalsa20poly1305_afternm(ct, msg, msg.bytesize, nonce, beforenm) || raise(CryptoError, "Encryption failed")
+        Util.remove_zeros(BOXZEROBYTES, ct)
+      end
+      alias encrypt box
+
+      # Decrypts a ciphertext
+      #
+      # Decrypts the ciphertext with the given nonce using the keypair setup when
+      # initializing the class.
+      #
+      # This function takes care of the padding required by the NaCL C API.
+      #
+      # @param nonce [String] A 24-byte string containing the nonce.
+      # @param ciphertext [String] The message to be decrypted.
+      #
+      # @raise [RbNaCl::LengthError] If the nonce is not valid
+      # @raise [RbNaCl::CryptoError] If the ciphertext cannot be authenticated.
+      #
+      # @return [String] The decrypted message (BINARY encoded)
+      def open(nonce, ciphertext)
+        Util.check_length(nonce, nonce_bytes, "Nonce")
+        ct = Util.prepend_zeros(BOXZEROBYTES, ciphertext)
+        message  = Util.zeros(ct.bytesize)
+
+        self.class.box_curve25519xsalsa20poly1305_open_afternm(message, ct, ct.bytesize, nonce, beforenm) || raise(CryptoError, "Decryption failed. Ciphertext failed verification.")
+        Util.remove_zeros(ZEROBYTES, message)
+      end
+      alias decrypt open
+
+      # The crypto primitive for the box class
+      #
+      # @return [Symbol] The primitive used
+      def primitive
+        self.class.primitive
+      end
+
+      # The nonce bytes for the box class
+      #
+      # @return [Integer] The number of bytes in a valid nonce
+      def self.nonce_bytes
+        NONCEBYTES
+      end
+
+      # The nonce bytes for the box instance
+      #
+      # @return [Integer] The number of bytes in a valid nonce
+      def nonce_bytes
+        NONCEBYTES
+      end
+
+      private
+      def beforenm
+        @k ||= begin
+                 k = Util.zeros(BEFORENMBYTES)
+                 self.class.box_curve25519xsalsa20poly1305_beforenm(k, @public_key.to_s, @private_key.to_s) || raise(CryptoError, "Failed to derive shared key")
+                 k
+               end
+      end
+    end
+  end
+end

data/lib/rbnacl/group_elements/curve25519.rb

@@ -0,0 +1,81 @@
+# encoding: binary
+module RbNaCl
+  module GroupElements
+    # Points provide the interface to NaCl's Curve25519 high-speed elliptic
+    # curve cryptography, which can be used for implementing Diffie-Hellman
+    # and other forms of public key cryptography (e.g. RbNaCl::Box)
+    #
+    # Objects of the Point class represent points on Edwards curves. NaCl
+    # defines a base point (the "standard group element") which we can
+    # multiply by an arbitrary integer. This is how NaCl computes public
+    # keys from private keys.
+    class Curve25519
+      # NaCl's Curve25519 base point (a.k.a. standard group element), serialized as hex
+      STANDARD_GROUP_ELEMENT = ["0900000000000000000000000000000000000000000000000000000000000000"].pack("H*").freeze
+
+      # Order of the standard group
+      STANDARD_GROUP_ORDER = 2**252 + 27742317777372353535851937790883648493
+
+      include KeyComparator
+      include Serializable
+
+      extend Sodium
+
+      sodium_type      :scalarmult
+      sodium_primitive :curve25519
+
+      sodium_function  :scalarmult_curve25519,
+                       :crypto_scalarmult_curve25519,
+                       [:pointer, :pointer, :pointer]
+
+      # Number of bytes in a scalar on this curve
+      SCALARBYTES = 32
+      BYTES       = 32
+
+      # Number of bytes in a scalar on this curve
+
+      # Creates a new Point from the given serialization
+      #
+      # @param [String] point location of a group element (32-bytes)
+      #
+      # @return [RbNaCl::Point] the Point at this location
+      def initialize(point)
+        @point = point.to_str
+
+        # FIXME: really should have a separate constant here for group element size
+        # Group elements and scalars are both 32-bits, but that's for convenience
+        Util.check_length(@point, SCALARBYTES, "group element")
+      end
+
+      # Multiply the given integer by this point
+      # This ordering is a bit confusing because traditionally the point
+      # would be the right-hand operand.
+      #
+      # @param [String] integer value to multiply with this Point (32-bytes)
+      #
+      # @return [RbNaCl::Point] result as a Point object
+      def mult(integer, encoding = :raw)
+        integer = integer.to_str
+        Util.check_length(integer, SCALARBYTES, "integer")
+
+        result = Util.zeros(SCALARBYTES)
+        self.class.scalarmult_curve25519(result, integer, @point)
+
+        self.class.new(result)
+      end
+
+      # Return the point serialized as bytes
+      #
+      # @return [String] 32-byte string representing this point
+      def to_bytes; @point; end
+
+      @base_point = new(STANDARD_GROUP_ELEMENT)
+
+      # NaCl's standard base point for all Curve25519 public keys
+      #
+      # @return [RbNaCl::Point] standard base point (a.k.a. standard group element)
+      def self.base; @base_point; end
+      def self.base_point; @base_point; end
+    end
+  end
+end