rbnacl 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 15ef68a1b4b1742cf2b8a582119a6772c5faa159
-  data.tar.gz: 28a60711d07476e92d19c42981c58ced76e46d22
+  metadata.gz: 5f8462f580b5f1517e510c7cf5137b4dc5edec1f
+  data.tar.gz: e6ef35925227eeb5e49edb8868ab1f375002fa3a
 SHA512:
-  metadata.gz: 9f0da08b8631268141302d8613d0bf161db9868046e1b94b8b069b8042179c5d23e3936bfeaa1e10e8207f683b698faf5d61fcdac5194378dc56e7046fead956
-  data.tar.gz: 280fd06fbc3a3805d14ee843df4bd3b46865f0be809d6be2ada67094b140af92c1d6c9cce825ec994371696f855b0d04b8d405af1383a18439b7f5b4a7bcc016
+  metadata.gz: 3f66ffdf3087fd9f5b77f85c0e87f68825ed7c9c4cfe07c45d37cab48f299971cd4e07e0a443dde9fa7d7bf245df0834eda82cc4a9f1c4afc52c10cc0602b184
+  data.tar.gz: a25f2a0fbed4b8b09a9c8bbb4e2d4029e0327684483b1aabf7f2ac8d7023cab716b51a78a38c5531c786f9a143ad6b8c5176a6aafa27ca6347a34f4379aaf06c

data/CHANGES.md

@@ -1,4 +1,3 @@
-HEAD
-----
-
-Unreleased!
+1.0.0 (2013-03-08)
+------------------
+* Initial release

data/README.md

@@ -13,7 +13,8 @@ This is a crypto library.
 On a completely unrelated topic, RbNaCl is also the empirical formula for
 Rubidium Sodium Chloride.
 
-Need help with RbNaCl? Join the [RbNaCl Google Group][group]
+Need help with RbNaCl? Join the [RbNaCl Google Group][group].
+We're also on IRC at #cryptosphere on irc.freenode.net
 
 [nacl]:  http://nacl.cr.yp.to/
 [djb]:   http://cr.yp.to/djb.html
@@ -51,8 +52,9 @@ For more information on NaCl's goals, see Dan Bernstein's presentation
 You can use RbNaCl anywhere you can get libsodium installed (see below).
 RbNaCl is continuously integration tested on the following Ruby VMs:
 
-* MRI 1.8 / REE
+* 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)
 
@@ -74,19 +76,9 @@ for information regarding installation:
 
 https://github.com/jedisct1/libsodium
 
