sandal 0.4.0 → 0.5.0

data/lib/sandal/enc/acbc_hs.rb

@@ -1,103 +1,148 @@
-require 'openssl'
-require 'sandal/util'
+require "openssl"
+require "sandal/util"
 
 module Sandal
   module Enc
 
-    # Base implementation of the AES/CBC+HMAC-SHA family of encryption 
-    # algorithms.
+    # Base implementation of the A*CBC-HS* family of encryption methods.
     class ACBC_HS
       include Sandal::Util
 
-      # The JWA name of the encryption.
+      # The JWA name of the encryption method.
       attr_reader :name
 
       # The JWA algorithm used to encrypt the content master key.
       attr_reader :alg
 
-      # Creates a new instance; it's probably easier to use one of the subclass 
-      # constructors.
+      # Initialises a new instance; it's probably easier to use one of the subclass constructors.
       #
-      # @param aes_size [Integer] The size of the AES algorithm.
-      # @param sha_size [Integer] The size of the SHA algorithm.
-      # @param alg [#name, #encrypt_cmk, #decrypt_cmk] The algorithm to use to 
-      #   encrypt and/or decrypt the AES key.
-      def initialize(aes_size, sha_size, alg)
+      # @param name [String] The JWA name of the encryption method.
+      # @param aes_size [Integer] The size of the AES algorithm, in bits.
+      # @param sha_size [Integer] The size of the SHA algorithm, in bits.
+      # @param alg [#name, #encrypt_key, #decrypt_key] The algorithm to use to encrypt and/or decrypt the AES key.
+      def initialize(name, aes_size, sha_size, alg)
+        @name = name
         @aes_size = aes_size
         @sha_size = sha_size
-        @name = "A#{aes_size}CBC+HS#{@sha_size}"
         @cipher_name = "aes-#{aes_size}-cbc"
         @alg = alg
         @digest = OpenSSL::Digest.new("sha#{@sha_size}")
       end
 
+      # Encrypts a token payload.
+      #
+      # @param header [String] The header string.
+      # @param payload [String] The payload.
+      # @return [String] An encrypted JSON Web Token.
       def encrypt(header, payload)
-        cipher = OpenSSL::Cipher.new(@cipher_name).encrypt
-        cmk = @alg.respond_to?(:cmk) ? @alg.cmk : cipher.random_key
-        encrypted_key = @alg.encrypt_cmk(cmk)
+        key = get_encryption_key
+        mac_key, enc_key = derive_keys(key)
+        encrypted_key = @alg.encrypt_key(key)
 
-        cipher.key = derive_encryption_key(cmk) 
-        iv = cipher.random_iv
+        cipher = OpenSSL::Cipher.new(@cipher_name).encrypt
+        cipher.key = enc_key
+        cipher.iv = iv = SecureRandom.random_bytes(16)
         ciphertext = cipher.update(payload) + cipher.final
 
-        sec_parts = [MultiJson.dump(header), encrypted_key, iv, ciphertext]
-        sec_input = sec_parts.map { |part| jwt_base64_encode(part) }.join('.')
-        cik = derive_integrity_key(cmk)
-        integrity_value = compute_integrity_value(cik, sec_input)
+        auth_data = jwt_base64_encode(header)
+        auth_data_length = [auth_data.length * 8].pack("Q>")
+        mac_input = [auth_data, iv, ciphertext, auth_data_length].join
+        mac = OpenSSL::HMAC.digest(@digest, mac_key, mac_input)
+        auth_tag = mac[0...(mac.length / 2)]
 
-        sec_input << '.' << jwt_base64_encode(integrity_value)
+        remainder = [encrypted_key, iv, ciphertext, auth_tag].map { |part| jwt_base64_encode(part) }
+        [auth_data, *remainder].join(".")
       end
 
