jose 0.3.1 → 1.0.0

data/docs/SignatureAlgorithms.md

@@ -0,0 +1,35 @@
+# @title Signature Algorithms
+
+# Signature Algorithms
+
+The basic parameters for a {JOSE::JWS JOSE::JWS} header are:
+
+- `"alg"` **(required)** - Cryptographic Algorithm used to secure the JWS.
+
+See [RFC 7515](https://tools.ietf.org/html/rfc7515#section-4.1) for more information about other header parameters.
+
+### `alg` Header Parameter
+
+Here are the supported options for the `alg` parameter, grouped by similar funcionality:
+
+- Elliptic Curve Digital Signature Algorithm (ECDSA)
+  - [`ES256`](http://www.rubydoc.info/gems/jose/JOSE/JWS#ECDSA-group)
+  - [`ES384`](http://www.rubydoc.info/gems/jose/JOSE/JWS#ECDSA-group)
+  - [`ES512`](http://www.rubydoc.info/gems/jose/JOSE/JWS#ECDSA-group)
+- Edwards-curve Digital Signature Algorithm (EdDSA)
+  - [`Ed25519`](http://www.rubydoc.info/gems/jose/JOSE/JWS#EdDSA-25519-group)
+  - [`Ed25519ph`](http://www.rubydoc.info/gems/jose/JOSE/JWS#EdDSA-25519-group)
+  - [`Ed448`](http://www.rubydoc.info/gems/jose/JOSE/JWS#EdDSA-448-group)
+  - [`Ed448ph`](http://www.rubydoc.info/gems/jose/JOSE/JWS#EdDSA-448-group)
+- HMAC using SHA-2
+  - [`HS256`](http://www.rubydoc.info/gems/jose/JOSE/JWS#HMACSHA2-group)
+  - [`HS384`](http://www.rubydoc.info/gems/jose/JOSE/JWS#HMACSHA2-group)
+  - [`HS512`](http://www.rubydoc.info/gems/jose/JOSE/JWS#HMACSHA2-group)
+- RSASSA PSS using SHA-2 and MGF1 with SHA-2
+  - [`PS256`](http://www.rubydoc.info/gems/jose/JOSE/JWS#RSASSAPSS-group)
+  - [`PS384`](http://www.rubydoc.info/gems/jose/JOSE/JWS#RSASSAPSS-group)
+  - [`PS512`](http://www.rubydoc.info/gems/jose/JOSE/JWS#RSASSAPSS-group)
+- RSASSA PKCS#1.5 using SHA-2
+  - [`RS256`](http://www.rubydoc.info/gems/jose/JOSE/JWS#RSASSAPKCS1_5-group)
+  - [`RS384`](http://www.rubydoc.info/gems/jose/JOSE/JWS#RSASSAPKCS1_5-group)
+  - [`RS512`](http://www.rubydoc.info/gems/jose/JOSE/JWS#RSASSAPKCS1_5-group)

data/lib/jose.rb

@@ -6,68 +6,129 @@ require 'json'
 require 'openssl'
 require 'thread'
 
-module JOSE
-  class Map < Hamster::Hash; end
-end
-
+# JOSE stands for JSON Object Signing and Encryption which is a is a set of
+# standards established by the [JOSE Working Group](https://datatracker.ietf.org/wg/jose).
+#
+# JOSE is split into 5 main components:
+#
+#   * {JOSE::JWA JOSE::JWA} - JSON Web Algorithms (JWA) {https://tools.ietf.org/html/rfc7518 RFC 7518}
+#   * {JOSE::JWE JOSE::JWE} - JSON Web Encryption (JWE) {https://tools.ietf.org/html/rfc7516 RFC 7516}
+#   * {JOSE::JWK JOSE::JWK} - JSON Web Key (JWK)        {https://tools.ietf.org/html/rfc7517 RFC 7517}
+#   * {JOSE::JWS JOSE::JWS} - JSON Web Signature (JWS)  {https://tools.ietf.org/html/rfc7515 RFC 7515}
+#   * {JOSE::JWT JOSE::JWT} - JSON Web Token (JWT)      {https://tools.ietf.org/html/rfc7519 RFC 7519}
+#
+# Additional specifications and drafts implemented:
+#
+#   * JSON Web Key (JWK) Thumbprint [RFC 7638](https://tools.ietf.org/html/rfc7638)
+#   * JWS Unencoded Payload Option  [draft-ietf-jose-jws-signing-input-options-04](https://tools.ietf.org/html/draft-ietf-jose-jws-signing-input-options-04)
 module JOSE
 
-  extend self
-
+  # @!visibility private
   MUTEX = Mutex.new
 
+  # Immutable Map structure based on `Hamster::Hash`.
+  class Map < Hamster::Hash; end
+
   @__crypto_fallback__ = ENV['JOSE_CRYPTO_FALLBACK'] ? true : false
   @__unsecured_signing__ = ENV['JOSE_UNSECURED_SIGNING'] ? true : false
 
-  def __crypto_fallback__
+  # Gets the current Cryptographic Algorithm Fallback state, defaults to `false`.
+  # @return [Boolean]
+  def self.crypto_fallback
     return @__crypto_fallback__
   end
 
-  def __crypto_fallback__=(boolean)
+  # Sets the current Cryptographic Algorithm Fallback state.
+  # @param [Boolean] boolean
+  # @return [Boolean]
+  def self.crypto_fallback=(boolean)
     boolean = !!boolean
     MUTEX.synchronize {
       @__crypto_fallback__ = boolean
       __config_change__
     }
+    return boolean
   end
 
-  def __curve25519_module__
+  # Gets the current Curve25519 module used by {JOSE::JWA::Curve25519 JOSE::JWA::Curve25519}, see {.curve25519_module=} for default.
+  # @return [Module]
+  def self.curve25519_module
     return JOSE::JWA::Curve25519.__implementation__
   end
 
-  def __curve25519_module__=(m)
-    JOSE::JWA::Curve25519.__implementation__ = m
+  # Sets the current Curve25519 module used by {JOSE::JWA::Curve25519 JOSE::JWA::Curve25519}.
+  #
+  # Currently supported Curve25519 modules (first found is used as default):
+  #
+  #   * {https://github.com/cryptosphere/rbnacl `RbNaCl`}
+  #   * {JOSE::JWA::Curve25519_Ruby JOSE::JWA::Curve25519_Ruby} - only supported when {.crypto_fallback} is `true`
+  #
+  # Additional modules that implement the functions specified in {JOSE::JWA::Curve25519 JOSE::JWA::Curve25519} may also be used.
+  # @param [Module] mod
+  # @return [Module]
+  def self.curve25519_module=(mod)
+    JOSE::JWA::Curve25519.__implementation__ = mod
   end
 
-  def __curve448_module__
+  # Gets the current Curve448 module used by {JOSE::JWA::Curve448 JOSE::JWA::Curve448}, see {.curve25519_module=} for default.
+  # @return [Module]
+  def self.curve448_module
     return JOSE::JWA::Curve448.__implementation__
   end
 
-  def __curve448_module__=(m)
-    JOSE::JWA::Curve448.__implementation__ = m
+  # Sets the current Curve448 module used by {JOSE::JWA::Curve448 JOSE::JWA::Curve448}.
+  #
+  # Currently supported Curve448 modules (first found is used as default):
+  #
+  #   * {JOSE::JWA::Curve448_Ruby JOSE::JWA::Curve448_Ruby} - only supported when {.crypto_fallback} is `true`
+  #
+  # Additional modules that implement the functions specified in {JOSE::JWA::Curve448 JOSE::JWA::Curve448} may also be used.
+  # @param [Module] mod
+  # @return [Module]
+  def self.curve448_module=(mod)
+    JOSE::JWA::Curve448.__implementation__ = mod
   end
 
-  def decode(binary)
+  # Decode JSON binary to a term.
+  # @param [String] binary
+  # @return [Object]
+  def self.decode(binary)
     return JSON.load(binary)
   end
 
-  def encode(term)
+  # Encode a term to JSON binary and sorts `Hash` and {JOSE::Map JOSE::Map} keys.
+  # @param [Object] term
+  # @return [Object]
+  def self.encode(term)
     return JSON.dump(sort_maps(term))
   end
 
-  def __unsecured_signing__
+  # Gets the current Unsecured Signing state, defaults to `false`.
+  # @return [Boolean]
+  def self.unsecured_signing
     return @__unsecured_signing__
   end
 
-  def __unsecured_signing__=(boolean)
+  # Sets the current Unsecured Signing state.
+  #
+  # Enables/disables the `"none"` algorithm used for signing and verifying.
+  #
+  # See {https://auth0.com/blog/2015/03/31/critical-vulnerabilities-in-json-web-token-libraries/ Critical vulnerabilities in JSON Web Token libraries} for more information.
+  # @param [Boolean] boolean
+  # @return [Boolean]
+  def self.unsecured_signing=(boolean)
     boolean = !!boolean
     MUTEX.synchronize {
       @__unsecured_signing__ = boolean
       __config_change__
     }
+    return boolean
   end
 
-  def urlsafe_decode64(binary)
+  # Returns the Base64Url decoded version of `binary` without padding.
+  # @param [String] binary
+  # @return [String]
+  def self.urlsafe_decode64(binary)
     case binary.bytesize % 4
     when 2
       binary += '=='
@@ -77,18 +138,21 @@ module JOSE
     return Base64.urlsafe_decode64(binary)
   end
 
-  def urlsafe_encode64(binary)
+  # Returns the Base64Url encoded version of `binary` without padding.
+  # @param [String] binary
+  # @return [String]
+  def self.urlsafe_encode64(binary)
     return Base64.urlsafe_encode64(binary).tr('=', '')
   end
 
 private
 
-  def __config_change__
+  def self.__config_change__
     JOSE::JWA::Curve25519.__config_change__
     JOSE::JWA::Curve448.__config_change__
   end
 
-  def sort_maps(term)
+  def self.sort_maps(term)
     case term
     when Hash, JOSE::Map
       return term.keys.sort.each_with_object(Hash.new) do |key, hash|

data/lib/jose/jwa.rb

@@ -1,4 +1,19 @@
 module JOSE
+  # JWA stands for JSON Web Algorithms which is defined in [RFC 7518](https://tools.ietf.org/html/rfc7518).
+  #
+  # ## Cryptographic Algorithm Fallback
+  #
+  # Native implementations of all cryptographic and public key algorithms
+  # required by the JWA specifications are not present in current versions
+  # of Ruby.
+  #
+  # JOSE will detect whether a specific algorithm is natively supported or not
+  # and, by default, it will mark the algorithm as unsupported if a native
+  # implementation is not found.
+  #
+  # However, JOSE also has pure Ruby versions of many of the missing algorithms
+  # which can be used as a fallback by calling {JOSE.crypto_fallback= JOSE.crypto_fallback=} and
+  # passing `true`.
   module JWA
 
     extend self
@@ -6,6 +21,10 @@ module JOSE
     UCHAR_PACK = 'C*'.freeze
     ZERO_PAD = [0].pack('C').force_encoding('BINARY').freeze
 
+    # Performs a constant time comparison between two binaries to help avoid [timing attacks](https://en.wikipedia.org/wiki/Timing_attack).
+    # @param [String] a
+    # @param [String] b
+    # @return [Boolean]
     def constant_time_compare(a, b)
       return false if a.empty? || b.empty? || a.bytesize != b.bytesize
       l = a.unpack "C#{a.bytesize}"
@@ -15,6 +34,7 @@ module JOSE
       return res == 0
     end
 
+    # @!visibility private
     def exor(a, b)
       a = a.to_bn if a.respond_to?(:to_bn)
       b = b.to_bn if b.respond_to?(:to_bn)
@@ -29,6 +49,279 @@ module JOSE
       end.reverse.pack(UCHAR_PACK), 2)
     end
 
+    # Returns the current listing of supported JOSE algorithms.
+    #
+    #     !!!ruby
+    #     JOSE::JWA.supports
+    #     # => {:jwe=>
+    #     #   {:alg=>
+    #     #     ["A128GCMKW",
+    #     #      "A192GCMKW",
+    #     #      "A256GCMKW",
+    #     #      "A128KW",
+    #     #      "A192KW",
+    #     #      "A256KW",
+    #     #      "ECDH-ES",
+    #     #      "ECDH-ES+A128KW",
+    #     #      "ECDH-ES+A192KW",
+    #     #      "ECDH-ES+A256KW",
+    #     #      "PBES2-HS256+A128KW",
+    #     #      "PBES2-HS384+A192KW",
+    #     #      "PBES2-HS512+A256KW",
+    #     #      "RSA1_5",
+    #     #      "RSA-OAEP",
+    #     #      "RSA-OAEP-256",
+    #     #      "dir"],
+    #     #    :enc=>
+    #     #     ["A128GCM",
+    #     #      "A192GCM",
+    #     #      "A256GCM",
+    #     #      "A128CBC-HS256",
+    #     #      "A192CBC-HS384",
+    #     #      "A256CBC-HS512"],
+    #     #    :zip=>
+    #     #     ["DEF"]},
+    #     #  :jwk=>
+    #     #   {:kty=>
+    #     #     ["EC",
+    #     #      "OKP",
+    #     #      "RSA",
+    #     #      "oct"],
+    #     #    :kty_EC_crv=>
+    #     #     ["P-256",
+    #     #      "P-384",
+    #     #      "P-521"],
+    #     #    :kty_OKP_crv=>
+    #     #     ["Ed25519",
+    #     #      "Ed25519ph",
+    #     #      "Ed448",
+    #     #      "Ed448ph",
+    #     #      "X25519",
+    #     #      "X448"]},
+    #     #  :jws=>
+    #     #   {:alg=>
+    #     #     ["Ed25519",
+    #     #      "Ed25519ph",
+    #     #      "Ed448",
+    #     #      "Ed448ph",
+    #     #      "ES256",
+    #     #      "ES384",
+    #     #      "ES512",
+    #     #      "HS256",
+    #     #      "HS384",
+    #     #      "HS512",
+    #     #      "PS256",
+    #     #      "PS384",
+    #     #      "PS512",
+    #     #      "RS256",
+    #     #      "RS384",
+    #     #      "RS512",
+    #     #      "none"]}}
+    #
+    # @return [Hash]
+    def supports
+      jwe_enc = __jwe_enc_support_check__([
+        'A128GCM',
+        'A192GCM',
+        'A256GCM',
+        'A128CBC-HS256',
+        'A192CBC-HS384',
+        'A256CBC-HS512'
+      ])
+      jwe_alg = __jwe_alg_support_check__([
+        ['A128GCMKW', :block],
+        ['A192GCMKW', :block],
+        ['A256GCMKW', :block],
+        ['A128KW', :block],
+        ['A192KW', :block],
+        ['A256KW', :block],
+        ['ECDH-ES', :box],
+        ['ECDH-ES+A128KW', :box],
+        ['ECDH-ES+A192KW', :box],
+        ['ECDH-ES+A256KW', :box],
+        ['PBES2-HS256+A128KW', :block],
+        ['PBES2-HS384+A192KW', :block],
+        ['PBES2-HS512+A256KW', :block],
+        ['RSA1_5', :rsa],
+        ['RSA-OAEP', :rsa],
+        ['RSA-OAEP-256', :rsa],
+        ['dir', :direct]
+      ], jwe_enc)
+      jwe_zip = __jwe_zip_support_check__([
+        'DEF'
+      ], jwe_enc)
+      jwk_kty, jwk_kty_EC_crv, jwk_kty_OKP_crv = __jwk_kty_support_check__([
+        ['EC', ['P-256', 'P-384', 'P-521']],
+        ['OKP', ['Ed25519', 'Ed25519ph', 'Ed448', 'Ed448ph', 'X25519', 'X448']],
+        'RSA',
+        'oct'
+      ])
+      jws_alg = __jws_alg_support_check__([
+        'Ed25519',
+        'Ed25519ph',
+        'Ed448',
+        'Ed448ph',
+        'ES256',
+        'ES384',
+        'ES512',
+        'HS256',
+        'HS384',
+        'HS512',
+        'PS256',
+        'PS384',
+        'PS512',
+        'RS256',
+        'RS384',
+        'RS512',
+        'X25519',
+        'X448',
+        'none'
+      ])
+      return {
+        jwe: {
+          alg: jwe_alg,
+          enc: jwe_enc,
+          zip: jwe_zip
+        },
+        jwk: {
+          kty: jwk_kty,
+          kty_EC_crv: jwk_kty_EC_crv,
+          kty_OKP_crv: jwk_kty_OKP_crv
+        },
+        jws: {
+          alg: jws_alg
+        }
+      }
+    end
+
+  private
+
+    def __jwe_enc_support_check__(encryption_algorithms)
+      plain_text = SecureRandom.random_bytes(16)
+      return encryption_algorithms.select do |enc|
+        begin
+          jwe = JOSE::JWE.from({ 'alg' => 'dir', 'enc' => enc })
+          jwk = jwe.generate_key
+          cipher_text = jwk.block_encrypt(plain_text).compact
+          next jwk.block_decrypt(cipher_text).first == plain_text
+        rescue StandardError, NotImplementedError
+          next false
+        end
+      end
+    end
+
+    def __jwe_alg_support_check__(key_algorithms, encryption_algorithms)
+      return [] if encryption_algorithms.empty?
+      plain_text = SecureRandom.random_bytes(16)
+      enc = encryption_algorithms[0]
+      rsa = nil
+      return key_algorithms.select do |(alg, strategy)|
+        begin
+          if strategy == :block
+            jwe = JOSE::JWE.from({ 'alg' => alg, 'enc' => enc })
+            jwk = jwe.generate_key
+            cipher_text = jwk.block_encrypt(plain_text).compact
+            next jwk.block_decrypt(cipher_text).first == plain_text
+          elsif strategy == :box
+            jwe = JOSE::JWE.from({ 'alg' => alg, 'enc' => enc })
+            send_jwk = jwe.generate_key
+            recv_jwk = jwe.generate_key
+            cipher_text = recv_jwk.box_encrypt(plain_text, send_jwk).compact
+            next recv_jwk.box_decrypt(cipher_text).first == plain_text
+          elsif strategy == :rsa
+            rsa ||= JOSE::JWK.generate_key([:rsa, 1024])
+            cipher_text = rsa.block_encrypt(plain_text, { 'alg' => alg, 'enc' => enc }).compact
+            next rsa.block_decrypt(cipher_text).first == plain_text
+          elsif strategy == :direct
+            next true
+          else
+            next false
+          end
+        rescue StandardError, NotImplementedError
+          next false
+        end
+      end.transpose.first
+    end
+
+    def __jwe_zip_support_check__(zip_algorithms, encryption_algorithms)
+      return [] if encryption_algorithms.empty?
+      plain_text = SecureRandom.random_bytes(16)
+      alg = 'dir'
+      enc = encryption_algorithms[0]
+      return zip_algorithms.select do |zip|
+        begin
+          jwe = JOSE::JWE.from({ 'alg' => alg, 'enc' => enc, 'zip' => zip })
+          jwk = jwe.generate_key
+          cipher_text = jwk.block_encrypt(plain_text, jwe).compact
+          next jwk.block_decrypt(cipher_text).first == plain_text
+        rescue StandardError, NotImplementedError
+          next false
+        end
+      end
+    end
+
+    def __jwk_kty_support_check__(key_types)
+      kty = []
+      kty_EC_crv = []
+      kty_OKP_crv = []
+      key_types.each do |(key_type, curves)|
+        case key_type
+        when 'EC'
+          curves.each do |curve|
+            begin
+              JOSE::JWK.generate_key([:ec, curve])
+              kty_EC_crv.push(curve)
+            rescue StandardError, NotImplementedError
+              next
+            end
+          end
+          kty.push(key_type) if not kty_EC_crv.empty?
+        when 'OKP'
+          curves.each do |curve|
+            begin
+              JOSE::JWK.generate_key([:okp, curve.to_sym])
+              kty_OKP_crv.push(curve)
+            rescue StandardError, NotImplementedError
+              next
+            end
+          end
+          kty.push(key_type) if not kty_OKP_crv.empty?
+        when 'RSA'
+          begin
+            JOSE::JWK.generate_key([:rsa, 256])
+            kty.push(key_type)
+          rescue StandardError, NotImplementedError
+            # do nothing
+          end
+        when 'oct'
+          begin
+            JOSE::JWK.generate_key([:oct, 8])
+            kty.push(key_type)
+          rescue StandardError, NotImplementedError
+            # do nothing
+          end
+        end
+      end
+      return kty, kty_EC_crv, kty_OKP_crv
+    end
+
+    def __jws_alg_support_check__(signature_algorithms)
+      plain_text = SecureRandom.random_bytes(16)
+      rsa = nil
+      return signature_algorithms.select do |alg|
+        begin
+          jwk = nil
+          jwk ||= JOSE::JWK.generate_key([:oct, 0]).merge({ 'alg' => alg, 'use' => 'sig' }) if alg == 'none'
+          jwk ||= (rsa ||= JOSE::JWK.generate_key([:rsa, 1024])).merge({ 'alg' => alg, 'use' => 'sig' }) if alg.start_with?('RS') or alg.start_with?('PS')
+          jwk ||= JOSE::JWS.generate_key({ 'alg' => alg })
+          signed_text = jwk.sign(plain_text).compact
+          next jwk.verify_strict(signed_text, [alg]).first
+        rescue StandardError, NotImplementedError
+          next false
+        end
+      end
+    end
+
   end
 end