sandal 0.0.2 → 0.0.3

data/lib/sandal.rb

@@ -11,37 +11,49 @@ require 'sandal/enc'
 # A library for creating and reading JSON Web Tokens (JWT).
 module Sandal
 
-  # Creates a signed token.
-  def self.encode_token(payload, sig, header_fields = nil)
+  # Creates a signed JSON Web Token.
+  #
+  # @param payload [String] The payload of the token.
+  # @param signer [Sandal::Sig] The token signer, which may be nil for an unsigned token.
+  # @param header_fields [Hash] Header fields for the token (note: do not include 'alg').
+  # @return [String] A signed JSON Web Token.
+  def self.encode_token(payload, signer, header_fields = nil)
     if header_fields && header_fields['enc']
       throw ArgumentError.new('The header cannot contain an "enc" parameter.')
     end
-    sig ||= Sandal::Sig::None.instance
+    signer ||= Sandal::Sig::None.instance
 
     header = {}
-    header['alg'] = sig.name if sig.name != Sandal::Sig::None.instance.name
+    header['alg'] = signer.name if signer.name != Sandal::Sig::None.instance.name
     header = header_fields.merge(header) if header_fields
 
     encoded_header = Sandal::Util.base64_encode(JSON.generate(header))
     encoded_payload = Sandal::Util.base64_encode(payload)
     secured_input = [encoded_header, encoded_payload].join('.')
 
-    signature = sig.sign(secured_input)
+    signature = signer.sign(secured_input)
     encoded_signature = Sandal::Util.base64_encode(signature)
     [secured_input, encoded_signature].join('.')
   end
 
-  # Creates an encrypted token.
-  def self.encrypt_token(payload, enc, header_fields = nil)
+  # Creates an encrypted JSON Web Token.
+  #
+  # @param payload [String] The payload of the token.
+  # @param encrypted [Sandal::Enc] The token encrypter.
+  # @param header_fields [Hash] Header fields for the token (note: do not include 'alg' or 'enc').
+  # @return [String] An encrypted JSON Web Token.
+  def self.encrypt_token(payload, encrypter, header_fields = nil)
     header = {}
-    header['enc'] = enc.name
-    header['alg'] = enc.alg_name
+    header['enc'] = encrypter.name
+    header['alg'] = encrypter.alg_name
     header = header_fields.merge(header) if header_fields
 
-    enc.encrypt(header, payload)
+    encrypter.encrypt(header, payload)
   end
 
-  # Decodes a token, verifying the signature if present.
+  # Decodes a JSON Web Token, verifying the signature as necessary.
+  #
+  # **NOTE: This method is likely to change, to allow more validation options**
   def self.decode_token(token, &sig_finder)
     parts = token.split('.')
     throw ArgumentError.new('Invalid token format.') unless [2, 3].include?(parts.length)
@@ -65,7 +77,9 @@ module Sandal
     payload
   end
 
-  # Decrypts a token.
+  # Decrypts an encrypted JSON Web Token.
+  #
+  # **NOTE: This method is likely to change, to allow more validation options**
   def self.decrypt_token(encrypted_token, &enc_finder)
     parts = encrypted_token.split('.')
     throw ArgumentError.new('Invalid token format.') unless parts.length == 5

data/lib/sandal/sig.rb

@@ -4,15 +4,22 @@ module Sandal
   # Common signature traits.
   module Sig
 
-    # The JWA name of the algorithm.
+    # @return [String] The JWA name of the algorithm.
     attr_reader :name
 
     # Signs a payload and returns the signature.
+    #
+    # @param payload [String] The payload of the token to sign.
+    # @return [String] The signature.
     def sign(payload)
       throw NotImplementedError.new("#{@name}.sign is not implemented.")
     end
 
     # Verifies a payload signature and returns whether the signature matches.
+    #
+    # @param signature [String] The signature to verify.
+    # @param payload [String] The payload of the token.
+    # @return [Boolean] true if the signature is correct; otherwise false.
     def verify(signature, payload)
       throw NotImplementedError.new("#{@name}.verify is not implemented.")
     end
@@ -28,11 +35,18 @@ module Sandal
       end
 
       # Returns an empty signature.
+      #
+      # @param payload [String] This parameter is ignored.
+      # @return [String] An empty string.
       def sign(payload)
         ''
       end
 