-      def decrypt(parts, decoded_parts)
-        cmk = @alg.decrypt_cmk(decoded_parts[1])
-        
-        cik = derive_integrity_key(cmk)
-        integrity_value = compute_integrity_value(cik, parts.take(4).join('.'))
-        unless jwt_strings_equal?(decoded_parts[4], integrity_value)
-          raise Sandal::TokenError, 'Invalid integrity value.'
+      # Decrypts an encrypted JSON Web Token.
+      #
+      # @param token [String or Array] The token, or token parts, to decrypt.
+      # @return [String] The token payload.
+      def decrypt(token)
+        parts, decoded_parts = Sandal::Enc.token_parts(token)
+        header, encrypted_key, iv, ciphertext, auth_tag = *decoded_parts
+
+        key = @alg.decrypt_key(encrypted_key)
+        mac_key, enc_key = derive_keys(key)
+
+        auth_data = parts[0]
+        auth_data_length = [auth_data.length * 8].pack("Q>")
+        mac_input = [auth_data, iv, ciphertext, auth_data_length].join
+        mac = OpenSSL::HMAC.digest(@digest, mac_key, mac_input)
+        unless auth_tag == mac[0...(mac.length / 2)]
+          raise Sandal::InvalidTokenError, "Invalid authentication tag."
         end
 
         cipher = OpenSSL::Cipher.new(@cipher_name).decrypt
         begin
-          cipher.key = derive_encryption_key(cmk)
+          cipher.key = enc_key
           cipher.iv = decoded_parts[2]
           cipher.update(decoded_parts[3]) + cipher.final
-        rescue OpenSSL::Cipher::CipherError
-          raise Sandal::TokenError, 'Invalid token.'
+        rescue OpenSSL::Cipher::CipherError => e
+          raise Sandal::InvalidTokenError, "Cannot decrypt token: #{e.message}"
         end
       end
 
-    private
-
-      # Computes the integrity value.
-      def compute_integrity_value(cik, sec_input)
-        OpenSSL::HMAC.digest(@digest, cik, sec_input)
-      end
-
-      # Derives the content encryption key from the content master key.
-      def derive_encryption_key(cmk)
-        Sandal::Enc.concat_kdf(@digest, cmk, @aes_size, @name, 0, 0, 'Encryption')
+      private
+
+      # Gets the key to use for mac and encryption
+      def get_encryption_key
+        key_bytes = @sha_size / 8
+        if @alg.respond_to?(:preshared_key)
+          key = @alg.preshared_key
+          unless key.size == key_bytes
+            raise Sandal::KeyError, "The pre-shared content key must be #{@sha_size} bits."
+          end
+          key
+        else
+          SecureRandom.random_bytes(key_bytes)
+        end
       end
 
-      # Derives the content integrity key from the content master key.
-      def derive_integrity_key(cmk)
-        Sandal::Enc.concat_kdf(@digest, cmk, @sha_size, @name, 0, 0, 'Integrity')
+      # Derives the mac key and encryption key
+      def derive_keys(key)
+        derived_key_size = key.size / 2
+        mac_key = key[0...derived_key_size]
+        enc_key = key[derived_key_size..-1]
+        return mac_key, enc_key
       end
 
     end
 
-    # The AES-128-CBC+HMAC-SHA256 encryption algorithm.
+    # The A128CBC-HS256 encryption method.
     class A128CBC_HS256 < Sandal::Enc::ACBC_HS
-      def initialize(key)
-        super(128, 256, key)
+
+      # The JWA name of the algorithm.
+      NAME = "A128CBC-HS256"
+
+      # The size of key that is required, in bits.
+      KEY_SIZE = 256
+
+      # Initialises a new instance.
+      #
+      # @param alg [#name, #encrypt_key, #decrypt_key] The algorithm to use to encrypt and/or decrypt the AES key.
+      def initialize(alg)
+        super(NAME, KEY_SIZE / 2, KEY_SIZE, alg)
       end
+
     end
 
-    # The AES-256-CBC+HMAC-SHA512 encryption algorithm.
+    # The A256CBC-HS512 encryption method.
     class A256CBC_HS512 < Sandal::Enc::ACBC_HS
