rbnacl 1.0.0.pre

data/lib/rbnacl/keys/private_key.rb

@@ -0,0 +1,62 @@
+# encoding: binary
+module Crypto
+  # Crypto::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
+  # provided.
+  #
+  # 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
+    include KeyComparator
+    include Serializable
+
+    # The size of the key, in bytes
+    BYTES = Crypto::NaCl::SECRETKEYBYTES
+
+    # Initializes a new PrivateKey for key operations.
+    #
+    # Takes the (optionally encoded) private key bytes.  This class can then be
+    # used for various key operations, including deriving the corresponding
+    # PublicKey
+    #
+    # @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.
+    #
+    # @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")
+    end
+
+    # Generates a new keypair
+    #
+    # @raise [Crypto::CryptoError] if key generation fails, due to insufficient randomness.
+    #
+    # @return [Crypto::PrivateKey] A new private key, with the associated public key also set.
+    def self.generate
+      pk = Util.zeros(NaCl::PUBLICKEYBYTES)
+      sk = Util.zeros(NaCl::SECRETKEYBYTES)
+      NaCl.crypto_box_keypair(pk, sk) || raise(CryptoError, "Failed to generate a key pair")
+      new(sk)
+    end
+
+    # The raw bytes of the key
+    #
+    # @return [String] the raw bytes.
+    def to_bytes
+      @private_key
+    end
+
+    # the public key associated with this private key
+    #
+    # @return [PublicKey] the key
+    def public_key
+      @public_key ||= PublicKey.new(Point.base.mult(to_bytes))
+    end
+  end
+end

data/lib/rbnacl/keys/public_key.rb

@@ -0,0 +1,38 @@
+# encoding: binary
+module Crypto
+  # Crypto::Box public key. Send to your friends.
+  #
+  # This class stores the NaCL public key, and provides some convience
+  # functions for working with it.
+  class PublicKey
+    include KeyComparator
+    include Serializable
+
+    # The size of the key, in bytes
+    BYTES = Crypto::NaCl::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
+    #
+    # @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.
+    #
+    # @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")
+    end
+
+    # The raw bytes of the key
+    #
+    # @return [String] the raw bytes.
+    def to_bytes
+      @public_key
+    end
+  end
+end

data/lib/rbnacl/keys/signing_key.rb

@@ -0,0 +1,74 @@
+# encoding: binary
+module Crypto
+  # Private key for producing digital signatures using the Ed25519 algorithm.
+  # Ed25519 provides a 128-bit security level, that is to say, all known attacks
+  # take at least 2^128 operations, providing the same security level as
+  # AES-128, NIST P-256, and RSA-3072.
+  #
+  # Signing keys are produced from a 32-byte (256-bit) random seed value.
+  # This value can be passed into the SigningKey constructoras a String
+  # whose bytesize is 32.
+  #
+  # The public VerifyKey can be computed from the private 32-byte seed value
+  # as well, eliminating the need to store a "keypair".
+  #
+  # SigningKey produces 64-byte (512-bit) signatures. The signatures are
+  # deterministic: signing the same message will always produce the same
+  # signature. This prevents "entropy failure" seen in other signature
+  # algorithms like DSA and ECDSA, where poor random number generators can
+  # leak enough information to recover the private key.
+  class SigningKey
+    include KeyComparator
+    include Serializable
+
+    attr_reader :verify_key
+
+    # Generate a random SigningKey
+    #
+    # @return [Crypto::SigningKey] Freshly-generated random SigningKey
+    def self.generate
+      new Crypto::Random.random_bytes(NaCl::SECRETKEYBYTES)
+    end
+
+    # Create a SigningKey from a seed value
+    #
+    # @param seed [String] Random 32-byte value (i.e. private key)
+    # @param encoding [Symbol] Parse seed from the given encoding
+    #
+    # @return [Crypto::SigningKey] Key which can sign messages
+    def initialize(seed, encoding = :raw)
+      seed = Encoder[encoding].decode(seed)
+
+      Util.check_length(seed, NaCl::SECRETKEYBYTES, "seed")
+
+      pk = Util.zeros(NaCl::PUBLICKEYBYTES)
+      sk = Util.zeros(NaCl::SECRETKEYBYTES * 2)
+
+      NaCl.crypto_sign_seed_keypair(pk, sk, seed) || raise(CryptoError, "Failed to generate a key pair")
+
+      @seed, @signing_key = seed, sk
+      @verify_key = VerifyKey.new(pk)
+    end
+
+    # Sign a message using this key
+    #
+    # @param message [String] Message to be signed by this key
+    # @param encoding [Symbol] Encode signature in the given format
+    #
+    # @return [String] Signature as bytes 
+    def sign(message, encoding = :raw)
+      buffer = Util.prepend_zeros(NaCl::SIGNATUREBYTES, message)
+      buffer_len = Util.zeros(FFI::Type::LONG_LONG.size)
+
+      NaCl.crypto_sign(buffer, buffer_len, message, message.bytesize, @signing_key)
+
+      signature = buffer[0, NaCl::SIGNATUREBYTES]
+      Encoder[encoding].encode(signature)
+    end
+
+    # Return the raw seed value of this key
+    #
+    # @return [String] seed used to create this key
+    def to_bytes; @seed; end
+  end
+end

