sandal 0.0.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NjVlMDRhMzgyZTY4OTkyMDZjZmUwNDY2ZGY3YjY4NTdiZWY0NDFjZA==
+  data.tar.gz: !binary |-
+    MjE1N2ZmZmQxMjI1YmEzYzQ4YzJiMGY5MjliOWQ0NDU0NmYzZWM2Mw==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    YjU2ZWEwYWU5NDc2MzliNmQwNjExMDdmYTU2ZTc4OGRlZWQ3ZWE4ODAxZmE1
+    MzJkMWJlMzQzZjQ2ZDg4MGY1YTlmZThkZDE5MmUzZTBmMTQ2NjQ1OWFkZTJm
+    MDkzYTY3NGQwNDFmNjlkMGQ4ODliOWFlMjg4MTA3MDAyNWNhMGY=
+  data.tar.gz: !binary |-
+    NzRiZjIwYjg2OGUwOWZlZmY3MTAxY2U3ZWFmMjI5NjZiM2U1ODFlMjBlNDA0
+    Y2M4NzI2M2IyMGU2ODUyYWE1MTEzYTczMTc5YjM2Yzg1N2IxNWNlYjFlYzk1
+    MmFlMjkxZmU2ODRkNTUxMGZkODNlNWY1ZDQyMDQ1MGUwMmVkNzI=

data/lib/sandal/enc/aescbc.rb

@@ -0,0 +1,78 @@
+require 'openssl'
+require 'sandal/util'
+
+module Sandal
+  module Enc
+
+    # Base implementation of the AES/CBC family of encryption algorithms.
+    class AESCBC
+      include Sandal::Enc
+
+      def initialize(aes_size, key)
+        throw ArgumentError.new('A key is required.') unless key
+        @aes_size = aes_size
+        @sha_size = aes_size * 2 # TODO: Any smarter way to do this?
+        @name = "A#{aes_size}CBC+HS#{@sha_size}"
+        @alg_name = "RSA1_5" # TODO: From key?
+        @cipher_name = "AES-#{aes_size}-CBC"
+        @key = key
+        @digest = OpenSSL::Digest.new("SHA#{@sha_size}")
+      end
+
+      def encrypt(header, payload)
+        cipher = OpenSSL::Cipher.new(@cipher_name).encrypt
+        content_master_key = cipher.random_key # TODO: Check with the spec if this is long enough
+        iv = cipher.random_iv
+
+        # TODO: Need to think about how this works with pre-shared symmetric keys - I'd originally thought
+        # this wouldn't be a common use case, but in cases where the recipient is also the issuer (e.g.
+        # an OAuth refresh token) then it would make a lot of sense.
+        encrypted_key = @key.public_encrypt(content_master_key)
+        encoded_encrypted_key = Sandal::Util.base64_encode(encrypted_key)
+        encoded_iv = Sandal::Util.base64_encode(iv)
+
+        cipher.key = derive_content_key('Encryption', content_master_key, @aes_size)
+        ciphertext = cipher.update(payload) + cipher.final
+        encoded_ciphertext = Sandal::Util.base64_encode(ciphertext)
+
+        encoded_header = Sandal::Util.base64_encode(JSON.generate(header))
+        secured_input = [encoded_header, encoded_encrypted_key, encoded_iv, encoded_ciphertext].join('.')
+        content_integrity_key = derive_content_key('Integrity', content_master_key, @sha_size)
+        integrity_value = OpenSSL::HMAC.digest(@digest, content_integrity_key, secured_input)
+        encoded_integrity_value = Sandal::Util.base64_encode(integrity_value)
+
+        [secured_input, encoded_integrity_value].join('.')
+      end
+
+      private
+
+      # Derives content keys using the Concat KDF.
+      def derive_content_key(label, content_master_key, size)
+        round_number = [1].pack('N')
+        output_size = [size].pack('N')
+        enc_bytes = @name.encode('utf-8').bytes.to_a.pack('C*')
+        epu = epv = [0].pack('N')
+        label_bytes = label.encode('us-ascii').bytes.to_a.pack('C*')
+        hash_input = round_number + content_master_key + output_size + enc_bytes + epu + epv + label_bytes
+        hash = @digest.digest(hash_input)
+        hash[0..((size / 8) - 1)]
+      end
+
+    end
+
+    # The AES-128-CBC encryption algorithm.
+    class AES128CBC < Sandal::Enc::AESCBC
+      def initialize(key)
+        super(128, key)
+      end
+    end
+
+    # The AES-256-CBC encryption algorithm.
+    class AES256CBC < Sandal::Enc::AESCBC
+      def initialize(key)
+        super(256, key)
+      end
+    end
+
+  end
+end