-      def initialize(key)
-        super(256, 512, key)
+
+      # The JWA name of the algorithm.
+      NAME = "A256CBC-HS512"
+
+      # The size of key that is required, in bits.
+      KEY_SIZE = 512
+
+      # Initialises a new instance.
+      #
+      # @param alg [#name, #encrypt_key, #decrypt_key] The algorithm to use to encrypt and/or decrypt the AES key.
+      def initialize(alg)
+        super(NAME, KEY_SIZE / 2, KEY_SIZE, alg)
       end
+
     end
 
   end

data/lib/sandal/enc/agcm.rb

@@ -1,71 +1,109 @@
-require 'openssl'
-require 'sandal/util'
+require "openssl"
+require "sandal/util"
 
 module Sandal
   module Enc
 
-    # Base implementation of the AES/GCM family of encryption algorithms.
+    # Base implementation of the A*GCM family of encryption methods.
     class AGCM
       include Sandal::Util
 
-      # The JWA name of the encryption.
+      @@iv_size = 96
+      @@auth_tag_size = 128
+
+      # The JWA name of the encryption method.
       attr_reader :name
 
-      # The JWA algorithm used to encrypt the content master key.
+      # The JWA algorithm used to encrypt the content encryption key.
       attr_reader :alg
 
-      def initialize(aes_size, alg)
+      # Initialises a new instance; it's probably easier to use one of the subclass constructors.
+      #
+      # @param aes_size [Integer] The size of the AES algorithm, in bits.
+      # @param alg [#name, #encrypt_key, #decrypt_key] The algorithm to use to encrypt and/or decrypt the AES key.
+      def initialize(name, aes_size, alg)
+        @name = name
         @aes_size = aes_size
-        @name = "A#{aes_size}GCM"
         @cipher_name = "aes-#{aes_size}-gcm"
         @alg = alg
       end
 
+      # Encrypts a token payload.
+      #
+      # @param header [String] The header string.
+      # @param payload [String] The payload.
+      # @return [String] An encrypted JSON Web Token.
       def encrypt(header, payload)
         cipher = OpenSSL::Cipher.new(@cipher_name).encrypt
-        cmk = @alg.respond_to?(:cmk) ? @alg.cmk : cipher.random_key
-        encrypted_key = @alg.encrypt_cmk(cmk)
+        key = @alg.respond_to?(:preshared_key) ? @alg.preshared_key : cipher.random_key
+        encrypted_key = @alg.encrypt_key(key)
 
-        cipher.key = cmk
-        iv = cipher.random_iv
+        cipher.key = key
+        cipher.iv = iv = SecureRandom.random_bytes(@@iv_size / 8)
 
-        auth_parts = [MultiJson.dump(header), encrypted_key, iv]
-        auth_data = auth_parts.map { |part| jwt_base64_encode(part) }.join('.')
+        auth_data = jwt_base64_encode(header)
         cipher.auth_data  = auth_data
 
         ciphertext = cipher.update(payload) + cipher.final
-        remaining_parts = [ciphertext, cipher.auth_tag]
+        remaining_parts = [encrypted_key, iv, ciphertext, cipher.auth_tag(@@auth_tag_size / 8)]
         remaining_parts.map! { |part| jwt_base64_encode(part) }
-        [auth_data, *remaining_parts].join('.')
+        [auth_data, *remaining_parts].join(".")
       end
 
-      def decrypt(parts, decoded_parts)
+      # Decrypts an encrypted JSON Web Token.
+      #
+      # @param token [String or Array] The token, or token parts, to decrypt.
+      # @return [String] The token payload.
+      def decrypt(token)
+        parts, decoded_parts = Sandal::Enc.token_parts(token)
         cipher = OpenSSL::Cipher.new(@cipher_name).decrypt
         begin