data/lib/rbnacl/keys/verify_key.rb

@@ -0,0 +1,76 @@
+# encoding: binary
+module Crypto
+  # The signature was forged or otherwise corrupt
+  class BadSignatureError < CryptoError; end
+
+  # The public key counterpart to an Ed25519 SigningKey for producing digital
+  # signatures. Like the name says, VerifyKeys can be used to verify that a
+  # given digital signature is authentic.
+  #
+  # For more information on the Ed25519 digital signature system, please see
+  # the SigningKey documentation.
+  class VerifyKey
+    include KeyComparator
+    include Serializable
+
+    # Create a new VerifyKey object from a serialized public key. The key can
+    # be decoded from any serialization format supported by the
+    # Crypto::Encoding system.
+    #
+    # @param key [String] Serialized Ed25519 public key
+    # @param encoding [Symbol] Parse key from the given encoding
+    #
+    # @return [Crypto::SigningKey] Key which can sign messages
+    def initialize(key, encoding = :raw)
+      key = Encoder[encoding].decode(key)
+      Util.check_length(key, NaCl::PUBLICKEYBYTES, "key")
+
+      @key = key
+    end
+
+    # Create a new VerifyKey object from a serialized public key. The key can
+    # be decoded from any serialization format supported by the
+    # Crypto::Encoding system.
+    #
+    # You can remember the argument ordering by "verify message with signature"
+    # It's like a legal document, with the signature at the end.
+    #
+    # @param message [String] Message to be authenticated
+    # @param signature [String] Alleged signature to be checked
+    # @param signature_encoding [Symbol] Parse signature from the given encoding
+    #
+    # @return [Boolean] was the signature authentic?
+    def verify(message, signature, signature_encoding = :raw)
+      signature = Encoder[signature_encoding].decode(signature)
+      Util.check_length(signature, NaCl::SIGNATUREBYTES, "signature")
+
+      sig_and_msg = signature + message
+      buffer = Util.zeros(sig_and_msg.bytesize)
+      buffer_len = Util.zeros(FFI::Type::LONG_LONG.size)
+
+      NaCl.crypto_sign_open(buffer, buffer_len, sig_and_msg, sig_and_msg.bytesize, @key)
+    end
+
+    # "Dangerous" (but probably safer) verify that raises an exception if a
+    # signature check fails. This is probably less likely to go unnoticed than
+    # an improperly checked verify, as you are forced to deal with the
+    # exception explicitly (and failing signature checks are certainly an
+    # exceptional condition!)
+    #
+    # The arguments are otherwise the same as the verify method.
+    #
+    # @param message [String] Message to be authenticated
+    # @param signature [String] Alleged signature to be checked
+    # @param signature_encoding [Symbol] Parse signature from the given encoding
+    #
+    # @return [true] Will raise BadSignatureError if signature check fails
+    def verify!(message, signature, signature_encoding = :raw)
+      verify(message, signature, signature_encoding) or raise BadSignatureError, "signature was forged/corrupt"
+    end
+
+    # Return the raw key in byte format
+    #
+    # @return [String] raw key as bytes
+    def to_bytes; @key; end
+  end
+end