data/lib/sandal/enc.rb

@@ -0,0 +1,24 @@
+module Sandal
+  # Common encryption traits.
+  module Enc
+
+    # The JWA name of the encryption.
+    attr_reader :name
+
+    # The JWA name of the algorithm.
+    attr_reader :alg_name
+
+    # Encrypts a header and payload, and returns an encrypted token.
+    def encrypt(header, payload)
+      throw NotImplementedError.new("#{@name}.encrypt is not implemented.")
+    end
+
+    # Decrypts a token.
+    def decrypt(data)
+      throw NotImplementedError.new("#{@name}.decrypt is not implemented.")
+    end
+
+  end
+end
+
+require 'sandal/enc/aescbc'

data/lib/sandal/sig/hs.rb

@@ -0,0 +1,55 @@
+require 'openssl'
+
+module Sandal
+  module Sig
+
+    # Base implementation of the HMAC-SHA family of signature algorithms.
+    class HS
+      include Sandal::Sig
+
+      # Creates a new instance with the size of the SHA algorithm and a string key.
+      def initialize(sha_size, key)
+        throw ArgumentError.new('A key is required.') unless key
+        @name = "HS#{sha_size}"
+        @digest = OpenSSL::Digest.new("SHA#{sha_size}")
+        @key = key
+      end
+
+      # Signs a payload and returns the signature.
+      def sign(payload)
+        OpenSSL::HMAC.digest(@digest, @key, payload)
+      end
+
+      # Verifies a payload signature and returns whether the signature matches.
+      def verify(signature, payload)
+        Sandal::Util.secure_equals(sign(payload), signature)
+      end
+
+    end
+
+    # The HMAC-SHA256 signing algorithm.
+    class HS256 < Sandal::Sig::HS
+      # Creates a new instance with a string key.
+      def initialize(key)
+        super(256, key)
+      end
+    end
+
+    # The HMAC-SHA384 signing algorithm.
+    class HS384 < Sandal::Sig::HS
+      # Creates a new instance with a string key.
+      def initialize(key)
+        super(384, key)
+      end
+    end
+
+    # The HMAC-SHA512 signing algorithm.
+    class HS512 < Sandal::Sig::HS
+      # Creates a new instance with a string key.
+      def initialize(key)
+        super(512, key)
+      end
+    end
+
+  end
+end

data/lib/sandal/sig/rs.rb

@@ -0,0 +1,59 @@
+require 'openssl'
+
+module Sandal
+  module Sig
+
+    # Base implementation of the RSA-SHA family of signature algorithms.
+    class RS
+      include Sandal::Sig
+
+      # Creates a new instance with the size of the SHA algorithm and an OpenSSL RSA PKey. To sign
+      # a value this must contain a private key; to verify a signature a public key is sufficient.
+      # Note that the size of the RSA key must be at least 2048 bits to be compliant with the
+      # JWA specification.
+      def initialize(sha_size, key)
+        throw ArgumentError.new('A key is required.') unless key
+        @name = "RS#{sha_size}"
+        @digest = OpenSSL::Digest.new("SHA#{sha_size}")
+        @key = key
+      end
+
+      # Signs a payload and returns the signature.
+      def sign(payload)
+        throw ArgumentError.new('A private key is required to sign the payload.') unless @key.private?
+        @key.sign(@digest, payload)
+      end
+
+      # Verifies a payload signature and returns whether the signature matches.
+      def verify(signature, payload)
+        @key.verify(@digest, signature, payload)
+      end
+
+    end
+
+    # The RSA-SHA256 signing algorithm.
+    class RS256 < Sandal::Sig::RS
+      # Creates a new instance with an OpenSSL RSA PKey.
+      def initialize(key)
+        super(256, key)
+      end
+    end
+
+    # The RSA-SHA384 signing algorithm.
+    class RS384 < Sandal::Sig::RS
+      # Creates a new instance with an OpenSSL RSA PKey.
+      def initialize(key)
+        super(384, key)
+      end
+    end
+
+    # The RSA-SHA512 signing algorithm.
+    class RS512 < Sandal::Sig::RS
+      # Creates a new instance with an OpenSSL RSA PKey.
+      def initialize(key)
+        super(512, key)
+      end
+    end
+
+  end
+end