-#### OS X
-
-Unfortunately libsodium is not in homebrew proper yet (I would strongly
-encourage you to [ask for libsodium's inclusion in homebrew][homebrew]),
-however you can use homebrew's "tap" feature for the time being to
-install libsodium:
-
-```
-brew tap qmx/homebrew-libsodium
-brew install libsodium
-```
+For OS X users, libsodium is available via homebrew and can be installed with:
 
-[homebrew]: https://github.com/mxcl/homebrew/pull/17275
+    brew install libsodium
 
 ### RbNaCl gem
 
@@ -102,6 +94,12 @@ Or install it yourself as:
 
     $ gem install rbnacl
 
+Inside of your Ruby program do:
+
+    require 'rbnacl'
+
+...to pull it in as a dependency.
+
 ## Documentation
 
 RbNaCl's documentation can be found [in the Wiki][wiki]. The following features
@@ -121,12 +119,15 @@ are supported:
 Additional power-user features are available. Please see the Wiki for further
 information.
 
+[RDoc documentation][rdoc] is also available.
+
 [wiki]: https://github.com/cryptosphere/rbnacl/wiki
 [secretkey]: https://github.com/cryptosphere/rbnacl/wiki/Secret-Key-Encryption
 [publickey]: https://github.com/cryptosphere/rbnacl/wiki/Public-Key-Encryption
 [signatures]: https://github.com/cryptosphere/rbnacl/wiki/Digital-Signatures
 [macs]: https://github.com/cryptosphere/rbnacl/wiki/Authenticators
 [hashes]: https://github.com/cryptosphere/rbnacl/wiki/Hash-Functions
+[rdoc]: http://rubydoc.info/github/cryptosphere/rbnacl/master/frames
 
 ## Security Notes
 
@@ -138,6 +139,32 @@ by professional cryptographers.
 
 That said, it's probably still a million times better than OpenSSL...
 
+## Using Signed Gems
+
+The RbNaCl gem is signed by Tony Arcieri's certificate, which identifies
+as `bascule@gmail.com`. You can obtain the official certificate with:
+
+```
+curl https://raw.github.com/cryptosphere/rbnacl/master/bascule.cert > /tmp/bascule.cert
+gem cert -a /tmp/bascule.cert
+```
+
+You can verify the authenticity of bascule.cert by its SHA256 hash:
+
+```
+$ shasum -a 256 bascule.cert
+6e8b7e53d347ca6c6d214efef2b923aadecdd7650565f0eb1d8d0419723ae20c  bascule.cert
+```
+
+If you get a different number than `6e8b7e53...`, this is not the cert you are
+looking for!
+
+If you'd like to install the gem in high security mode, run:
+
+```
+gem install rbnacl-1.0.0.gem -P HighSecurity
+```
+
 ## Reporting Security Problems
 
 If you have discovered a bug in RbNaCl of a sensitive nature, i.e.

data/bascule.cert

@@ -0,0 +1,21 @@
+-----BEGIN CERTIFICATE-----
+MIIDbDCCAlSgAwIBAgIBATANBgkqhkiG9w0BAQUFADA+MRAwDgYDVQQDDAdiYXNj
+dWxlMRUwEwYKCZImiZPyLGQBGRYFZ21haWwxEzARBgoJkiaJk/IsZAEZFgNjb20w
+HhcNMTMwMzA4MDYwNzA1WhcNMTQwMzA4MDYwNzA1WjA+MRAwDgYDVQQDDAdiYXNj
+dWxlMRUwEwYKCZImiZPyLGQBGRYFZ21haWwxEzARBgoJkiaJk/IsZAEZFgNjb20w
+ggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC8S9Y1eahE5w/b0P1jVbO4
+nZbGwJGnGUTPPujZZfCXdkJu1pa8MvsU+pzgm051/yy9bWUp5eMTIjP9Qg+v92gK
+bfjiUoVwAqISW7zD98gbXwdOgcbCjPFfdP7XmAlxbmq0/T+kYXVngfYo737SukWz
+/3LLzfmtzBAZipJhTL3EAvlD2O2n2m/JARtxUwHjohd5199BBrSgbjKBXrbZ159F
+rJzDZef9SLCeXbVL218C4Z4Yf3QvOAvlkBQbYZmD0jnivAvXaoylZnCgIpGUnEiA
+C3raBW2/zMeKZC7dxygqezxwKiA/u4rxeCK3XDwYlRkF35UtAyIbIJYGODJL4MR9
+AgMBAAGjdTBzMAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQWBBRP3DGA
+NBCsdSMAHGzKpylnYy90ejAcBgNVHREEFTATgRFiYXNjdWxlQGdtYWlsLmNvbTAc
+BgNVHRIEFTATgRFiYXNjdWxlQGdtYWlsLmNvbTANBgkqhkiG9w0BAQUFAAOCAQEA
+NhP3rks+x49coXHS0vPPxXb7V0HDnuYP5R+pN1+T2Z7D4qwJKjEF4EC8mQYtwcNe
+Qquz1t9Uxtr7i3QqjnwhNKlIVig1nikNF+FnApjYs4mwAtMHn77WOwx8wkn7ykej
+7sF7dRE+BLgpJ88/ycnA6zsEiSQVcIMDVpiYUqUBx+MDNnq5jw5dI0Kct8vBirNA
+QiZB6YQD1raVKUTpRubo4i0SnGpbMSxMy+YreqwNQiWG9iWCbp0JJWaOPSYTeQHe
+3L/NVZQttSvxjd+WF6mA9yeCjpomboQMP36GRIZ30SoOVPMGvZ/+QpW52QU7mJW5
+GzWyf92p0uscgUZVTYixjg==
+-----END CERTIFICATE-----

data/lib/rbnacl.rb

@@ -12,6 +12,12 @@ module Crypto
   # This indicates some argument with an expected length was not that length.
   # Since this is probably a cryptographic key, you should check that!
   class LengthError < ArgumentError; end
+
+  # An incorrect primitive has been passed to a method
+  #
+  # This indicates that an attempt has been made to use something (probably a key)
+  # with an incorrect primitive
+  class IncorrectPrimitiveError < ArgumentError; end
 end
 
 # TIMTOWTDI!

data/lib/rbnacl/auth.rb

@@ -21,7 +21,7 @@ module Crypto
     # @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, self.class::KEYBYTES, "#{self.class} key")
+      Util.check_length(@key, key_bytes, "#{self.class} key")
     end
 
     # Compute authenticator for message
@@ -52,7 +52,7 @@ module Crypto
     #
     # @return [String] The authenticator in the requested encoding (default raw)
     def auth(message, authenticator_encoding = :raw)
-      authenticator = Util.zeros(self.class::BYTES)
+      authenticator = Util.zeros(tag_bytes)
       message = message.to_str
       compute_authenticator(message, authenticator)
       Encoder[authenticator_encoding].encode(authenticator)
@@ -67,10 +67,37 @@ module Crypto
     # @return [Boolean] Was it valid?
     def verify(message, authenticator, authenticator_encoding = :raw)
       auth = Encoder[authenticator_encoding].decode(authenticator)
-      return false unless auth.bytesize == self.class::BYTES
+      return false unless auth.bytesize == tag_bytes
       verify_message(message, auth)
     end
 
+    # The crypto primitive for this authenticator instance
+    #
+    # @return [Symbol] The primitive used
+    def primitive
+      self.class.primitive
+    end
+
+    # The number of key bytes for this Auth class
+    #
+    # @return [Integer] number of key bytes
+    def self.key_bytes; self::KEYBYTES; end
+
+    # The number of key bytes for this Auth instance
+    #
+    # @return [Integer] number of key bytes
+    def key_bytes; self.class.key_bytes; end
+
+    # The number bytes in the tag or authenticator from this Auth class
+    #
+    # @return [Integer] number of tag bytes
+    def self.tag_bytes; self::BYTES; end
+
+    # The number of bytes in the tag or authenticator for this Auth instance
+    #
+    # @return [Integer] number of tag bytes
+    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

data/lib/rbnacl/auth/one_time.rb

@@ -23,6 +23,13 @@ module Crypto
 
       # Number of bytes in a valid authenticator
       BYTES = NaCl::ONETIME_BYTES
+      
+      # The crypto primitive for the Auth::OneTime class
+      #
+      # @return [Symbol] The primitive used
+      def self.primitive
+        :poly_1305
+      end
 
       private
       def compute_authenticator(message, authenticator)

data/lib/rbnacl/box.rb

@@ -62,6 +62,9 @@ module Crypto
   # non-repudiatable messages, sign them before or after encryption.
   class Box
 
+    # Number of bytes in a Box nonce
+    NONCEBYTES = NaCl::CURVE25519_XSALSA20_POLY1305_BOX_NONCEBYTES
+
     # Create a new Box
     #
     # Sets up the Box for deriving the shared key and encrypting and
@@ -75,10 +78,9 @@ module Crypto
     #
     # @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")
+      @public_key   = PublicKey  === public_key  ? public_key  : PublicKey.new(public_key, encoding)
+      @private_key  = PrivateKey === private_key ? private_key : PrivateKey.new(private_key, encoding)
+      raise IncorrectPrimitiveError unless @public_key.primitive == primitive && @private_key.primitive == primitive
     end
 
     # Encrypts a message
@@ -96,11 +98,11 @@ module Crypto
     #
     # @return [String] The ciphertext without the nonce prepended (BINARY encoded)
     def box(nonce, message)
-      Util.check_length(nonce, Crypto::NaCl::NONCEBYTES, "Nonce")
+      Util.check_length(nonce, nonce_bytes, "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")
+      NaCl.crypto_box_curve25519_xsalsa20_poly1305_afternm(ct, msg, msg.bytesize, nonce, beforenm) || raise(CryptoError, "Encryption failed")
       Util.remove_zeros(NaCl::BOXZEROBYTES, ct)
     end
     alias encrypt box
@@ -120,20 +122,48 @@ module Crypto
     #
     # @return [String] The decrypted message (BINARY encoded)
     def open(nonce, ciphertext)
-      Util.check_length(nonce, Crypto::NaCl::NONCEBYTES, "Nonce")
+      Util.check_length(nonce, nonce_bytes, "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.")
+      NaCl.crypto_box_curve25519_xsalsa20_poly1305_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
 
+    # The crypto primitive for the box class
+    #
+    # @return [Symbol] The primitive used
+    def self.primitive
+      :curve25519_xsalsa20_poly1305
+    end
+
+    # 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(NaCl::BEFORENMBYTES)
-               NaCl.crypto_box_beforenm(k, @public_key, @private_key) || raise(CryptoError, "Failed to derive shared key")
+               k = Util.zeros(NaCl::CURVE25519_XSALSA20_POLY1305_BOX_BEFORENMBYTES)
+               NaCl.crypto_box_curve25519_xsalsa20_poly1305_beforenm(k, @public_key.to_s, @private_key.to_s) || raise(CryptoError, "Failed to derive shared key")
                k
              end
     end

data/lib/rbnacl/hmac/sha256.rb

@@ -19,6 +19,13 @@ module Crypto
       # Number of bytes in a valid authenticator
       BYTES = NaCl::HMACSHA256_BYTES
 
+      # The crypto primitive for the HMAC::SHA256 class
+      #
+      # @return [Symbol] The primitive used
+      def self.primitive
+        :hmac_sha256
+      end
+
       private
       def compute_authenticator(message, authenticator)
         NaCl.crypto_auth_hmacsha256(authenticator, message, message.bytesize, key)

data/lib/rbnacl/hmac/sha512256.rb

@@ -18,6 +18,13 @@ module Crypto
 
       # Number of bytes in a valid authenticator
       BYTES = NaCl::HMACSHA512256_BYTES
+      
+      # The crypto primitive for the HMAC::SHA512256 class
+      #
+      # @return [Symbol] The primitive used
+      def self.primitive
+        :hmac_sha512256
+      end
 
       private
       def compute_authenticator(message, authenticator)

data/lib/rbnacl/keys/private_key.rb

@@ -14,7 +14,7 @@ module Crypto
     include Serializable
 
     # The size of the key, in bytes
-    BYTES = Crypto::NaCl::SECRETKEYBYTES
+    BYTES = NaCl::CURVE25519_XSALSA20_POLY1305_SECRETKEY_BYTES
 
     # Initializes a new PrivateKey for key operations.
     #
@@ -39,9 +39,9 @@ module Crypto
     #
     # @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")
+      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")
       new(sk)
     end
 
@@ -58,5 +58,20 @@ module Crypto
     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
+    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/public_key.rb

@@ -9,7 +9,7 @@ module Crypto
     include Serializable
 
     # The size of the key, in bytes
-    BYTES = Crypto::NaCl::PUBLICKEYBYTES
+    BYTES = NaCl::CURVE25519_XSALSA20_POLY1305_PUBLICKEY_BYTES
 
     # Initializes a new PublicKey for key operations.
     #
@@ -34,5 +34,19 @@ module Crypto
     def to_bytes
       @public_key
     end
+
+    # The crypto primitive the PublicKey class is to be used for
+    #
+    # @return [Symbol] The primitive
+    def self.primitive
+      :curve25519_xsalsa20_poly1305
+    end
+
+    # The crypto primitive this PublicKey is to be used for.
+    #
+    # @return [Symbol] The primitive
+    def primitive
+      self.class.primitive
+    end
   end
 end

data/lib/rbnacl/keys/signing_key.rb

@@ -27,7 +27,7 @@ module Crypto
     #
     # @return [Crypto::SigningKey] Freshly-generated random SigningKey
     def self.generate
-      new Crypto::Random.random_bytes(NaCl::SECRETKEYBYTES)
+      new Crypto::Random.random_bytes(NaCl::ED25519_SEED_BYTES)
     end
 
     # Create a SigningKey from a seed value
@@ -39,12 +39,12 @@ module Crypto
     def initialize(seed, encoding = :raw)
       seed = Encoder[encoding].decode(seed)
 
-      Util.check_length(seed, NaCl::SECRETKEYBYTES, "seed")
+      Util.check_length(seed, NaCl::ED25519_SEED_BYTES, "seed")
 
-      pk = Util.zeros(NaCl::PUBLICKEYBYTES)
-      sk = Util.zeros(NaCl::SECRETKEYBYTES * 2)
+      pk = Util.zeros(NaCl::ED25519_VERIFYKEY_BYTES)
+      sk = Util.zeros(NaCl::ED25519_SIGNINGKEY_BYTES)
 
-      NaCl.crypto_sign_seed_keypair(pk, sk, seed) || raise(CryptoError, "Failed to generate a key pair")
+      NaCl.crypto_sign_ed25519_seed_keypair(pk, sk, seed) || raise(CryptoError, "Failed to generate a key pair")
 
       @seed, @signing_key = seed, sk
       @verify_key = VerifyKey.new(pk)
@@ -55,14 +55,14 @@ module Crypto
     # @param message [String] Message to be signed by this key
     # @param encoding [Symbol] Encode signature in the given format
     #
-    # @return [String] Signature as bytes 
+    # @return [String] Signature as bytes
     def sign(message, encoding = :raw)
-      buffer = Util.prepend_zeros(NaCl::SIGNATUREBYTES, message)
+      buffer = Util.prepend_zeros(signature_bytes, message)
       buffer_len = Util.zeros(FFI::Type::LONG_LONG.size)
 
-      NaCl.crypto_sign(buffer, buffer_len, message, message.bytesize, @signing_key)
+      NaCl.crypto_sign_ed25519(buffer, buffer_len, message, message.bytesize, @signing_key)
 
-      signature = buffer[0, NaCl::SIGNATUREBYTES]
+      signature = buffer[0, signature_bytes]
       Encoder[encoding].encode(signature)
     end
 
@@ -70,5 +70,26 @@ module Crypto
     #
     # @return [String] seed used to create this key
     def to_bytes; @seed; end
+
+    # The crypto primitive the SigningKey class uses for signatures
+    #
+    # @return [Symbol] The primitive
+    def self.primitive; :ed25519; end
+
+    # The crypto primitive this SigningKey class uses for signatures
+    #
+    # @return [Symbol] The primitive
+    def primitive; self.class.primitive; end
+
+    # The size of signatures generated by the SigningKey class
+    #
+    # @return [Integer] The number of bytes in a signature
+    def self.signature_bytes; NaCl::ED25519_SIGNATUREBYTES; end
+
+    # The size of signatures generated by the SigningKey instance
+    #
+    # @return [Integer] The number of bytes in a signature
+    def signature_bytes; NaCl::ED25519_SIGNATUREBYTES; end
+
   end
 end