data/lib/rbnacl/nacl.rb

@@ -0,0 +1,132 @@
+# encoding: binary
+require 'ffi'
+module Crypto
+  # This module has all the FFI code hanging off it
+  #
+  # And that's all it does, really.
+  #
+  # @private
+  module NaCl
+    extend FFI::Library
+    ffi_lib 'sodium'
+
+    # Wraps an NaCl function so it returns a sane value
+    #
+    # The NaCl functions generally have an integer return value which is 0 in
+    # the case of success and below 0 if they failed.  This is a bit
+    # inconvinient in ruby, where 0 is a truthy value, so this makes them
+    # return true/false based on success.
+    #
+    # @param [Symbol] name Function name that will return true/false
+    # @param [Symbol] function Function to attach
+    # @param [Array<Symbol>] arguments Array of arguments to the function
+    def self.wrap_nacl_function(name, function, arguments)
+      module_eval <<-eos, __FILE__, __LINE__ + 1
+      attach_function #{function.inspect}, #{arguments.inspect}, :int
+      def self.#{name}(*args)
+        ret = #{function}(*args)
+        ret == 0
+      end
+      eos
+    end
+
+    SHA256BYTES = 32
+    wrap_nacl_function :crypto_hash_sha256,
+                       :crypto_hash_sha256_ref,
+                       [:pointer, :string, :long_long]
+
+    SHA512BYTES = 64
+    wrap_nacl_function :crypto_hash_sha512,
+                       :crypto_hash_sha512_ref,
+                       [:pointer, :string, :long_long]
+
+    PUBLICKEYBYTES = 32
+    SECRETKEYBYTES = 32
+    wrap_nacl_function :crypto_box_keypair,
+                       :crypto_box_curve25519xsalsa20poly1305_ref_keypair,
+                       [:pointer, :pointer]
+
+    NONCEBYTES     = 24
+    ZEROBYTES      = 32
+    BOXZEROBYTES   = 16
+    BEFORENMBYTES  = 32
+
+    wrap_nacl_function :crypto_box_beforenm,
+                       :crypto_box_curve25519xsalsa20poly1305_ref_beforenm,
+                       [:pointer, :pointer, :pointer]
+
+    wrap_nacl_function :crypto_box_afternm,
+                       :crypto_box_curve25519xsalsa20poly1305_ref_afternm,
+                       [:pointer, :pointer, :long_long, :pointer, :pointer]
+
+    wrap_nacl_function :crypto_box_open_afternm,
+                       :crypto_box_curve25519xsalsa20poly1305_ref_open_afternm,
+                       [:pointer, :pointer, :long_long, :pointer, :pointer]
+
+    SECRETBOX_KEYBYTES = 32
+    wrap_nacl_function :crypto_secretbox,
+                       :crypto_secretbox_xsalsa20poly1305_ref,
+                       [:pointer, :pointer, :long_long, :pointer, :pointer]
+
+    wrap_nacl_function :crypto_secretbox_open,
+                       :crypto_secretbox_xsalsa20poly1305_ref_open,
+                       [:pointer, :pointer, :long_long, :pointer, :pointer]
+
+    HMACSHA512256_KEYBYTES = 32
+    HMACSHA512256_BYTES = 32
+    wrap_nacl_function :crypto_auth_hmacsha512256,
+                       :crypto_auth_hmacsha512256_ref,
+                       [:pointer, :pointer, :long_long, :pointer]
+    wrap_nacl_function :crypto_auth_hmacsha512256_verify,
+                       :crypto_auth_hmacsha512256_ref_verify,
+                       [:pointer, :pointer, :long_long, :pointer]
+
+    HMACSHA256_KEYBYTES = 32
+    HMACSHA256_BYTES = 32
+    wrap_nacl_function :crypto_auth_hmacsha256,
+                       :crypto_auth_hmacsha256_ref,
+                       [:pointer, :pointer, :long_long, :pointer]
+    wrap_nacl_function :crypto_auth_hmacsha256_verify,
+                       :crypto_auth_hmacsha256_ref_verify,
+                       [:pointer, :pointer, :long_long, :pointer]
+    
+    ONETIME_KEYBYTES = 32
+    ONETIME_BYTES = 16
+    wrap_nacl_function :crypto_auth_onetime,
+                       :crypto_onetimeauth_poly1305_ref,
+                       [:pointer, :pointer, :long_long, :pointer]
+    wrap_nacl_function :crypto_auth_onetime_verify,
+                       :crypto_onetimeauth_poly1305_ref_verify,
+                       [:pointer, :pointer, :long_long, :pointer]
+
+    wrap_nacl_function :random_bytes,
+                       :randombytes,
+                       [:pointer, :long_long]
+
+    wrap_nacl_function :crypto_verify_32,
+                       :crypto_verify_32_ref,
+                       [:pointer, :pointer]
+    wrap_nacl_function :crypto_verify_16,
+                       :crypto_verify_16_ref,
+                       [:pointer, :pointer]
+
+    SIGNATUREBYTES = 64
+    wrap_nacl_function :crypto_sign_seed_keypair,
+                       :crypto_sign_ed25519_ref_seed_keypair,
+                       [:pointer, :pointer, :pointer]
+
+    wrap_nacl_function :crypto_sign,
+                       :crypto_sign_ed25519_ref,
+                       [:pointer, :pointer, :pointer, :long_long, :pointer]
+
+    wrap_nacl_function :crypto_sign_open,
+                       :crypto_sign_ed25519_ref_open,
+                       [:pointer, :pointer, :pointer, :long_long, :pointer]
+
+    SCALARBYTES = 32
+
+    wrap_nacl_function :crypto_scalarmult,
+                       :crypto_scalarmult_curve25519_ref,
+                       [:pointer, :pointer, :pointer]
+  end
+end

