cerner-oauth1a 1.0.1 → 2.0.0.rc1

data/lib/cerner/oauth1a/access_token_agent.rb

@@ -1,15 +1,21 @@
+# frozen_string_literal: true
+
+require 'base64'
 require 'cerner/oauth1a/access_token'
+require 'cerner/oauth1a/keys'
 require 'cerner/oauth1a/oauth_error'
+require 'cerner/oauth1a/cache'
+require 'cerner/oauth1a/protocol'
 require 'cerner/oauth1a/version'
+require 'json'
 require 'net/https'
 require 'securerandom'
 require 'uri'
 
 module Cerner
   module OAuth1a
-
-    # Public: A User Agent for interacting with the Access Token service to acquire
-    # Access Tokens.
+    # Public: A user agent for interacting with the Cerner OAuth 1.0a Access Token service to acquire
+    # consumer Access Tokens or service provider Keys.
     class AccessTokenAgent
       MIME_WWW_FORM_URL_ENCODED = 'application/x-www-form-urlencoded'
 
@@ -22,18 +28,41 @@ module Cerner
 
       # Public: Constructs an instance of the agent.
       #
+      # Caching - By default, AccessToken and Keys instances are maintained in a small, constrained
+      # memory cache used by #retrieve and #retrieve_keys, respectively.
+      #
+      # The AccessToken cache keeps a maximum of 5 entries and prunes them when they expire. As the
+      # cache is based on the #consumer_key and the 'principal' parameter, the cache has limited
+      # effect. It's strongly suggested that AccessToken's be cached independently, as well.
+      #
+      # The Keys cache keeps a maximum of 10 entries and prunes them 24 hours after retrieval.
+      #
       # arguments - The keyword arguments of the method:
-      #             :access_token_url - The String or URI of the Access Token service endpoint.
-      #             :consumer_key     - The String of the Consumer Key of the account.
-      #             :consumer_secret  - The String of the Consumer Secret of the account.
-      #             :open_timeout     - An object responding to to_i. Used to set the timeout, in seconds,
-      #                                 for opening HTTP connections to the Access Token service (optional, default: 5).
-      #             :read_timeout     - An object responding to to_i. Used to set the timeout, in seconds,
-      #                                 for reading data from HTTP connections to the Access Token service (optional, default: 5).
-      #
-      # Raises ArgumentError if access_token_url, consumer_key or consumer_key is nil; if access_token_url is
-      #                      an invalid URI.
-      def initialize(access_token_url:, consumer_key:, consumer_secret:, open_timeout: 5, read_timeout: 5)
+      #             :access_token_url    - The String or URI of the Access Token service endpoint.
+      #             :consumer_key        - The String of the Consumer Key of the account.
+      #             :consumer_secret     - The String of the Consumer Secret of the account.
+      #             :open_timeout        - An object responding to to_i. Used to set the timeout, in
+      #                                    seconds, for opening HTTP connections to the Access Token
+      #                                    service (optional, default: 5).
+      #             :read_timeout        - An object responding to to_i. Used to set the timeout, in
+      #                                    seconds, for reading data from HTTP connections to the
+      #                                    Access Token service (optional, default: 5).
+      #             :cache_keys          - A Boolean for configuring Keys caching within
+      #                                    #retrieve_keys. (optional, default: true)
+      #             :cache_access_tokens - A Boolean for configuring AccessToken caching within
+      #                                    #retrieve. (optional, default: true)
+      #
+      # Raises ArgumentError if access_token_url, consumer_key or consumer_key is nil; if
+      #                      access_token_url is an invalid URI.
+      def initialize(
+        access_token_url:,
+        consumer_key:,
+        consumer_secret:,
+        open_timeout: 5,
+        read_timeout: 5,
+        cache_keys: true,
+        cache_access_tokens: true
+      )
         raise ArgumentError, 'consumer_key is nil' unless consumer_key
         raise ArgumentError, 'consumer_secret is nil' unless consumer_secret
 
@@ -44,73 +73,65 @@ module Cerner
 
         @open_timeout = (open_timeout ? open_timeout.to_i : 5)
         @read_timeout = (read_timeout ? read_timeout.to_i : 5)
+
+        @keys_cache = cache_keys ? Cache.new(max: 10) : nil
+        @access_token_cache = cache_access_tokens ? Cache.new(max: 5) : nil
       end
 