data/lib/sandal/sig.rb

@@ -0,0 +1,43 @@
+module Sandal
+  # Common signature traits.
+  module Sig
+
+    # The JWA name of the algorithm.
+    attr_reader :name
+
+    # Signs a payload and returns the signature.
+    def sign(payload)
+      throw NotImplementedError.new("#{@name}.sign is not implemented.")
+    end
+
+    # Verifies a payload signature and returns whether the signature matches.
+    def verify(signature, payload)
+      throw NotImplementedError.new("#{@name}.verify is not implemented.")
+    end
+
+    # The 'none' JWA signature method.
+    class None
+      include Sandal::Sig
+
+      # Creates a new instance.
+      def initialize
+        @name = 'none'
+      end
+
+      # Returns an empty signature.
+      def sign(payload)
+        ''
+      end
+
+      # Verifies that the signature is empty.
+      def verify(signature, payload)
+        signature.nil? || signature.length == 0
+      end
+
+    end
+
+  end
+end
+
+require 'sandal/sig/hs'
+require 'sandal/sig/rs'

data/lib/sandal/util.rb

@@ -0,0 +1,36 @@
+require 'base64'
+
+module Sandal
+  # Implements some JWT utility functions. Shouldn't be needed by most people but may
+  # be useful if you're developing an extension to the library.
+  module Util
+    
+    # A string equality function which doesn't short-circuit the equality check to help
+    # protect against timing attacks.
+    #--
+    # See http://rdist.root.org/2009/05/28/timing-attack-in-google-keyczar-library/
+    def self.secure_equals(a, b)
+      if a.nil? && b.nil?
+        true
+      elsif a.nil? || b.nil? || a.bytesize != b.bytesize
+        false
+      else
+        result = a.bytes.zip(b.bytes).reduce(0) { |memo, (b1, b2)| memo |= (b1 ^ b2) }
+        result == 0
+      end
+    end
+
+    # Base64 encodes a string, in compliance with the JWT specification.
+    def self.base64_encode(s)
+      Base64.urlsafe_encode64(s).gsub(%r{=+$}, '')
+    end
+
+    # Base64 decodes a string, in compliance with the JWT specification.
+    def self.base64_decode(s)
+      padding_length = (4 - (s.length % 4)) % 4
+      padding = '=' * padding_length
+      Base64.urlsafe_decode64(s + padding)
+    end
+
+  end
+end

data/lib/sandal/version.rb

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

data/lib/sandal.rb

@@ -0,0 +1,162 @@
+$:.unshift('.')
+
+require 'base64'
+require 'json'
+require 'openssl'
+
+require 'sandal/version'
+require 'sandal/sig'
+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)
+    if header_fields && header_fields['enc']
+      throw ArgumentError.new('The header cannot contain an "enc" parameter.')
+    end
+    sig ||= Sandal::Sig::None.new
+
+    header = {}
+    header['alg'] = sig.name if sig.name != 'none'
+    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)
+    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)
+    header = {}
+    header['enc'] = enc.name
+    header['alg'] = enc.alg_name
+    header = header_fields.merge(header) if header_fields
+
+    enc.encrypt(header, payload)
+  end
+
+  # Decodes a token, verifying the signature if present.
+  def self.decode_token(token, &sig_finder)
+    parts = token.split('.')
+    throw ArgumentError.new('Invalid token format.') unless [2, 3].include?(parts.length)
+    begin
+      header = JSON.parse(Sandal::Util.base64_decode(parts[0]))
+      payload = Sandal::Util.base64_decode(parts[1])
+      signature = if parts.length > 2 then Sandal::Util.base64_decode(parts[2]) else '' end
+    rescue
+      throw ArgumentError.new('Invalid token encoding.')
+    end
+
+    algorithm = header['alg']
+    if algorithm && algorithm != 'none'
+      throw SecurityError.new('The signature is missing.') unless signature.length > 0
+      sig = sig_finder.call(header)
+      throw SecurityError.new('No signature verifier was found.') unless sig
+      secured_input = parts.take(2).join('.')
+      throw ArgumentError.new('Invalid signature.') unless sig.verify(signature, secured_input)
+    end
+
+    payload
+  end
+
+  # Decrypts a token.
+  def self.decrypt_token(encrypted_token, &key_finder)
+    parts = encrypted_token.split('.')
+    throw ArgumentError.new('Invalid token format.') unless parts.length == 5
+    begin
+      header = JSON.parse(Sandal::Util.base64_decode(parts[0]))
+      encrypted_key = Sandal::Util.base64_decode(parts[1])
+      iv = Sandal::Util.base64_decode(parts[2])
+      ciphertext = Sandal::Util.base64_decode(parts[3])
+      integrity_value = Sandal::Util.base64_decode(parts[4])
+    rescue
+      throw ArgumentError.new('Invalid token encoding.')
+    end
+
+    algorithm = header['alg']
+    encryption = header['enc']
+    case encryption 
+    when 'A128CBC+HS256', 'A256CBC+HS512'
+      aes_length = Integer(encryption[1..3])
+      sha_length = Integer(encryption[-3..-1])
+
+      digest = OpenSSL::Digest.new("SHA#{sha_length}")
+
+      private_key = key_finder.call(header)
+      throw SecurityError.new('No key was found to decrypt the content master key.') unless private_key
+      content_master_key = private_key.private_decrypt(encrypted_key)
+
+      content_encryption_key = derive_content_key('Encryption', content_master_key, encryption, digest, aes_length)
+      content_integrity_key = derive_content_key('Integrity', content_master_key, encryption, digest, sha_length)
+
+      secured_input = parts.take(4).join('.')
+      computed_integrity_value = OpenSSL::HMAC.digest(digest, content_integrity_key, secured_input)
+      throw ArgumentError.new('Invalid signature.') unless integrity_value == computed_integrity_value
+
+      cipher = OpenSSL::Cipher.new("AES-#{aes_length}-CBC")
+      cipher.decrypt
+      cipher.key = content_encryption_key
+      cipher.iv = iv
+      cipher.update(ciphertext) + cipher.final
+    when 'A128GCM', 'A256GCM'
+      throw NotImplementedError.new("The GCM family of encryption algorithms are not implemented yet.")
+    else
+      throw NotImplementedError.new("The #{encryption} encryption algorithm is not supported.")
+    end
+  end
+
+  private  
+
+  # Derives content keys using the Concat KDF.
+  def self.derive_content_key(label, content_master_key, encryption, digest, size)
+    round_number = [1].pack('N')
+    output_size = [size].pack('N')
+    enc_bytes = encryption.encode('utf-8').bytes.to_a.pack('C*')
+    epu = epv = [0].pack('N')
+    label_bytes = label.encode('us-ascii').bytes.to_a.pack('C*')
+    hash_input = round_number + content_master_key + output_size + enc_bytes + epu + epv + label_bytes
+    hash = digest.digest(hash_input)
+    hash[0..((size / 8) - 1)]
+  end
+
+end
+
+if __FILE__ == $0
+
+  # create payload
+  issued_at = Time.now
+  claims = JSON.generate({
+    iss: 'example.org',
+    aud: 'example.com',
+    sub: 'user@example.org',
+    iat: issued_at.to_i,
+    exp: (issued_at + 3600).to_i
+  })
+
+  puts claims.to_s
+
+  # sign and encrypt
+  jws_key = OpenSSL::PKey::RSA.new(2048)
+  sig = Sandal::Sig::RS256.new(jws_key)
+  jws_token = Sandal.encode_token(claims.to_s, sig)
+
+  puts jws_token
+
+  jwe_key = OpenSSL::PKey::RSA.new(2048)
+  enc = Sandal::Enc::AES128CBC.new(jwe_key.public_key)
+  jwe_token = Sandal.encrypt_token(jws_token, enc, { 'cty' => 'JWT' })
+
+  puts jwe_token
+
+  jws_token_2 = Sandal.decrypt_token(jwe_token) { |header| jwe_key }
+  roundtrip_claims = Sandal.decode_token(jws_token_2) { |header| Sandal::Sig::RS256.new(jws_key.public_key) }
+
+  puts roundtrip_claims
+
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: sandal
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- Greg Beech
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-03-22 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).
+email:
+- greg@gregbeech.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/sandal/enc/aescbc.rb
+- lib/sandal/enc.rb
+- lib/sandal/sig/hs.rb
+- lib/sandal/sig/rs.rb
+- lib/sandal/sig.rb
+- lib/sandal/util.rb
+- lib/sandal/version.rb
+- lib/sandal.rb
+homepage: http://rubygems.org/gems/sandal
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: A JSON Web Token (JWT) library.
+test_files: []