data/lib/rbnacl/point.rb

@@ -0,0 +1,67 @@
+# encoding: binary
+module Crypto
+  # NaCl's base point (a.k.a. standard group element), serialized as hex
+  STANDARD_GROUP_ELEMENT = "0900000000000000000000000000000000000000000000000000000000000000".freeze
+
+  # Order of the standard group
+  STANDARD_GROUP_ORDER = 2**252 + 27742317777372353535851937790883648493
+
+  # 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. Crypto::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 Point
+    include KeyComparator
+    include Serializable
+
+    # Creates a new Point from the given serialization
+    #
+    # @param value [String] 32-byte value representing a group element
+    # @param encoding [Symbol] The encoding format of the group element
+    #
+    # @return [Crypto::Point] New Crypto::Point object
+    def initialize(value, encoding = :raw)
+      @point = Encoder[encoding].decode(value)
+
+      # 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, NaCl::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 integer [String] 32-byte integer value
+    # @param encoding [Symbol] The encoding format of the integer
+    #
+    # @return [Crypto::Point] Result as a Point object
+    def mult(integer, encoding = :raw)
+      integer = Encoder[encoding].decode(integer)
+      Util.check_length(integer, NaCl::SCALARBYTES, "integer")
+
+      result = Util.zeros(NaCl::SCALARBYTES)
+      NaCl.crypto_scalarmult(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 = Point.new(STANDARD_GROUP_ELEMENT, :hex)
+
+    # NaCl's standard base point for all Curve25519 public keys
+    #
+    # @return [Crypto::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
+