-      # Public: Retrives an AccessToken from the configured Access Token service endpoint (#access_token_url).
-      # This method will the #generate_accessor_secret, #generate_nonce and #generate_timestamp methods to
-      # interact with the service, which can be overridden via a sub-class, if desired.
+      # Public: Retrieves the service provider keys from the configured Access Token service endpoint
+      # (@access_token_url). This method will invoke #retrieve to acquire an AccessToken to request
+      # the keys.
       #
-      # Returns a AccessToken upon success.
+      # keys_version - The version identifier of the keys to retrieve. This corresponds to the
+      #                KeysVersion parameter of the oauth_token.
       #
-      # Raises OAuthError unless the service returns a HTTP Status Code of 200.
-      # Raises StandardError sub-classes for any issues interacting with the service.
-      def retrieve
-        # construct a POST request
-        request = Net::HTTP::Post.new @access_token_url
+      # Return a Keys instance upon success.
+      #
+      # Raises ArgumentError if keys_version is nil.
+      # Raises OAuthError for any functional errors returned within an HTTP 200 response.
+      # Raises StandardError sub-classes for any issues interacting with the service, such as networking issues.
+      def retrieve_keys(keys_version)
+        raise ArgumentError, 'keys_version is nil' unless keys_version
 
-        # setup the data to construct the POST's message
-        accessor_secret = generate_accessor_secret
-        nonce = generate_nonce
-        timestamp = generate_timestamp
-        params = [
-                  [:oauth_consumer_key, @consumer_key],
-                  [:oauth_signature_method, 'PLAINTEXT'],
-                  [:oauth_version, '1.0'],
-                  [:oauth_timestamp, timestamp],
-                  [:oauth_nonce, nonce],
-                  [:oauth_signature, "#{@consumer_secret}&"],
-                  [:oauth_accessor_secret, accessor_secret]
-                 ]
-        # set the POST's body as a URL form-encoded string
-        request.set_form(params, MIME_WWW_FORM_URL_ENCODED, charset: 'UTF-8')
+        if @keys_cache
+          cache_entry = @keys_cache.get(keys_version)
+          return cache_entry.value if cache_entry
+        end
 
-        request['Accept'] = MIME_WWW_FORM_URL_ENCODED
-        # Set a custom User-Agent to help identify these invocation
-        request['User-Agent'] = "cerner-oauth1a #{VERSION} (Ruby #{RUBY_VERSION})"
+        request = retrieve_keys_prepare_request(keys_version)
+        response = http_client.request(request)
+        keys = retrieve_keys_handle_response(keys_version, response)
+        @keys_cache&.put(keys_version, Cache::KeysEntry.new(keys, Cache::TWENTY_FOUR_HOURS))
+        keys
+      end
 
-        http = Net::HTTP.new(@access_token_url.host, @access_token_url.port)
-        if @access_token_url.scheme == 'https'
-          # if the scheme is HTTPS, then enable SSL
-          http.use_ssl = true
-          # make sure to verify peers
-          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
-          # tweak the ciphers to eliminate unsafe options
-          http.ciphers = 'DEFAULT:!aNULL:!eNULL:!LOW:!SSLv2:!RC4'
+      # Public: Retrieves an AccessToken from the configured Access Token service endpoint (#access_token_url).
+      # This method will use the #generate_accessor_secret, #generate_nonce and #generate_timestamp methods to
+      # interact with the service, which can be overridden via a sub-class, if desired.
+      #
+      # principal - An optional principal identifier, which is passed via the xoauth_principal protocol parameter.
+      #
+      # Returns a AccessToken upon success.
+      #
+      # Raises OAuthError for any functional errors returned within an HTTP 200 response.
+      # Raises StandardError sub-classes for any issues interacting with the service, such as networking issues.
+      def retrieve(principal = nil)
+        cache_key = "#{@consumer_key}&#{principal}"
+        if @access_token_cache
+          cache_entry = @access_token_cache.get(cache_key)
+          return cache_entry.value if cache_entry
         end
-        http.open_timeout = @open_timeout
-        http.read_timeout = @read_timeout
 
-        response = http.request request
+        # generate token request info
+        nonce = generate_nonce
+        timestamp = generate_timestamp
+        accessor_secret = generate_accessor_secret
 
-        case response
-        when Net::HTTPSuccess
-          # Part the HTTP response and convert it into a Symbol-keyed Hash
-          tuples = Hash[URI.decode_www_form(response.body).map { |pair| [pair[0].to_sym, pair[1]] }]
-          # Use the parsed response to construct the AccessToken
-          access_token = AccessToken.new(accessor_secret: accessor_secret,
-                                         consumer_key: @consumer_key,
-                                         expires_at: timestamp + tuples[:oauth_expires_in].to_i,
-                                         nonce: nonce,
-                                         timestamp: timestamp,
-                                         token: tuples[:oauth_token],
-                                         token_secret: tuples[:oauth_token_secret])
-          access_token
-        else
-          # Extract any OAuth Problems reported in the response
-          oauth_data = parse_www_authenticate(response['WWW-Authenticate'])
-          # Raise an error for a failure to acquire a token
-          raise OAuthError.new('unable to acquire token', response.code, oauth_data['oauth_problem'])
-        end
+        request = retrieve_prepare_request(timestamp, nonce, accessor_secret, principal)
+        response = http_client.request(request)
+        access_token = retrieve_handle_response(response, timestamp, nonce, accessor_secret)
+        @access_token_cache&.put(cache_key, Cache::AccessTokenEntry.new(access_token))
+        access_token
       end
 
       # Public: Generate an Accessor Secret for invocations of the Access Token service.
@@ -136,18 +157,28 @@ module Cerner
 
       private
 
-      # Internal: Parse a WWW-Authenticate HTTP header for any OAuth
-      # information, which is indicated by a value starting with 'OAuth '.
-      #
-      # value - The String containing the header value.
-      #
-      # Returns a Hash containing any name-value pairs found in the value.
-      def parse_www_authenticate(value)
-        return {} unless value
-        value = value.strip
-        return {} unless value.start_with?('OAuth ')
+      # Internal: Generate a User-Agent HTTP Header string
+      def user_agent_string
+        "cerner-oauth1a #{VERSION} (Ruby #{RUBY_VERSION})"
+      end
+
+      # Internal: Provide the HTTP client instance for invoking requests
+      def http_client
+        http = Net::HTTP.new(@access_token_url.host, @access_token_url.port)
+
+        if @access_token_url.scheme == 'https'
+          # if the scheme is HTTPS, then enable SSL
+          http.use_ssl = true
+          # make sure to verify peers
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          # tweak the ciphers to eliminate unsafe options
+          http.ciphers = 'DEFAULT:!aNULL:!eNULL:!LOW:!SSLv2:!RC4'
+        end
+
+        http.open_timeout = @open_timeout
+        http.read_timeout = @read_timeout
 
