rbnacl 1.0.0.pre

data/lib/rbnacl/box.rb

@@ -0,0 +1,141 @@
+# encoding: binary
+module Crypto
+  # 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 = Crypto::PrivateKey.generate
+  #   #=> #<Crypto::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 = Crypto::Box.new(alice_pubkey, bobkey)
+  #   #=> #<Crypto::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 Crypto::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 repudiatable.  For
+  # non-repudiatable messages, sign them before or after encryption.
+  class Box
+
+    # Create a new Box
+    #
+    # Sets up the Box for deriving the shared key and encrypting and
+    # decrypting messages.
+    #
+    # @param public_key [String,Crypto::PublicKey] The public key to encrypt to
+    # @param private_key [String,Crypto::PrivateKey] The private key to encrypt with
+    # @param encoding [Symbol] Parse keys from the given encoding
+    #
+    # @raise [Crypto::LengthError] on invalid keys
+    #
+    # @return [Crypto::Box] The new Box, ready to use
+    def initialize(public_key, private_key, encoding = :raw)
+      @public_key  = Encoder[encoding].decode(public_key)  if public_key
+      @private_key = Encoder[encoding].decode(private_key) if private_key
+      Util.check_length(@public_key,  PublicKey::BYTES,  "Public key")
+      Util.check_length(@private_key, PrivateKey::BYTES, "Private key")
+    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 [Crypto::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, Crypto::NaCl::NONCEBYTES, "Nonce")
+      msg = Util.prepend_zeros(NaCl::ZEROBYTES, message)
+      ct  = Util.zeros(msg.bytesize)
+
+      NaCl.crypto_box_afternm(ct, msg, msg.bytesize, nonce, beforenm) || raise(CryptoError, "Encryption failed")
+      Util.remove_zeros(NaCl::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 [Crypto::LengthError] If the nonce is not valid
+    # @raise [Crypto::CryptoError] If the ciphertext cannot be authenticated.
+    #
+    # @return [String] The decrypted message (BINARY encoded)
+    def open(nonce, ciphertext)
+      Util.check_length(nonce, Crypto::NaCl::NONCEBYTES, "Nonce")
+      ct = Util.prepend_zeros(NaCl::BOXZEROBYTES, ciphertext)
+      message  = Util.zeros(ct.bytesize)
+
+      NaCl.crypto_box_open_afternm(message, ct, ct.bytesize, nonce, beforenm) || raise(CryptoError, "Decryption failed. Ciphertext failed verification.")
+      Util.remove_zeros(NaCl::ZEROBYTES, message)
+    end
+    alias decrypt open
+
+    private
+    def beforenm
+      @k ||= begin
+               k = Util.zeros(NaCl::BEFORENMBYTES)
+               NaCl.crypto_box_beforenm(k, @public_key, @private_key) || raise(CryptoError, "Failed to derive shared key")
+               k
+             end
+    end
+  end
+end

data/lib/rbnacl/encoder.rb

@@ -0,0 +1,44 @@
+# encoding: binary
+module Crypto
+  # Encoders can be used to serialize or deserialize keys, ciphertexts, hashes,
+  # and signatures. To provide an encoder, simply subclass Encoder and call the
+  # register class method, then define the encode and decode methods:
+  #
+  #     class CrazysauceEncoder < Crypto::Encoder
+  #       register :crazysauce
+  #
+  #       def encode(string)
+  #         ...
+  #       end
+  #
+  #       def decode(string)
+  #         ...
+  #       end
+  #     end
+  #
+  # Once an encoder has been registered, an instance of it is available via
+  # calling Crypto::Encoder[], e.g. Crypto::Encoder[:hex].encode("foobar")
+  #
+  class Encoder
+    # Hash where encoder objects are stored
+    Registry = {}
+
+    # Register the current class as an encoder
+    def self.register(name)
+      self[name] = self.new
+    end
+
+    # Look up an encoder by the given name
+    def self.[](name)
+      Registry[name.to_sym] or raise ArgumentError, "unsupported encoder: #{name}"
+    end
+
+    # Register an encoder object directly
+    def self.[]=(name, obj)
+      Registry[name.to_sym] = obj
+    end
+
+    def encode(string); raise NotImplementedError, "encoding not implemented"; end
+    def decode(string); raise NotImplementedError, "decoding not implemented"; end
+  end
+end

data/lib/rbnacl/encoders/base32.rb

@@ -0,0 +1,33 @@
+# encoding: binary
+# Requires the base32 gem
+require 'base32'
+
+module Crypto
+  module Encoders
+    # Base64 encoding provider
+    #
+    # Accessable as Crypto::Encoder[:base64]
+    #
+    class Base32 < Crypto::Encoder
+      register :base32
+
+      # Base64 encodes a message
+      #
+      # @param [String] bytes The bytes to encode
+      #
+      # @return [String] Lovely, elegant "Zooko-style" Base32
+      def encode(bytes)
+        ::Base32.encode(bytes.to_s).downcase
+      end
+
+      # Hex decodes a message
+      #
+      # @param [String] base32 string to decode.
+      #
+      # @return [String] crisp and clean bytes
+      def decode(base32)
+        ::Base32.decode(base32.to_s.upcase)
+      end
+    end
+  end
+end

data/lib/rbnacl/encoders/base64.rb

@@ -0,0 +1,30 @@
+# encoding: binary
+module Crypto
+  module Encoders
+    # Base64 encoding provider
+    #
+    # Accessable as Crypto::Encoder[:base64]
+    #
+    class Base64 < Crypto::Encoder
+      register :base64
+
+      # Base64 encodes a message
+      #
+      # @param [String] bytes The bytes to encode
+      #
+      # @return [String] Clunky old base64
+      def encode(bytes)
+        [bytes.to_s].pack("m").gsub("\n", '')
+      end
+
+      # Hex decodes a message
+      #
+      # @param [String] base64 string to decode.
+      #
+      # @return [String] crisp and clean bytes
+      def decode(base64)
+        base64.to_s.unpack("m").first
+      end
+    end
+  end
+end

data/lib/rbnacl/encoders/hex.rb

@@ -0,0 +1,30 @@
+# encoding: binary
+module Crypto
+  module Encoders
+    # Hex encoding provider
+    #
+    # Accessable as Crypto::Encoder[:hex]
+    #
+    class Hex < Crypto::Encoder
+      register :hex
+
+      # Hex encodes a message
+      #
+      # @param [String] bytes The bytes to encode
+      #
+      # @return [String] Tasty, tasty hexidecimal
+      def encode(bytes)
+        bytes.to_s.unpack("H*").first
+      end
+
+      # Hex decodes a message
+      #
+      # @param [String] hex hex to decode.
+      #
+      # @return [String] crisp and clean bytes
+      def decode(hex)
+        [hex.to_s].pack("H*")
+      end
+    end
+  end
+end

data/lib/rbnacl/encoders/raw.rb

@@ -0,0 +1,12 @@
+# encoding: binary
+module Crypto
+  module Encoders
+    # Raw encoder which only does a string conversion (if necessary)
+    class Raw < Crypto::Encoder
+      register :raw
+
+      def encode(bytes); bytes.to_s; end
+      def decode(bytes); bytes.to_s; end
+    end
+  end
+end

data/lib/rbnacl/hash.rb

@@ -0,0 +1,48 @@
+# encoding: binary
+module Crypto
+  # Cryptographic hash functions
+  #
+  # Cryptographic hash functions take a variable length message and compute a
+  # fixed length string, the message digest. Even a small change in the input
+  # data should produce a large change in the digest, and it is 'very difficult'
+  # to create two messages with the same digest.
+  #
+  # A cryptographic hash can be used for checking the integrity of data, but
+  # there is no secret involved in the hashing, so anyone can create the hash of
+  # a given message.
+  #
+  # RbNaCl provides the SHA-256 and SHA-512 hash functions.
+  module Hash
+    # Returns the SHA-256 hash of the given data
+    #
+    # There's no streaming done, just pass in the data and be done with it.
+    #
+    # @param [String] data The data, as a collection of bytes
+    # @param [#to_sym] encoding Encoding of the returned hash.
+    #
+    # @raise [CryptoError] If the hashing fails for some reason.
+    #
+    # @return [String] The SHA-256 hash as raw bytes (Or encoded as per the second argument)
+    def self.sha256(data, encoding = :raw)
+      hash = Util.zeros(NaCl::SHA256BYTES)
+      NaCl.crypto_hash_sha256(hash, data, data.bytesize) || raise(CryptoError, "Hashing failed!")
+      Encoder[encoding].encode(hash)
+    end
+
+    # Returns the SHA-512 hash of the given data
+    #
+    # There's no streaming done, just pass in the data and be done with it.
+    #
+    # @param [String] data The data, as a collection of bytes
+    # @param [#to_sym] encoding Encoding of the returned hash.
+    #
+    # @raise [CryptoError] If the hashing fails for some reason.
+    #
+    # @return [String] The SHA-512 hash as raw bytes (Or encoded as per the second argument)
+    def self.sha512(data, encoding = :raw)
+      hash = Util.zeros(NaCl::SHA512BYTES)
+      NaCl.crypto_hash_sha512(hash, data, data.bytesize) || raise(CryptoError, "Hashing failed!")
+      Encoder[encoding].encode(hash)
+    end
+  end
+end

data/lib/rbnacl/hmac/sha256.rb

@@ -0,0 +1,32 @@
+# encoding: binary
+module Crypto
+  module HMAC
+    # Computes an authenticator as HMAC-SHA-256
+    #
+    # The authenticator can be used at a later time to verify the provenence of
+    # the message by recomputing the HMAC over the message and then comparing it to
+    # the provided authenticator.  The class provides methods for generating
+    # signatures and also has a constant-time implementation for checking them.
+    #
+    # This is a secret key authenticator, i.e. anyone who can verify signatures
+    # can also create them.
+    #
+    # @see http://nacl.cr.yp.to/auth.html
+    class SHA256 < Auth
+      # Number of bytes in a valid key
+      KEYBYTES = NaCl::HMACSHA256_KEYBYTES
+
+      # Number of bytes in a valid authenticator
+      BYTES = NaCl::HMACSHA256_BYTES
+
+      private
+      def compute_authenticator(message, authenticator)
+        NaCl.crypto_auth_hmacsha256(authenticator, message, message.bytesize, key)
+      end
+
+      def verify_message(message, authenticator)
+        NaCl.crypto_auth_hmacsha256_verify(authenticator, message, message.bytesize, key)
+      end
+    end
+  end
+end

data/lib/rbnacl/hmac/sha512256.rb

@@ -0,0 +1,35 @@
+# encoding: binary
+module Crypto
+  module HMAC
+    # Computes an authenticator as HMAC-SHA-512 truncated to 256-bits
+    #
+    # The authenticator can be used at a later time to verify the provenence of
+    # the message by recomputing the HMAC over the message and then comparing it to
+    # the provided authenticator.  The class provides methods for generating
+    # signatures and also has a constant-time implementation for checking them.
+    #
+    # This is a secret key authenticator, i.e. anyone who can verify signatures
+    # can also create them.
+    #
+    # @see http://nacl.cr.yp.to/auth.html
+    class SHA512256 < Auth
+      # Number of bytes in a valid key
+      KEYBYTES = NaCl::HMACSHA512256_KEYBYTES
+
+      # Number of bytes in a valid authenticator
+      BYTES = NaCl::HMACSHA512256_BYTES
+
+      private
+      def compute_authenticator(message, authenticator)
+        NaCl.crypto_auth_hmacsha512256(authenticator, message, message.bytesize, key)
+      end
+
+      def verify_message(message, authenticator)
+        NaCl.crypto_auth_hmacsha512256_verify(authenticator, message, message.bytesize, key)
+      end
+    end
+
+    # TIMTOWTDI!
+    SHA512 = SHA512256
+  end
+end

data/lib/rbnacl/keys/key_comparator.rb

@@ -0,0 +1,59 @@
+# encoding: binary
+module Crypto
+  # Implements comparisons of keys
+  #
+  # This permits both timing invariant equality tests, as well as
+  # lexicographical sorting.
+  module KeyComparator
+    include Comparable
+    # spaceship operator
+    #
+    # @param other [KeyComparator,#to_str] The thing to compare
+    #
+    # @return [0] if the keys are equal
+    # @return [1] if the key is larger than the other key
+    # @return [-1] if the key is smaller than the other key
+    # @return [nil] if comparison doesn't make sense
+    def <=>(other)
+      if KeyComparator > other.class
+        other = other.to_bytes
+      elsif other.respond_to?(:to_str)
+        other = other.to_str
+      else
+        return nil
+      end
+
+      if Util.verify32(self.to_bytes, other)
+        return 0
+      elsif self.to_bytes > other
+        return 1
+      else
+        return -1
+      end
+    end
+
+    # equality operator
+    #
+    # The equality operator is explicity defined, despite including Comparable
+    # and having a spaceship operator, so that if equality tests are desired,
+    # they can be timing invariant, without any chance that the further
+    # comparisons for greater than and less than can leak information.  Maybe
+    # this is too paranoid, but I don't know how ruby works under the hood with
+    # comparable.
+    #
+    # @param other [KeyComparator,#to_str] The thing to compare
+    #
+    # @return [true] if the keys are equal
+    # @return [false] if they keys are not equal
+    def ==(other)
+      if KeyComparator > other.class
+        other = other.to_bytes
+      elsif other.respond_to?(:to_str)
+        other = other.to_str
+      else
+        return false
+      end
+      Util.verify32(self.to_bytes, other)
+    end
+  end
+end