-          cipher.key = @alg.decrypt_cmk(decoded_parts[1])
+          cipher.key = @alg.decrypt_key(decoded_parts[1])
           cipher.iv = decoded_parts[2]
           cipher.auth_tag = decoded_parts[4]
-          cipher.auth_data = parts.take(3).join('.')
+          cipher.auth_data = parts[0]
           cipher.update(decoded_parts[3]) + cipher.final
-        rescue OpenSSL::Cipher::CipherError
-          raise Sandal::TokenError, 'Invalid token.'
+        rescue OpenSSL::Cipher::CipherError => e
+          raise Sandal::InvalidTokenError, "Cannot decrypt token: #{e.message}"
         end
       end
 
     end
 
-    # The AES-128-GCM encryption algorithm.
+    # The A128GCM encryption method.
     class A128GCM < Sandal::Enc::AGCM
-      def initialize(key)
-        super(128, key)
+
+      # The JWA name of the algorithm.
+      NAME = "A128GCM"
+
+      # The size of key that is required, in bits.
+      KEY_SIZE = 128
+
+      # Initialises a new instance.
+      #
+      # @param alg [#name, #encrypt_key, #decrypt_key] The algorithm to use to encrypt and/or decrypt the AES key.
+      def initialize(alg)
+        super(NAME, KEY_SIZE, alg)
       end
+
     end
 
-    # The AES-256-GCM encryption algorithm.
+    # The A256GCM encryption method.
     class A256GCM < Sandal::Enc::AGCM
-      def initialize(key)
-        super(256, key)
+
+      # The JWA name of the algorithm.
+      NAME = "A256GCM"
+
+      # The size of key that is required, in bits.
+      KEY_SIZE = 256
+
+      # Initialises a new instance.
+      #
+      # @param alg [#name, #encrypt_key, #decrypt_key] The algorithm to use to encrypt and/or decrypt the AES key.
+      def initialize(alg)
+        super(NAME, KEY_SIZE, alg)
       end
+
     end
 
   end

data/lib/sandal/enc/alg.rb

@@ -6,6 +6,5 @@ module Sandal
   end
 end
 
-require 'sandal/enc/alg/direct'
-require 'sandal/enc/alg/rsa1_5'
-require 'sandal/enc/alg/rsa_oaep'
+require "sandal/enc/alg/direct"
+require "sandal/enc/alg/rsa"

data/lib/sandal/enc/alg/direct.rb

@@ -1,46 +1,48 @@
-require 'openssl'
+require "openssl"
 
 module Sandal
   module Enc
     module Alg
 
-      # The direct ("dir") key encryption mechanism, which uses a pre-shared 
-      # content master key.
+      # The direct ("dir") key encryption algorithm, which uses a pre-shared symmetric key.
       class Direct
 
-        # @return [String] The JWA name of the algorithm.
-        attr_reader :name
+        # The JWA name of the algorithm.
+        NAME = "dir"
 
-        # @return [String] The pre-shared content master key key.
-        attr_reader :cmk
+        # @return [String] The pre-shared symmetric key.
+        attr_reader :preshared_key
 
-        # Creates a new instance.
+        # Initialises a new instance.
         #
-        # @param cmk [String] The pre-shared content master key.
-        def initialize(cmk)
-          @name = 'dir'
-          @cmk = cmk
+        # @param preshared_key [String] The pre-shared symmetric key.
+        def initialize(preshared_key)
+          @preshared_key = preshared_key
         end
 
-        # Returns an empty string as the content master key is not included in 
-        # the JWE token.
+        # The JWA name of the algorithm.
+        def name
+          NAME
+        end
+
+        # Returns an empty string as the key is not included in JWE tokens using direct key exchange.
         #
-        # @param cmk [String] This parameter is ignored.
+        # @param key [String] This parameter is ignored.
         # @return [String] An empty string.
-        def encrypt_cmk(cmk)
-          ''
+        def encrypt_key(key)
+          ""
         end
 
-        # Returns the pre-shared content master key.
+        # Returns the pre-shared content key.
         #