-      # Verifies that the signature is empty.
+      # Verifies that a signature is nil or empty.
+      #
+      # @param signature [String] The signature to verify.
+      # @param payload [String] This parameter is ignored.
+      # @return [Boolean] `true` if the signature is nil or empty; otherwise `false`.
       def verify(signature, payload)
         signature.nil? || signature.length == 0
       end

data/lib/sandal/sig/es.rb

@@ -8,10 +8,11 @@ module Sandal
       include Sandal::Sig
 
       # Creates a new instance with the size of the SHA algorithm and an OpenSSL ES PKey.
-      def initialize(sha_size, key)
+      def initialize(sha_size, prime_size, key)
         throw ArgumentError.new('A key is required.') unless key
         @name = "ES#{sha_size}"
         @digest = OpenSSL::Digest.new("sha#{sha_size}")
+        @prime_size = prime_size
         @key = key
       end
 
@@ -20,7 +21,7 @@ module Sandal
         hash = @digest.digest(payload)
         asn1_sig = @key.dsa_sign_asn1(hash)
         r, s = self.class.decode_asn1_signature(asn1_sig)
-        self.class.encode_jws_signature(r, s)
+        self.class.encode_jws_signature(r, s, @prime_size)
       end
 
       # Verifies a payload signature and returns whether the signature matches.
@@ -45,22 +46,18 @@ module Sandal
 
       # Decodes a JWS signature into a pair of BNs.
       def self.decode_jws_signature(signature)
-        binary_string = Sandal::Util.base64_decode(signature)
-        coord_length = binary_string.length / 2
-        r = OpenSSL::BN.new(binary_string[0..(coord_length - 1)].unpack('H*')[0], 16)
-        s = OpenSSL::BN.new(binary_string[coord_length..-1].unpack('H*')[0], 16)
+        n_length = signature.length / 2
+        s_to_n = lambda { |s| OpenSSL::BN.new(s.unpack('H*')[0], 16) }
+        r = s_to_n.call(signature[0..(n_length - 1)])
+        s = s_to_n.call(signature[n_length..-1])
         return r, s
       end
 
       # Encodes a pair of BNs into a JWS signature.
-      def self.encode_jws_signature(r, s)
-        # TODO: Is there a better way to convert these to a binary string?
-        r_str = [r.to_s(16)].pack('H*')
-        r_str = "\x00" + r_str if r_str.length % 2 != 0
-        s_str = [s.to_s(16)].pack('H*')
-        s_str = "\x00" + s_str if s_str.length % 2 != 0
-        binary_string = r_str + s_str
-        Sandal::Util.base64_encode(binary_string)
+      def self.encode_jws_signature(r, s, prime_size)
+        byte_count = (prime_size / 8.0).ceil
+        n_to_s = lambda { |n| [n.to_s(16)].pack('H*').rjust(byte_count, "\0") }
+        n_to_s.call(r) + n_to_s.call(s)
       end
 
     end
@@ -69,7 +66,7 @@ module Sandal
     class ES256 < Sandal::Sig::ES
       # Creates a new instance with an OpenSSL ES PKey.
       def initialize(key)
-        super(256, key)
+        super(256, 256, key)
       end
     end
 
@@ -77,7 +74,7 @@ module Sandal
     class ES384 < Sandal::Sig::ES
       # Creates a new instance with an OpenSSL ES PKey.
       def initialize(key)
-        super(384, key)
+        super(384, 384, key)
       end
     end
 
@@ -85,7 +82,7 @@ module Sandal
     class ES512 < Sandal::Sig::ES
       # Creates a new instance with an OpenSSL ES PKey.
       def initialize(key)
-        super(512, key)
+        super(512, 521, key)
       end
     end
 

data/lib/sandal/version.rb

@@ -1,4 +1,4 @@
 module Sandal
   # The semantic version of the library.
-  VERSION = '0.0.2'
+  VERSION = '0.0.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sandal
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-26 00:00:00.000000000 Z
+date: 2013-03-29 00:00:00.000000000 Z
 dependencies: []
 description: A ruby library for creating and reading JSON Web Tokens (JWT), supporting
   JSON Web Signatures (JWS) and JSON Web Encryption (JWE).
@@ -55,3 +55,4 @@ signing_key:
 specification_version: 3
 summary: A JSON Web Token (JWT) library.
 test_files: []
+has_rdoc: