oci 2.0.5 → 2.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d7078801a2b74a3c9b77cb7f2f04c22ee9cb9f10
-  data.tar.gz: 23ba6bd17cd613c9aeb32172d6c15710047440fd
+  metadata.gz: 38b3af475a0f7eb30b1f26b775ae4121b5fdb7f8
+  data.tar.gz: 245eb1ec30aacc7266559e3f9a8669593282fd30
 SHA512:
-  metadata.gz: 4d28e54bcd3b93d54bf5bc6869beeb696ecaeb46f4164c0377caf98990e8da841a3c3b34d6315d103e006304cb45c0533f1b4ce4f4d1e68fb52e42091f33f0a9
-  data.tar.gz: 55a3e63ba55f7184ba30928821d3ba5440e2a1d9802d408a38bcf39806072334c12225092a4bad0a6d0682f134467f80d8ca251ac90f78531a7ec6245e7db7cc
+  metadata.gz: 45e486bdf5f719d842281e33fb05b98433346d786018009abb5d7c9b64b3d19dad1db37fa35d248f215baa5623fc78708e8f2136c6a6072ae075fcea7787c898
+  data.tar.gz: 009fdb794589d0821d5c789e3ea332a2a62acb02f4c7ca3f8a06790442594add8e3af721d97c0c34ec193d6e91a57d97d89e865f53449ed076979705a5caf82f

data/README.md

@@ -1,5 +1,5 @@
 # Oracle Cloud Infrastructure Ruby SDK
-**Version 2.0.5**
+**Version 2.0.6**
 
 This topic describes how to install, configure, and use the Oracle Cloud Infrastructure Ruby SDK.
 
@@ -66,7 +66,7 @@ To use the Ruby SDK, you must have:
 * An Oracle Cloud Infrastructure account.
 * A user created in that account, in a group with a policy that grants the desired permissions. This can be a user for yourself, or another person/system that needs to call the API. For an example of how to set up a new user, group, compartment, and policy, see [Adding Users](https://docs.us-phoenix-1.oraclecloud.com/Content/GSG/Tasks/addingusers.htm) in the Getting Started Guide. For a list of typical policies you may want to use, see [Common Policies](https://docs.us-phoenix-1.oraclecloud.com/Content/Identity/Concepts/commonpolicies.htm) in the User Guide.
 * A keypair used for signing API requests, with the public key uploaded to Oracle. Only the user calling the API should be in possession of the private key. See the configuration information below.
-* Ruby version 2.2 or later running on Mac or Linux. Windows is not supported at this time.
+* Ruby version 2.2 or later running on Mac, Linux or Windows.
 
 # Downloading and Installing the Gem File
 ## Installing the SDK

data/lib/oci.rb

@@ -9,10 +9,13 @@ require 'oci/internal/internal'
 require 'oci/regions'
 require 'oci/response_headers'
 require 'oci/response'
+require 'oci/base_signer'
 require 'oci/signer'
 require 'oci/version'
 require 'oci/waiter'
 
+require 'oci/auth/auth'
+
 require 'oci/audit/audit'
 require 'oci/core/core'
 require 'oci/database/database'

data/lib/oci/api_client.rb

@@ -57,7 +57,8 @@ module OCI
     def call_api(http_method, path, endpoint, opts, &block)
       http_method = http_method.to_sym.downcase
 
-      return call_api_inner(http_method, path, endpoint, opts, &block) unless http_method == :get
+      return call_api_inner(http_method, path, endpoint, opts, &block) if !using_instance_principals? && http_method != :get
+      return instance_principals_signer_wrapped_call { call_api_inner(http_method, path, endpoint, opts, &block) } if using_instance_principals? && http_method != :get
 
       # Wrap get calls in a lambda that can be called later for paging
       # and wait_until.
@@ -70,7 +71,9 @@ module OCI
         return call_api_inner(http_method, path, endpoint, opts, &block)
       }
 
-      response = proc.call(nil)
+      response = proc.call(nil) if !using_instance_principals?
+      response = instance_principals_signer_wrapped_call { proc.call(nil) } if using_instance_principals?
+      
       response.api_call = proc
       response
     end
@@ -238,7 +241,6 @@ module OCI
       rescue Errors::NetworkError, Errors::ServiceError, JSON::ParserError
         raise
       rescue => ex
-        puts(ex.inspect)
         raise Errors::NetworkError.new(ex.message, 0)
       end
     end
@@ -391,5 +393,24 @@ module OCI
       end
     end
 
+    def using_instance_principals?
+      @signer.is_a?(OCI::Auth::Signers::InstancePrincipalsSecurityTokenSigner)
+    end
+
+    def instance_principals_signer_wrapped_call
+      max_attempts = 2
+      
+      max_attempts.times do |attempt|
+        begin
+          return yield
+        rescue OCI::Errors::ServiceError => e
+          raise if attempt >= (max_attempts - 1)  # .times is zero-based
+          raise if e.status != 401
+          
+          @signer.refresh_security_token
+          retry
+        end
+      end
+    end
   end
 end

data/lib/oci/audit/audit_client.rb

@@ -28,15 +28,29 @@ module OCI
     # @param [Config] config A Config object.
     # @param [String] region A region used to determine the service endpoint. This will usually
     #   correspond to a value in {OCI::Regions::REGION_ENUM}, but may be an arbitrary string.
-    #
-    def initialize(config:nil, region:nil)
-      config ||= OCI.config
-      config.validate
+    # @param [OCI::BaseSigner] signer A signer implementation which can be used by this client. If this is not provided then
+    #   a signer will be constructed via the provided config. One use case of this parameter is instance principals authentication,
+    #   so that the instance principals signer can be provided to the client
+    def initialize(config:nil, region:nil, signer:nil)
+      # If the signer is an InstancePrincipalsSecurityTokenSigner and no config was supplied (which is valid for instance principals)
+      # then create a dummy config to pass to the ApiClient constructor. If customers wish to create a client which uses instance principals
+      # and has config (either populated programmatically or loaded from a file), they must construct that config themselves and then
+      # pass it to this constructor.
+      #
+      # If there is no signer (or the signer is not an instance principals signer) and no config was supplied, this is not valid
+      # so try and load the config from the default file.
+      config ||= OCI.config unless signer.is_a?(OCI::Auth::Signers::InstancePrincipalsSecurityTokenSigner)
+      config ||= OCI::Config.new if signer.is_a?(OCI::Auth::Signers::InstancePrincipalsSecurityTokenSigner)
+      config.validate unless signer.is_a?(OCI::Auth::Signers::InstancePrincipalsSecurityTokenSigner)
+
+      if signer.nil?
+        signer = Signer.new(config.user, config.fingerprint, config.tenancy, config.key_file, pass_phrase: config.pass_phrase, private_key_content: config.key_content, signing_strategy: Signer::STANDARD)
+      end
 
-      signer = Signer.new(config.user, config.fingerprint, config.tenancy, config.key_file, pass_phrase: config.pass_phrase, private_key_content: config.key_content, signing_strategy: Signer::STANDARD)
       @api_client = ApiClient.new(config, signer)
 
       region ||= config.region
+      region ||= signer.region if signer.respond_to?(:region)
       self.region = region
     end
 

data/lib/oci/audit/models/audit_event.rb

@@ -83,6 +83,25 @@ module OCI
 
     # Initializes the object
     # @param [Hash] attributes Model attributes in the form of hash
+    # @option attributes [String] :tenantId The value to assign to the {#tenant_id} property
+    # @option attributes [String] :compartmentId The value to assign to the {#compartment_id} property
+    # @option attributes [String] :eventId The value to assign to the {#event_id} property
+    # @option attributes [String] :eventSource The value to assign to the {#event_source} property
+    # @option attributes [String] :eventType The value to assign to the {#event_type} property
+    # @option attributes [DateTime] :eventTime The value to assign to the {#event_time} property
+    # @option attributes [String] :principalId The value to assign to the {#principal_id} property
+    # @option attributes [String] :credentialId The value to assign to the {#credential_id} property
+    # @option attributes [String] :requestAction The value to assign to the {#request_action} property
+    # @option attributes [String] :requestId The value to assign to the {#request_id} property
+    # @option attributes [String] :requestAgent The value to assign to the {#request_agent} property
+    # @option attributes [Hash<String, Array<String>>] :requestHeaders The value to assign to the {#request_headers} property
+    # @option attributes [String] :requestOrigin The value to assign to the {#request_origin} property
+    # @option attributes [Hash<String, Array<String>>] :requestParameters The value to assign to the {#request_parameters} property
+    # @option attributes [String] :requestResource The value to assign to the {#request_resource} property
+    # @option attributes [Hash<String, Array<String>>] :responseHeaders The value to assign to the {#response_headers} property
+    # @option attributes [String] :responseStatus The value to assign to the {#response_status} property
+    # @option attributes [DateTime] :responseTime The value to assign to the {#response_time} property
+    # @option attributes [Hash<String, Object>] :responsePayload The value to assign to the {#response_payload} property
     def initialize(attributes = {})
       return unless attributes.is_a?(Hash)
 

data/lib/oci/audit/models/configuration.rb

@@ -11,6 +11,7 @@ module OCI
 
     # Initializes the object
     # @param [Hash] attributes Model attributes in the form of hash
+    # @option attributes [Integer] :retentionPeriodDays The value to assign to the {#retention_period_days} property
     def initialize(attributes = {})
       return unless attributes.is_a?(Hash)
 

data/lib/oci/audit/models/update_configuration_details.rb

@@ -11,6 +11,7 @@ module OCI
 
     # Initializes the object
     # @param [Hash] attributes Model attributes in the form of hash
+    # @option attributes [Integer] :retentionPeriodDays The value to assign to the {#retention_period_days} property
     def initialize(attributes = {})
       return unless attributes.is_a?(Hash)
 

data/lib/oci/auth/auth.rb

@@ -0,0 +1,16 @@
+# Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
+
+module OCI
+  module Audit
+  end
+end
+
+require 'oci/auth/federation_client'
+require 'oci/auth/security_token_container'
+require 'oci/auth/session_key_supplier'
+require 'oci/auth/util'
+require 'oci/auth/url_based_certificate_retriever'
+
+require 'oci/auth/signers/security_token_signer'
+require 'oci/auth/signers/x509_federation_client_based_security_token_signer'
+require 'oci/auth/signers/instance_principals_security_token_signer'

data/lib/oci/auth/federation_client.rb

@@ -0,0 +1,125 @@
+# Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
+
+require 'json'
+require 'net/http'
+require 'thread'
+
+require 'oci/auth/internal/auth_token_request_signer'
+require 'oci/auth/session_key_supplier'
+
+module OCI
+  module Auth
+    # A client which can be used to retrieve a token from Auth Service. It needs the following supplied to it:
+    #
+    #   * The endpoint for Auth Service
+    #   * Our tenancy OCID
+    #   * A session key supplier so that we can send its public key as part of the token request. The private key in the session key supplier should be used to sign all requests made with the token
+    #   * The certificate (via leaf_certificate_supplier) which will be used to sign the requests to Auth Service.
+    #
+    # Optionally, intermediate certificates (if present) can be supplied as part of the request to Auth Service.
+    #
+    # The client has knowledge of its last requested token and can re-request the token if it is expired (otherwise
+    # it will vend the last requested token if it is not expired).
+    class FederationClient
+      # A supplier which vends a private and public key for signing token requests to Auth Service.
+      # The public key will be sent as part of the token request and the private key should be used to 
+      # sign all requests made with the token vended by this client
+      # @return [OCI::Auth::SessionKeySupplier] A supplier which vends a private and public key for signing token requests to Auth Service
+      attr_reader :session_key_supplier
+
+      # Creates a new FederationClient
+      #
+      # @param [String] federation_endpoint The Auth Service endpoint from which to retrieve the token
+      # @param [String] tenancy_id The OCID of the tenancy whose resources will be interacted with by users of the token
+      # @param [OCI::Auth::SessionKeySupplier] session_key_supplier A supplier which vends a private and public key for signing token requests to Auth Service
+      # @param [OCI::Auth::UrlBasedCertificateRetriever] leaf_certificate_supplier The certificate which will be used to sign requests to Auth Service
+      # @param [Array<OCI::Auth::UrlBasedCertificateRetriever>] intermediate_certificate_suppliers An array of retrievers which can be used to fetch intermediate certificates which can be sent as part of the Auth Service request. If not provided, defaults to an empty array
+      # @param [String] cert_bundle_path The full file path to a custom certificate bundle which can be used for SSL verification against the Auth Service endpoint. If not provided (e.g. because a custom bundle is not needed), defaults to nil
+      def initialize(federation_endpoint, tenancy_id, session_key_supplier, leaf_certificate_supplier, intermediate_certificate_suppliers: [], cert_bundle_path: nil)
+        @federation_endpoint = federation_endpoint
+        uri = URI(@federation_endpoint)
+        @federation_http_client = Net::HTTP.new(uri.hostname, uri.port)
+        @federation_http_client.use_ssl = (uri.scheme == 'https')
+        @federation_http_client.ca_file = cert_bundle_path if cert_bundle_path
+
+        @tenancy_id = tenancy_id
+        @session_key_supplier = session_key_supplier
+        @leaf_certificate_supplier = leaf_certificate_supplier
+        @intermediate_certificate_suppliers = intermediate_certificate_suppliers
+
+        @refresh_lock = Mutex.new
+        @security_token = nil
+      end
+
+      # Retrieves a security token, but always asks Auth Service for a new token, regardless of whether or not the previously requested
+      # token is still valid
+      # @return [String] The security token
+      def security_token!
+        refresh_security_token_inner
+      end
+
+      # Retrieves the security token held by the client. If the previously retrieved token is still valid, it is vended
+      # rather than making another request
+      # @return [String] The security token
+      def security_token
+        return @security_token.security_token if @security_token && @security_token.token_valid?
+        refresh_security_token_inner
+      end
+
+      private
+        def refresh_security_token_inner
+          @refresh_lock.lock
+
+          @session_key_supplier.refresh
+          @leaf_certificate_supplier.refresh
+
+          updated_tenancy_id = OCI::Auth::Util.get_tenancy_id_from_certificate(@leaf_certificate_supplier.certificate)
+          raise "Unexpected update of tenancy OCID in the leaf certificate. Previous tenancy: #{@tenancy_id}, Updated: #{updated_tenancy_id}" if updated_tenancy_id != @tenancy_id
+
+          @intermediate_certificate_suppliers.each { |supplier| supplier.refresh }
+
+          leaf_certificate_pem = @leaf_certificate_supplier.certificate_pem
+          request_payload = {
+            'certificate': OCI::Auth::Util.sanitize_certificate_string(leaf_certificate_pem),
+            'publicKey': OCI::Auth::Util.sanitize_certificate_string(@session_key_supplier.key_pair[:public_key].to_pem)
+          }
+
+          unless @intermediate_certificate_suppliers.empty?
+            retrieved_certs = []
+            @intermediate_certificate_suppliers.each { |supplier| retrieved_certs << OCI::Auth::Util.sanitize_certificate_string(supplier.certificate_pem) }
+            request_payload['intermediateCertificates'] = retrieved_certs
+          end
+
+          fingerprint = OCI::Auth::Util.colon_separate_fingerprint(OpenSSL::Digest::SHA1.new(@leaf_certificate_supplier.certificate.to_der).to_s)
+          signer = OCI::Auth::Internal::AuthTokenRequestSigner.new(@tenancy_id, fingerprint, @leaf_certificate_supplier.private_key_pem)
+
+          request = Net::HTTP::Post.new(@federation_endpoint)
+          request.body = request_payload.to_json
+
+          header_params = {}
+          signer.sign(:post, @federation_endpoint, header_params, request.body)
+          header_params.each { |key, value| request[key.to_s] = value }
+
+          raw_body = nil
+          @federation_http_client.start do
+            @federation_http_client.request(request) do |response|
+              raw_body = response.body
+            end
+          end
+
+          begin
+            parsed_response = JSON.parse(raw_body)
+            raise "No token received in the response from auth service: #{raw_body}" unless parsed_response.has_key?('token')
+
+            @security_token = OCI::Auth::SecurityTokenContainer.new(parsed_response['token'])
+          rescue JSON::ParserError => e
+            raise "Unable to parse response from Auth Service: #{raw_body}"
+          end
+
+          @security_token.security_token
+        ensure
+          @refresh_lock.unlock if @refresh_lock.locked? && @refresh_lock.owned?
+        end
+    end
+  end
+end

data/lib/oci/auth/internal/auth_token_request_signer.rb

@@ -0,0 +1,20 @@
+# Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
+
+require 'oci/base_signer'
+
+module OCI
+  module Auth
+    module Internal
+      # A signer which can sign requests to Auth Service. Not intended for general use
+      class AuthTokenRequestSigner < OCI::BaseSigner
+        def initialize(tenancy_id, fingerprint, private_key_pem)
+          api_key = "#{tenancy_id}/fed-x509/#{fingerprint}"
+          private_key = private_key_pem
+
+          generic_headers = [:"date", :"(request-target)"]
+          super(api_key, private_key, headers_to_sign_in_all_requests: generic_headers)
+        end
+      end
+    end
+  end
+end

data/lib/oci/auth/security_token_container.rb

@@ -0,0 +1,25 @@
+# Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
+
+require 'jwt'
+
+module OCI
+  module Auth
+    # A container class which holds the raw token retrieved from Auth Service and its decoded
+    # equivalent
+    class SecurityTokenContainer
+      attr_reader :jwt
+      attr_reader :security_token
+
+      def initialize(security_token, key_pair: nil)
+        @key_pair = key_pair
+        @security_token = security_token
+        @jwt = JWT.decode(@security_token, nil, false)
+      end
+
+      def token_valid?
+        expiration_epoch_seconds = @jwt[0]['exp']
+        return expiration_epoch_seconds > Time.now.to_i
+      end
+    end
+  end
+end

data/lib/oci/auth/session_key_supplier.rb

@@ -0,0 +1,37 @@
+# Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
+
+require 'openssl'
+require 'thread'
+
+module OCI
+  module Auth
+    # A supplier which can vend a public and private key to be used for signing requests
+    class SessionKeySupplier
+      PUBLIC_EXPONENT = 65537  # Ruby docs suggest 3, 17 or 65537
+      def initialize(key_size: 2048)
+        @key_size = key_size
+        @refresh_lock = Mutex.new
+
+        @private_key = OpenSSL::PKey::RSA.generate(@key_size, PUBLIC_EXPONENT)
+      end
+
+      # Retrieves a public key and private key
+      # @return [Hash] A 2 element hash, where the key 'private_key' retrieves the private key and the public key can be retrieved by using the key 'public_key'
+      def key_pair
+        @refresh_lock.lock
+        private_key = @private_key
+        @refresh_lock.unlock
+
+        {'private_key': private_key, 'public_key': private_key.public_key}
+      end
+
+      # Generates a new public and private key
+      def refresh
+        @refresh_lock.lock
+        @private_key = OpenSSL::PKey::RSA.generate(@key_size, PUBLIC_EXPONENT)
+      ensure
+        @refresh_lock.unlock if @refresh_lock.locked? && @refresh_lock.owned?
+      end
+    end
+  end
+end

data/lib/oci/auth/signers/instance_principals_security_token_signer.rb

@@ -0,0 +1,83 @@
+# Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
+
+require 'net/http'
+require 'uri'
+
+require 'oci/auth/session_key_supplier'
+require 'oci/auth/url_based_certificate_retriever'
+require 'oci/auth/util'
+require 'oci/base_signer'
+require 'oci/regions'
+
+require_relative 'x509_federation_client_based_security_token_signer'
+
+module OCI
+  module Auth
+    module Signers
+      # A SecurityTokenSigner which uses a security token for an instance principal.  This signer can also
+      # refresh its token as needed.
+      #
+      # This signer is self-sufficient in that its internals know how to source the required information to request and use
+      # the token:
+      #
+      #   * Using the metadata endpoint for the instance (http://169.254.169.254/opc/v1) we can discover the region the instance is in, its leaf certificate and any intermediate certificates (for requesting the token) and the tenancy (as) that is in the leaf certificate.
+      #   * The signer leverages {OCI::Auth::FederationClient} so it can refresh the security token and also get the private key needed to sign requests (via the client's session_key_supplier)  
+      class InstancePrincipalsSecurityTokenSigner < OCI::Auth::Signers::X509FederationClientBasedSecurityTokenSigner
+        # The region the instance is in, as returned from the metadata endpoint for the instance (http://169.254.169.254/opc/v1/instance/region)
+        # @return [String] The region for the instance
+        attr_reader :region
+
+        METADATA_URL_BASE = 'http://169.254.169.254/opc/v1'.freeze
+        GET_REGION_URL = "#{METADATA_URL_BASE}/instance/region".freeze
+        LEAF_CERTIFICATE_URL = "#{METADATA_URL_BASE}/identity/cert.pem".freeze
+        LEAF_CERTIFICATE_PRIVATE_KEY_URL = "#{METADATA_URL_BASE}/identity/key.pem".freeze
+        INTERMEDIATE_CERTIFICATE_URL = "#{METADATA_URL_BASE}/identity/intermediate.pem".freeze
+
+        # Creates a new InstancePrincipalsSecurityTokenSigner
+        #
+        # @param [String] federation_endpoint The endpoint where we will retrieve the instance principals auth token from. If not provided, this will
+        # default to the endpoint which the instance is in
+        # @param [String] federation_client_cert_bundle The full file path to a custom certificate bundle which can be used for SSL verification against the federation_endpoint. If not provided (e.g. because a custom bundle is not needed), defaults to nil
+        # @param [String] signing_strategy Whether this signer is used for Object Storage requests or not. Acceptable values are {OCI::BaseSigner::STANDARD} and {OCI::BaseSigner::OBJECT_STORAGE}. If not provided, defaults to {OCI::BaseSigner::STANDARD}
+        # @param [Array<String>] headers_to_sign_in_all_requests An array of headers which will be signed in each request. If not provided, defaults to {OCI::BaseSigner::GENERIC_HEADERS}
+        # @param [Array<String>] body_headers_to_sign An array of headers which should be signed on requests with bodies. If not provided, defaults to {OCI::BaseSigner::BODY_HEADERS}
+        def initialize(federation_endpoint: nil, federation_client_cert_bundle: nil, signing_strategy: OCI::BaseSigner::STANDARD, headers_to_sign_in_all_requests: OCI::BaseSigner::GENERIC_HEADERS, body_headers_to_sign: OCI::BaseSigner::BODY_HEADERS)
+          @leaf_certificate_retriever = OCI::Auth::UrlBasedCertificateRetriever.new(LEAF_CERTIFICATE_URL, private_key_url: LEAF_CERTIFICATE_PRIVATE_KEY_URL)
+          @intermediate_certificate_retriever = OCI::Auth::UrlBasedCertificateRetriever.new(INTERMEDIATE_CERTIFICATE_URL)
+          @session_key_supplier = OCI::Auth::SessionKeySupplier.new
+          @tenancy_id = OCI::Auth::Util.get_tenancy_id_from_certificate(@leaf_certificate_retriever.certificate)
+
+          raw_region = Net::HTTP.get(URI(GET_REGION_URL)).strip
+          symbolised_raw_region = raw_region.to_sym
+          if OCI::Regions::REGION_SHORT_NAMES_TO_LONG_NAMES.has_key?(symbolised_raw_region)
+            @region = OCI::Regions::REGION_SHORT_NAMES_TO_LONG_NAMES[symbolised_raw_region]
+          else
+            @region = raw_region
+          end
+
+          if federation_endpoint
+            @federation_endpoint = federation_endpoint
+          else
+            @federation_endpoint = "#{OCI::Regions.get_service_endpoint(@region, :Auth)}/v1/x509"
+          end
+
+          @federation_client = OCI::Auth::FederationClient.new(
+            @federation_endpoint,
+            @tenancy_id,
+            @session_key_supplier,
+            @leaf_certificate_retriever,
+            intermediate_certificate_suppliers: [@intermediate_certificate_retriever],
+            cert_bundle_path: federation_client_cert_bundle
+          )
+
+          super(
+            @federation_client, 
+            signing_strategy: signing_strategy,
+            headers_to_sign_in_all_requests: headers_to_sign_in_all_requests,
+            body_headers_to_sign: body_headers_to_sign
+          )
+        end
+      end
+    end
+  end
+end