-        # @param encrypted_cmk [String] The encrypted content master key.
-        # @return [String] The pre-shared content master key.
-        # @raise [Sandal::TokenError] encrypted_cmk is not nil or empty.
-        def decrypt_cmk(encrypted_cmk)
-          unless encrypted_cmk.nil? || encrypted_cmk.empty?
-            raise Sandal::TokenError, 'Token must not include encrypted CMK.' 
+        # @param encrypted_key [String] The encrypted key.
+        # @return [String] The pre-shared symmetric key.
+        # @raise [Sandal::InvalidTokenError] encrypted_key is not nil or empty.
+        def decrypt_key(encrypted_key)
+          unless encrypted_key.nil? || encrypted_key.empty?
+            raise Sandal::InvalidTokenError, "Tokens using direct key exchange must not include a content key."
           end
-          @cmk
+          @preshared_key
         end
 
       end

data/lib/sandal/enc/alg/rsa.rb

@@ -0,0 +1,82 @@
+require "openssl"
+
+module Sandal
+  module Enc
+    module Alg
+
+      # Base class for RSA key encryption algorithm.
+      class RSA
+
+        # The JWA name of the algorithm.
+        attr_reader :name
+
+        # Initialises a new instance.
+        #
+        # @param name [String] The JWA name of the algorithm.
+        # @param rsa_key [OpenSSL::PKey::RSA or String] The RSA key to use for key encryption (public) or decryption 
+        # (private). If the value is a String then it will be passed to the constructor of the RSA class. This must 
+        # be at least 2048 bits to be compliant with the JWA specification.
+        def initialize(name, rsa_key, padding)
+          @name = name
+          @rsa_key = rsa_key.is_a?(String) ? OpenSSL::PKey::RSA.new(rsa_key) : rsa_key
+          @padding = padding
+        end
+
+        # Encrypts the content key.
+        #
+        # @param key [String] The content key.
+        # @return [String] The encrypted content key.
+        def encrypt_key(key)
+          @rsa_key.public_encrypt(key, @padding)
+        end
+
+        # Decrypts the content key.
+        #
+        # @param encrypted_key [String] The encrypted content key.
+        # @return [String] The pre-shared content key.
+        # @raise [Sandal::TokenError] The content key can't be decrypted.
+        def decrypt_key(encrypted_key)
+          @rsa_key.private_decrypt(encrypted_key, @padding)
+        rescue => e
+          raise Sandal::InvalidTokenError, "Cannot decrypt content key: #{e.message}"
+        end
+
+      end
+
+      # The RSA1_5 key encryption algorithm.
+      class RSA1_5 < RSA
+
+        # The JWA name of the algorithm.
+        NAME = "RSA1_5"
+
+        # Initialises a new instance.
+        #
+        # @param rsa_key [OpenSSL::PKey::RSA or String] The RSA key to use for key encryption (public) or decryption 
+        # (private). If the value is a String then it will be passed to the constructor of the RSA class. This must 
+        # be at least 2048 bits to be compliant with the JWA specification.
+        def initialize(rsa_key)
+          super(NAME, rsa_key, OpenSSL::PKey::RSA::PKCS1_PADDING)
+        end
+
+      end
+
+      # The RSA-OAEP key encryption algorithm.
+      class RSA_OAEP < RSA
+
+        # The JWA name of the algorithm.
+        NAME = "RSA-OAEP"
+
+        # Initialises a new instance.
+        #
+        # @param rsa_key [OpenSSL::PKey::RSA or String] The RSA key to use for key encryption (public) or decryption 
+        # (private). If the value is a String then it will be passed to the constructor of the RSA class. This must 
+        # be at least 2048 bits to be compliant with the JWA specification.
+        def initialize(rsa_key)
+          super(NAME, rsa_key, OpenSSL::PKey::RSA::PKCS1_OAEP_PADDING)
+        end
+
+      end
+      
+    end
+  end
+end