-        Hash[value.scan(/([^\s=]*)=\"([^\"]*)\"/)]
+        http
       end
 
       # Internal: Convert an Access Token URL into a URI with some verification checks
@@ -163,17 +194,93 @@ module Cerner
         else
           begin
             uri = URI(access_token_url)
-          rescue URI::InvalidURIError => e
+          rescue URI::InvalidURIError
             # raise argument error with cause
             raise ArgumentError, 'access_token_url is invalid'
           end
         end
-        unless uri.is_a? URI::HTTP
-          raise ArgumentError, 'access_token_url must be an HTTP or HTTPS URI'
-        end
+        raise ArgumentError, 'access_token_url must be an HTTP or HTTPS URI' unless uri.is_a?(URI::HTTP)
         uri
       end
-    end
 
+      # Internal: Prepare a request for #retrieve
+      def retrieve_prepare_request(timestamp, nonce, accessor_secret, principal)
+        # construct a POST request
+        request = Net::HTTP::Post.new(@access_token_url)
+        # setup the data to construct the POST's message
+        params = [
+          [:oauth_consumer_key, @consumer_key],
+          [:oauth_signature_method, 'PLAINTEXT'],
+          [:oauth_version, '1.0'],
+          [:oauth_timestamp, timestamp],
+          [:oauth_nonce, nonce],
+          [:oauth_signature, "#{@consumer_secret}&"],
+          [:oauth_accessor_secret, accessor_secret]
+        ]
+        params << [:xoauth_principal, principal.to_s] if principal
+        # set the POST's body as a URL form-encoded string
+        request.set_form(params, MIME_WWW_FORM_URL_ENCODED, charset: 'UTF-8')
+        request['Accept'] = MIME_WWW_FORM_URL_ENCODED
+        # Set a custom User-Agent to help identify these invocation
+        request['User-Agent'] = user_agent_string
+        request
+      end
+
+      # Internal: Handle a response for #retrieve
+      def retrieve_handle_response(response, timestamp, nonce, accessor_secret)
+        case response
+        when Net::HTTPSuccess
+          # Parse the HTTP response and convert it into a Symbol-keyed Hash
+          tuples = Protocol.parse_url_query_string(response.body)
+          # Use the parsed response to construct the AccessToken
+          access_token = AccessToken.new(
+            accessor_secret: accessor_secret,
+            consumer_key: @consumer_key,
+            expires_at: timestamp + tuples[:oauth_expires_in].to_i,
+            nonce: nonce,
+            timestamp: timestamp,
+            token: tuples[:oauth_token],
+            token_secret: tuples[:oauth_token_secret]
+          )
+          access_token
+        else
+          # Extract any OAuth Problems reported in the response
+          oauth_data = Protocol.parse_authorization_header(response['WWW-Authenticate'])
+          # Raise an error for a failure to acquire a token
+          raise OAuthError.new('unable to acquire token', response.code, oauth_data[:oauth_problem])
+        end
+      end
+
+      # Internal: Prepare a request for #retrieve_keys
+      def retrieve_keys_prepare_request(keys_version)
+        request = Net::HTTP::Get.new("#{@access_token_url}/keys/#{keys_version}")
+        request['Accept'] = 'application/json'
+        request['User-Agent'] = user_agent_string
+        request['Authorization'] = retrieve.authorization_header
+        request
+      end
+
+      # Internal: Handle a response for #retrieve_keys
+      def retrieve_keys_handle_response(keys_version, response)
+        case response
+        when Net::HTTPSuccess
+          parsed_response = JSON.parse(response.body)
+          aes_key = parsed_response.dig('aesKey', 'secretKey')
+          raise OAuthError, 'AES secret key retrieved was invalid' unless aes_key
+          rsa_key = parsed_response.dig('rsaKey', 'publicKey')
+          raise OAuthError, 'RSA public key retrieved was invalid' unless rsa_key
+          Keys.new(
+            version: keys_version,
+            aes_secret_key: Base64.decode64(aes_key),
+            rsa_public_key: Base64.decode64(rsa_key)
+          )
+        else
+          # Extract any OAuth Problems reported in the response
+          oauth_data = Protocol.parse_authorization_header(response['WWW-Authenticate'])
+          # Raise an error for a failure to acquire keys
+          raise OAuthError.new('unable to acquire keys', response.code, oauth_data[:oauth_problem])
+        end
+      end
+    end
   end
 end

data/lib/cerner/oauth1a/cache.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Cerner
+  module OAuth1a
+    # Internal: A simple cache abstraction for use by AccessTokenAgent only.
+    class Cache
+      # Internal: A cache entry class for Keys values.
+      class KeysEntry
+        attr_reader :value
+
+        def initialize(keys, expires_in)
+          @value = keys
+          @expires_at = Time.now.utc.to_i + expires_in
+        end
+
+        def expired?(now)
+          @expires_at <= now
+        end
+      end
+
+      # Internal: A cache entry class for AccessToken values.
+      class AccessTokenEntry
+        attr_reader :value
+
+        def initialize(access_token)
+          @value = access_token
+        end
+
+        def expired?(now)
+          @value.expired?(now: now)
+        end
+      end
+
+      ONE_HOUR = 3600
+      TWENTY_FOUR_HOURS = 24 * ONE_HOUR
+
+      def initialize(max:)
+        @max = max
+        @lock = Mutex.new
+        @entries = {}
+      end
+
+      def put(key, entry)
+        @lock.synchronize do
+          now = Time.now.utc.to_i
+          prune_expired(now)
+          @entries[key] = entry
+          prune_size
+        end
+      end
+
+      def get(key)
+        @lock.synchronize do
+          prune_expired(Time.now.utc.to_i)
+          @entries[key]
+        end
+      end
+
+      private
+
+      def prune_expired(now)
+        return if @entries.empty?
+
+        @entries.delete_if { |_, v| v.expired?(now) }
+
+        nil
+      end
+
+      def prune_size
+        return if @entries.empty? || @entries.size <= @max
+
+        num_to_prune = @entries.size - @max
+        num_to_prune.times { @entries.shift }
+
+        nil
+      end
+    end
+  end
+end

data/lib/cerner/oauth1a/keys.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'openssl'
+require 'uri'
+
+module Cerner
+  module OAuth1a
+    # Public: Keys for authenticating Access Tokens by service providers. Keys can be retrieved
+    # via AccessTokenAgent#retrieve_keys.
+    class Keys
+      # Returns the String version identifier of the keys.
+      attr_reader :version
+      # Returns the String AES secret key.
+      attr_reader :aes_secret_key
+      # Returns the String RSA public key.
+      attr_reader :rsa_public_key
+
+      # Public: Constructs an instance.
+      #
+      # arguments - The keyword arguments of the method:
+      #             :version        - The version identifier of the keys.
+      #             :aes_secret_key - The AES secret key.
+      #             :rsa_public_key - The RSA public key.
+      #
+      # Raises ArgumentError if version, aes_secret_key or rsa_public_key is nil.
+      def initialize(version:, aes_secret_key:, rsa_public_key:)
+        raise ArgumentError, 'version is nil' unless version
+        raise ArgumentError, 'aes_secret_key is nil' unless aes_secret_key
+        raise ArgumentError, 'rsa_public_key is nil' unless rsa_public_key
+
+        @version = version
+        @aes_secret_key = aes_secret_key
+        @rsa_public_key = rsa_public_key
+      end
+
+      # Public: Compare this to other based on attributes.
+      #
+      # other - The Keys to compare this to.
+      #
+      # Return true if equal; false otherwise
+      def ==(other)
+        version == other.version &&
+          aes_secret_key == other.aes_secret_key &&
+          rsa_public_key == other.rsa_public_key
+      end
+
+      # Public: Compare this to other based on attributes.
+      #
+      # other - The Keys to compare this to.
+      #
+      # Return true if equal; false otherwise
+      def eql?(other)
+        self == other
+      end
+
+      # Public: Generates a Hash of the attributes.
+      #
+      # Returns a Hash with keys for each attribute.
+      def to_h
+        {
+          version: @version,
+          aes_secret_key: @aes_secret_key,
+          rsa_public_key: @rsa_public_key
+        }
+      end
+
+      # Public: Returns the #rsa_public_key as an OpenSSL::PKey::RSA intance.
+      #
+      # Raises OpenSSL::PKey::RSAError if #rsa_public_key is not a valid key
+      def rsa_public_key_as_pkey
+        OpenSSL::PKey::RSA.new(@rsa_public_key)
+      end
+
+      # Public: Verifies that an oauth_token is authentic based on the #rsa_public_key.
+      #
+      # oauth_token - The oauth_token value to verify.
+      #
+      # Returns true if authentic; false otherwise.
+      #
+      # Raises ArgumentError if oauth_token is nil or invalid
+      # Raises OpenSSL::PKey::RSAError if #rsa_public_key is not a valid key
+      def verify_rsasha1_signature(oauth_token)
+        raise ArgumentError, 'oauth_token is nil' unless oauth_token
+
+        message, raw_sig = oauth_token.split('&RSASHA1=')
+        raise ArgumentError, 'unable to get message out of oauth_token' unless message
+        raise ArgumentError, 'unable to get RSASHA1 signature out of oauth_token' unless raw_sig
+
+        # URL decode value and Base64 (urlsafe) decode that result
+        sig = Base64.urlsafe_decode64(URI.decode_www_form_component(raw_sig))
+        rsa_public_key_as_pkey.verify(OpenSSL::Digest::SHA1.new, sig, message)
+      end
+
+      # Public: Decrypts the HMACSecrets parameter of an oauth_token using the #aes_secret_key.
+      #
+      # hmac_secrets_param - The extracted value of the HMACSecrets parameter of an oauth_token. The
+      #                      value is assumed to be Base64 (URL safe) encoded.
+      #
+      # Returns the decrypted secrets.
+      #
+      # Raises ArgumentError if oauth_token is nil or invalid
+      def decrypt_hmac_secrets(hmac_secrets_param)
+        raise ArgumentError, 'hmac_secrets_param is nil' unless hmac_secrets_param
+
+        ciphertext = Base64.urlsafe_decode64(hmac_secrets_param)
+        raise ArgumentError, 'hmac_secrets_param does not contain enough data' unless ciphertext.size > 16
+
+        # extract first 16 bytes to get initialization vector
+        iv = ciphertext[0, 16]
+        # trim off the IV
+        ciphertext = ciphertext[16..-1]
+
+        cipher = OpenSSL::Cipher.new('AES-128-CBC')
+        # invoke #decrypt to prep the instance
+        cipher.decrypt
+        cipher.iv = iv
+        cipher.key = @aes_secret_key
+        text = cipher.update(ciphertext) + cipher.final
+        text
+      end
+    end
+  end
+end