JWK: More Documentation

Author: bellebaum

README.md

@@ -612,15 +612,27 @@ JWT.decode(token, nil, true, { algorithms: ['RS512'], jwks: jwks})
 
 ### Importing and exporting JSON Web Keys
 
-The ::JWT::JWK class can be used to import and export both the public key (default behaviour) and the private key. To include the private key in the export pass the `include_private` parameter to the export method.
+The ::JWT::JWK class can be used to import both JSON Web Keys and OpenSSL keys
+and export to either format with and without the private key included.
+
+To include the private key in the export pass the `include_private` parameter to the export method.
 
 ```ruby
+# Import a JWK Hash (showing an HMAC example)
+jwk = JWT::JWK.new({ kty: 'oct', k: 'my-secret', kid: 'my-kid' })
+
+# Import an OpenSSL key
 # You can optionally add descriptive parameters to the JWK
 desc_params = { kid: 'my-kid', use: 'sig' }
 jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048), desc_params)
 
+# Export as JWK Hash (public key only by default)
 jwk_hash = jwk.export
 jwk_hash_with_private_key = jwk.export(include_private: true)
+
+# Export as OpenSSL key
+public_key = jwk.public_key
+private_key = jwk.keypair if jwk.private?
 ```
 
 ### Key ID (kid) and JWKs

lib/jwt/jwk.rb

@@ -5,17 +5,17 @@
 module JWT
   module JWK
     class << self
-      def import(jwk_data)
-        jwk_kty = jwk_data[:kty] || jwk_data['kty']
-        raise JWT::JWKError, 'Key type (kty) not provided' unless jwk_kty
+      def create_from(key, params = nil, options = {})
+        if key.is_a?(Hash)
+          jwk_kty = key[:kty] || key['kty']
+          raise JWT::JWKError, 'Key type (kty) not provided' unless jwk_kty
 
-        mappings.fetch(jwk_kty.to_s) do |kty|
-          raise JWT::JWKError, "Key type #{kty} not supported"
-        end.import(jwk_data)
-      end
+          return mappings.fetch(jwk_kty.to_s) do |kty|
+            raise JWT::JWKError, "Key type #{kty} not supported"
+          end.new(key, params, options)
+        end
 
-      def create_from(key, params = nil, options = {})
-        mappings.fetch(keypair.class) do |klass|
+        mappings.fetch(key.class) do |klass|
           raise JWT::JWKError, "Cannot create JWK from a #{klass.name}"
         end.new(key, params, options)
       end
@@ -26,6 +26,7 @@ def classes
       end
 
       alias new create_from
+      alias import create_from
 
       private
 

spec/integration/readme_examples_spec.rb

@@ -370,6 +370,24 @@
       end
     end
 
+    it 'JWK import and export' do
+      # Import a JWK Hash (showing an HMAC example)
+      _jwk = JWT::JWK.new({ kty: 'oct', k: 'my-secret', kid: 'my-kid' })
+
+      # Import an OpenSSL key
+      # You can optionally add descriptive parameters to the JWK
+      desc_params = { kid: 'my-kid', use: 'sig' }
+      jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048), desc_params)
+
+      # Export as JWK Hash (public key only by default)
+      _jwk_hash = jwk.export
+      _jwk_hash_with_private_key = jwk.export(include_private: true)
+
+      # Export as OpenSSL key
+      _public_key = jwk.public_key
+      _private_key = jwk.keypair if jwk.private?
+    end
+
     it 'JWK with thumbprint as kid via symbol' do
       JWT.configuration.jwk.kid_generator_type = :rfc7638_thumbprint