google-cloud-storage 1.25.0 → 1.27.0

data/lib/google/cloud/storage/bucket/lifecycle.rb

@@ -111,7 +111,7 @@ module Google
           # @param [String,Symbol,Array<String,Symbol>] matches_storage_class
           #   Files having any of the storage classes specified by this
           #   condition will be matched. Values include `STANDARD`, `NEARLINE`,
-          #   and `COLDLINE`. `REGIONAL`,`MULTI_REGIONAL`, and
+          #   `COLDLINE`, and `ARCHIVE`. `REGIONAL`,`MULTI_REGIONAL`, and
           #   `DURABLE_REDUCED_AVAILABILITY` are supported as legacy storage
           #   classes. Arguments will be converted from symbols and lower-case
           #   to upper-case strings.
@@ -162,7 +162,7 @@ module Google
           # @param [String,Symbol,Array<String,Symbol>] matches_storage_class
           #   Files having any of the storage classes specified by this
           #   condition will be matched. Values include `STANDARD`, `NEARLINE`,
-          #   and `COLDLINE`. `REGIONAL`,`MULTI_REGIONAL`, and
+          #   `COLDLINE`, and `ARCHIVE`. `REGIONAL`,`MULTI_REGIONAL`, and
           #   `DURABLE_REDUCED_AVAILABILITY` are supported as legacy storage
           #   classes. Arguments will be converted from symbols and lower-case
           #   to upper-case strings.
@@ -240,9 +240,9 @@ module Google
           #   is `false`, it matches archived files.
           # @attr [Array<String>] matches_storage_class Files having any of the
           #   storage classes specified by this condition will be matched.
-          #   Values include `STANDARD`, `NEARLINE`, and `COLDLINE`. `REGIONAL`,
-          #   `MULTI_REGIONAL`, and `DURABLE_REDUCED_AVAILABILITY` are supported
-          #   as legacy storage classes.
+          #   Values include `STANDARD`, `NEARLINE`, `COLDLINE`, and `ARCHIVE`.
+          #   `REGIONAL`, `MULTI_REGIONAL`, and `DURABLE_REDUCED_AVAILABILITY`
+          #   are supported as legacy storage classes.
           # @attr [Integer] num_newer_versions Relevant only for versioned
           #   files. If the value is N, this condition is satisfied when there
           #   are at least N versions (including the live version) newer than

data/lib/google/cloud/storage/convert.rb

@@ -25,12 +25,13 @@ module Google
         def storage_class_for str
           return nil if str.nil?
           return str.map { |s| storage_class_for s } if str.is_a? Array
-          { "durable_reduced_availability" => "DURABLE_REDUCED_AVAILABILITY",
+          { "archive" => "ARCHIVE",
+            "coldline" => "COLDLINE",
             "dra" => "DURABLE_REDUCED_AVAILABILITY",
             "durable" => "DURABLE_REDUCED_AVAILABILITY",
-            "nearline" => "NEARLINE",
-            "coldline" => "COLDLINE",
+            "durable_reduced_availability" => "DURABLE_REDUCED_AVAILABILITY",
             "multi_regional" => "MULTI_REGIONAL",
+            "nearline" => "NEARLINE",
             "regional" => "REGIONAL",
             "standard" => "STANDARD" }[str.to_s.downcase] || str.to_s
         end

data/lib/google/cloud/storage/errors.rb

@@ -58,8 +58,13 @@ module Google
       ##
       # # SignedUrlUnavailable Error
       #
-      # This is raised when File#signed_url is unable to generate a URL due to
-      # missing credentials needed to create the URL.
+      # Raised by signed URL methods if the service account credentials
+      # are missing. Service account credentials are acquired by following the
+      # steps in [Service Account Authentication](
+      # https://cloud.google.com/iam/docs/service-accounts).
+      #
+      # @see https://cloud.google.com/storage/docs/access-control/signed-urls Signed URLs
+      #
       class SignedUrlUnavailable < Google::Cloud::Error
       end
     end

data/lib/google/cloud/storage/file.rb

@@ -431,6 +431,7 @@ module Google
         # * `:standard`
         # * `:nearline`
         # * `:coldline`
+        # * `:archive`
         #
         # as well as the equivalent strings returned by {File#storage_class} or
         # {Bucket#storage_class}. For more information, see [Storage
@@ -1441,7 +1442,7 @@ module Google
         # A {SignedUrlUnavailable} is raised if the service account credentials
         # are missing. Service account credentials are acquired by following the
         # steps in [Service Account Authentication](
-        # https://cloud.google.com/storage/docs/authentication#service_accounts).
+        # https://cloud.google.com/iam/docs/service-accounts).
         #
         # @see https://cloud.google.com/storage/docs/access-control/signed-urls
         #   Signed URLs guide
@@ -1466,10 +1467,22 @@ module Google
         #   use the signed URL.
         # @param [String] issuer Service Account's Client Email.
         # @param [String] client_email Service Account's Client Email.
-        # @param [OpenSSL::PKey::RSA, String] signing_key Service Account's
-        #   Private Key.
-        # @param [OpenSSL::PKey::RSA, String] private_key Service Account's
-        #   Private Key.
+        # @param [OpenSSL::PKey::RSA, String, Proc] signing_key Service Account's
+        #   Private Key or a Proc that accepts a single String parameter and returns a
+        #   RSA SHA256 signature using a valid Google Service Account Private Key.
+        # @param [OpenSSL::PKey::RSA, String, Proc] private_key Service Account's
+        #   Private Key or a Proc that accepts a single String parameter and returns a
+        #   RSA SHA256 signature using a valid Google Service Account Private Key.
+        # @param [OpenSSL::PKey::RSA, String, Proc] signer Service Account's
+        #   Private Key or a Proc that accepts a single String parameter and returns a
+        #   RSA SHA256 signature using a valid Google Service Account Private Key.
+        #
+        #   When using this method in environments such as GAE Flexible Environment,
+        #   GKE, or Cloud Functions where the private key is unavailable, it may be
+        #   necessary to provide a Proc (or lambda) via the signer parameter. This
+        #   Proc should return a signature created using a RPC call to the
+        #   [Service Account Credentials signBlob](https://cloud.google.com/iam/docs/reference/credentials/rest/v1/projects.serviceAccounts/signBlob)
+        #   method as shown in the example below.
         # @param [Hash] query Query string parameters to include in the signed
         #   URL. The given parameters are not verified by the signature.
         #
@@ -1478,11 +1491,29 @@ module Google
         #   using the URL, but only when the file resource is missing the
         #   corresponding values. (These values can be permanently set using
         #   {#content_disposition=} and {#content_type=}.)
+        # @param [String] scheme The URL scheme. The default value is `HTTPS`.
+        # @param [Boolean] virtual_hosted_style Whether to use a virtual hosted-style
+        #   hostname, which adds the bucket into the host portion of the URI rather
+        #   than the path, e.g. `https://mybucket.storage.googleapis.com/...`.
+        #   For V4 signing, this also sets the `host` header in the canonicalized
+        #   extension headers to the virtual hosted-style host, unless that header is
+        #   supplied via the `headers` param. The default value of `false` uses the
+        #   form of `https://storage.googleapis.com/mybucket`.
+        # @param [String] bucket_bound_hostname Use a bucket-bound hostname, which
+        #   replaces the `storage.googleapis.com` host with the name of a `CNAME`
+        #   bucket, e.g. a bucket named `gcs-subdomain.my.domain.tld`, or a Google
+        #   Cloud Load Balancer which routes to a bucket you own, e.g.
+        #   `my-load-balancer-domain.tld`.
         # @param [Symbol, String] version The version of the signed credential
         #   to create. Must be one of `:v2` or `:v4`. The default value is
         #   `:v2`.
         #
-        # @return [String]
+        # @return [String] The signed URL.
+        #
+        # @raise [SignedUrlUnavailable] If the service account credentials
+        #   are missing. Service account credentials are acquired by following the
+        #   steps in [Service Account Authentication](
+        #   https://cloud.google.com/iam/docs/service-accounts).
         #
         # @example
         #   require "google/cloud/storage"
@@ -1502,7 +1533,7 @@ module Google
         #   file = bucket.file "avatars/heidi/400x400.png"
         #   shared_url = file.signed_url expires: 300, # 5 minutes from now
         #                                version: :v4
-
+        #
         # @example Using the `issuer` and `signing_key` options:
         #   require "google/cloud/storage"
         #
@@ -1542,28 +1573,85 @@ module Google
         #   # Send the `x-goog-resumable:start` header and the content type
         #   # with the resumable upload POST request.
         #
-        def signed_url method: nil, expires: nil, content_type: nil,
-                       content_md5: nil, headers: nil, issuer: nil,
-                       client_email: nil, signing_key: nil, private_key: nil,
-                       query: nil, version: nil
+        # @example Using Cloud IAMCredentials signBlob to create the signature:
+        #   require "google/cloud/storage"
+        #   require "google/apis/iamcredentials_v1"
+        #   require "googleauth"
+        #
+        #   # Issuer is the service account email that the Signed URL will be signed with
+        #   # and any permission granted in the Signed URL must be granted to the
+        #   # Google Service Account.
+        #   issuer = "service-account@project-id.iam.gserviceaccount.com"
+        #
+        #   # Create a lambda that accepts the string_to_sign
+        #   signer = lambda do |string_to_sign|
+        #     IAMCredentials = Google::Apis::IamcredentialsV1
+        #     iam_client = IAMCredentials::IAMCredentialsService.new
+        #
+        #     # Get the environment configured authorization
+        #     scopes = ["https://www.googleapis.com/auth/iam"]
+        #     iam_client.authorization = Google::Auth.get_application_default scopes
+        #
+        #     request = {
+        #       "payload": string_to_sign,
+        #     }
+        #     resource = "projects/-/serviceAccounts/#{issuer}"
+        #     response = iam_client.sign_service_account_blob resource, request, {}
+        #     response.signed_blob
+        #   end
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-todo-app"
+        #   file = bucket.file "avatars/heidi/400x400.png", skip_lookup: true
+        #   url = file.signed_url method: "GET", issuer: issuer,
+        #                         signer: signer
+        #
+        def signed_url method: "GET",
+                       expires: nil,
+                       content_type: nil,
+                       content_md5: nil,
+                       headers: nil,
+                       issuer: nil,
+                       client_email: nil,
+                       signing_key: nil,
+                       private_key: nil,
+                       signer: nil,
+                       query: nil,
+                       scheme: "HTTPS",
+                       virtual_hosted_style: nil,
+                       bucket_bound_hostname: nil,
+                       version: nil
           ensure_service!
           version ||= :v2
           case version.to_sym
           when :v2
-            signer = File::SignerV2.from_file self
-            signer.signed_url method: method, expires: expires,
-                              headers: headers, content_type: content_type,
-                              content_md5: content_md5, issuer: issuer,
-                              client_email: client_email,
-                              signing_key: signing_key,
-                              private_key: private_key, query: query
+            sign = File::SignerV2.from_file self
+            sign.signed_url method: method,
+                            expires: expires,
+                            headers: headers,
+                            content_type: content_type,
+                            content_md5: content_md5,
+                            issuer: issuer,
+                            client_email: client_email,
+                            signing_key: signing_key,
+                            private_key: private_key,
+                            signer: signer,
+                            query: query
           when :v4
-            signer = File::SignerV4.from_file self
-            signer.signed_url method: method, expires: expires,
-                              headers: headers, issuer: issuer,
-                              client_email: client_email,
-                              signing_key: signing_key,
-                              private_key: private_key, query: query
+            sign = File::SignerV4.from_file self
+            sign.signed_url method: method,
+                            expires: expires,
+                            headers: headers,
+                            issuer: issuer,
+                            client_email: client_email,
+                            signing_key: signing_key,
+                            private_key: private_key,
+                            signer: signer,
+                            query: query,
+                            scheme: scheme,
+                            virtual_hosted_style: virtual_hosted_style,
+                            bucket_bound_hostname: bucket_bound_hostname
           else
             raise ArgumentError, "version '#{version}' not supported"
           end
@@ -1732,7 +1820,7 @@ module Google
           # Sending nil metadata results in an Apiary runtime error:
           # NoMethodError: undefined method `each' for nil:NilClass
           attr_params.reject! { |k, v| k == :metadata && v.nil? }
-          Google::Apis::StorageV1::Object.new attr_params
+          Google::Apis::StorageV1::Object.new(**attr_params)
         end
 
         protected
@@ -1783,12 +1871,12 @@ module Google
                       user_project: user_project }.delete_if { |_k, v| v.nil? }
 
           resp = service.rewrite_file \
-            bucket, name, new_bucket, new_name, updated_gapi, options
+            bucket, name, new_bucket, new_name, updated_gapi, **options
           until resp.done
             sleep 1
             retry_options = options.merge token: resp.rewrite_token
             resp = service.rewrite_file \
-              bucket, name, new_bucket, new_name, updated_gapi, retry_options
+              bucket, name, new_bucket, new_name, updated_gapi, **retry_options
           end
           resp.resource
         end

data/lib/google/cloud/storage/file/list.rb

@@ -77,11 +77,13 @@ module Google
           def next
             return nil unless next?
             ensure_service!
-            options = {
-              prefix: @prefix, delimiter: @delimiter, token: @token, max: @max,
-              versions: @versions, user_project: @user_project
-            }
-            gapi = @service.list_files @bucket, options
+
+            gapi = @service.list_files @bucket, prefix: @prefix,
+                                                delimiter: @delimiter,
+                                                token: @token,
+                                                max: @max,
+                                                versions: @versions,
+                                                user_project: @user_project
             File::List.from_gapi gapi, @service, @bucket, @prefix,
                                  @delimiter, @max, @versions,
                                  user_project: @user_project

data/lib/google/cloud/storage/file/signer_v2.rb

@@ -77,13 +77,21 @@ module Google
           end
 
           def determine_signing_key options = {}
-            options[:signing_key] || options[:private_key] ||
-              @service.credentials.signing_key
+            signing_key = options[:signing_key] || options[:private_key] ||
+                          options[:signer] || @service.credentials.signing_key
+            raise SignedUrlUnavailable, error_msg("signing_key (private_key, signer)") unless signing_key
+            signing_key
           end
 
           def determine_issuer options = {}
-            options[:issuer] || options[:client_email] ||
-              @service.credentials.issuer
+            issuer = options[:issuer] || options[:client_email] || @service.credentials.issuer
+            raise SignedUrlUnavailable, error_msg("issuer (client_email)") unless issuer
+            issuer
+          end
+
+          def error_msg attr_name
+            "Service account credentials '#{attr_name}' is missing. To generate service account credentials " \
+            "see https://cloud.google.com/iam/docs/service-accounts"
           end
 
           def post_object options
@@ -99,8 +107,6 @@ module Google
             i = determine_issuer options
             s = determine_signing_key options
 
-            raise SignedUrlUnavailable unless i && s
-
             policy_str = p.to_json
             policy = Base64.strict_encode64(policy_str).delete "\n"
 
@@ -119,18 +125,21 @@ module Google
             i = determine_issuer options
             s = determine_signing_key options
 
-            raise SignedUrlUnavailable unless i && s
-
             sig = generate_signature s, signature_str(options)
             generate_signed_url i, sig, options[:expires], options[:query]
           end
 
           def generate_signature signing_key, secret
-            unless signing_key.respond_to? :sign
-              signing_key = OpenSSL::PKey::RSA.new signing_key
+            unencoded_signature = ""
+            if signing_key.is_a? Proc
+              unencoded_signature = signing_key.call secret
+            else
+              unless signing_key.respond_to? :sign
+                signing_key = OpenSSL::PKey::RSA.new signing_key
+              end
+              unencoded_signature = signing_key.sign OpenSSL::Digest::SHA256.new, secret
             end
-            signature = signing_key.sign OpenSSL::Digest::SHA256.new, secret
-            Base64.strict_encode64(signature).delete "\n"
+            Base64.strict_encode64(unencoded_signature).delete "\n"
           end
 
           def generate_signed_url issuer, signed_string, expires, query

data/lib/google/cloud/storage/file/signer_v4.rb

@@ -39,37 +39,83 @@ module Google
             new bucket.name, file_name, bucket.service
           end
 
-          def signed_url method: "GET", expires: nil, headers: nil,
-                         issuer: nil, client_email: nil, signing_key: nil,
-                         private_key: nil, query: nil
-            issuer, signer = issuer_and_signer issuer, client_email,
-                                               signing_key, private_key
+          def post_object issuer: nil,
+                          client_email: nil,
+                          signing_key: nil,
+                          private_key: nil,
+                          signer: nil,
+                          expires: nil,
+                          fields: nil,
+                          conditions: nil,
+                          scheme: "https",
+                          virtual_hosted_style: nil,
+                          bucket_bound_hostname: nil
+            i = determine_issuer issuer, client_email
+            s = determine_signing_key signing_key, private_key, signer
+
+            now = Time.now.utc
+            base_fields = required_fields i, now
+            post_fields = fields.dup || {}
+            post_fields.merge! base_fields
+
+            p = {}
+            p["conditions"] = policy_conditions base_fields, conditions, fields
+            expires ||= 60*60*24
+            p["expiration"] = (now + expires).strftime "%Y-%m-%dT%H:%M:%SZ"
+
+            policy_str = escape_characters p.to_json
+
+            policy = Base64.strict_encode64(policy_str).force_encoding "utf-8"
+            signature = generate_signature s, policy
+
+            post_fields["x-goog-signature"] = signature
+            post_fields["policy"] = policy
+            url = post_object_ext_url scheme, virtual_hosted_style, bucket_bound_hostname
+            hostname = "#{url}#{bucket_path path_style?(virtual_hosted_style, bucket_bound_hostname)}"
+            Google::Cloud::Storage::PostObject.new hostname, post_fields
+          end
+
+          def signed_url method: "GET",
+                         expires: nil,
+                         headers: nil,
+                         issuer: nil,
+                         client_email: nil,
+                         signing_key: nil,
+                         private_key: nil,
+                         signer: nil,
+                         query: nil,
+                         scheme: "https",
+                         virtual_hosted_style: nil,
+                         bucket_bound_hostname: nil
+            raise ArgumentError, "method is required" unless method
+            issuer, signer = issuer_and_signer issuer, client_email, signing_key, private_key, signer
             datetime_now = Time.now.utc
             goog_date = datetime_now.strftime "%Y%m%dT%H%M%SZ"
             datestamp = datetime_now.strftime "%Y%m%d"
             # goog4_request is not checked.
             scope = "#{datestamp}/auto/storage/goog4_request"
 
-            canonical_headers_str, signed_headers_str = \
-              canonical_and_signed_headers headers
+            canonical_headers_str, signed_headers_str = canonical_and_signed_headers \
+              headers, virtual_hosted_style, bucket_bound_hostname
 
             algorithm = "GOOG4-RSA-SHA256"
             expires = determine_expires expires
-            credential = CGI.escape issuer + "/" + scope
-            canonical_query_str = canonical_query query, algorithm,
-                                                  credential, goog_date,
-                                                  expires, signed_headers_str
+            credential = issuer + "/" + scope
+            canonical_query_str = canonical_query query, algorithm, credential, goog_date, expires, signed_headers_str
 
             # From AWS: You don't include a payload hash in the Canonical
             # Request, because when you create a presigned URL, you don't know
             # the payload content because the URL is used to upload an arbitrary
             # payload. Instead, you use a constant string UNSIGNED-PAYLOAD.
+            payload = headers&.key?("X-Goog-Content-SHA256") ? headers["X-Goog-Content-SHA256"] : "UNSIGNED-PAYLOAD"
+
             canonical_request = [method,
-                                 ext_path,
+                                 file_path(!(virtual_hosted_style || bucket_bound_hostname)),
                                  canonical_query_str,
                                  canonical_headers_str,
                                  signed_headers_str,
-                                 "UNSIGNED-PAYLOAD"].join("\n")
+                                 payload].join("\n")
+
             # Construct string to sign
             req_sha = Digest::SHA256.hexdigest canonical_request
             string_to_sign = [algorithm, goog_date, scope, req_sha].join "\n"
@@ -78,66 +124,129 @@ module Google
             signature = signer.call string_to_sign
 
             # Construct signed URL
-            "#{ext_url}?#{canonical_query_str}&X-Goog-Signature=#{signature}"
+            hostname = signed_url_hostname scheme, virtual_hosted_style, bucket_bound_hostname
+            "#{hostname}?#{canonical_query_str}&X-Goog-Signature=#{signature}"
+          end
+
+          # methods below are public visibility only for unit testing
+          def escape_characters str
+            str.split("").map do |s|
+              if !s.ascii_only?
+                escape_special_unicode s
+              else
+                case s
+                when "\\"
+                  '\\'
+                when "\b"
+                  '\b'
+                when "\f"
+                  '\f'
+                when "\n"
+                  '\n'
+                when "\r"
+                  '\r'
+                when "\t"
+                  '\t'
+                when "\v"
+                  '\v'
+                else
+                  s
+                end
+              end
+            end.join
+          end
+
+          def escape_special_unicode str
+            str.unpack("U*").map { |i| '\u' + i.to_s(16).rjust(4, "0") }.join
           end
 
           protected
 
+          def required_fields issuer, time
+            {
+              "key" => @file_name,
+              "x-goog-date" => time.strftime("%Y%m%dT%H%M%SZ"),
+              "x-goog-credential" => "#{issuer}/#{time.strftime '%Y%m%d'}/auto/storage/goog4_request",
+              "x-goog-algorithm" => "GOOG4-RSA-SHA256"
+            }.freeze
+          end
+
+          def policy_conditions base_fields, user_conditions, user_fields
+            # Convert each pair in base_fields hash to a single-entry hash in an array.
+            conditions = base_fields.to_a.map { |f| Hash[*f] }
+            # Add the bucket to the head of the base_fields. This is not returned in the PostObject fields.
+            conditions.unshift "bucket" => @bucket_name
+            # Add user-provided conditions to the head of the conditions array.
+            conditions.unshift user_conditions if user_conditions && !user_conditions.empty?
+            if user_fields
+              # Convert each pair in fields hash to a single-entry hash and add it to the head of the conditions array.
+              user_fields.to_a.reverse.each { |f| conditions.unshift Hash[*f] }
+            end
+            conditions.freeze
+          end
+
+          def signed_url_hostname scheme, virtual_hosted_style, bucket_bound_hostname
+            url = ext_url scheme, virtual_hosted_style, bucket_bound_hostname
+            "#{url}#{file_path path_style?(virtual_hosted_style, bucket_bound_hostname)}"
+          end
+
           def determine_issuer issuer, client_email
             # Parse the Service Account and get client id and private key
             issuer = issuer || client_email || @service.credentials.issuer
-            unless issuer
-              raise SignedUrlUnavailable, "issuer (client_email) missing"
-            end
+            raise SignedUrlUnavailable, error_msg("issuer (client_email)") unless issuer
             issuer
           end
 
-          def determine_signing_key signing_key, private_key
-            signing_key = signing_key || private_key ||
-                          @service.credentials.signing_key
-            unless signing_key
-              raise SignedUrlUnavailable, "signing_key (private_key) missing"
-            end
+          def determine_signing_key signing_key, private_key, signer
+            signing_key = signing_key || private_key || signer || @service.credentials.signing_key
+            raise SignedUrlUnavailable, error_msg("signing_key (private_key, signer)") unless signing_key
             signing_key
           end
 
+          def error_msg attr_name
+            "Service account credentials '#{attr_name}' is missing. To generate service account credentials " \
+            "see https://cloud.google.com/iam/docs/service-accounts"
+          end
+
           def service_account_signer signer
-            unless signer.respond_to? :sign
-              signer = OpenSSL::PKey::RSA.new signer
-            end
-            # Sign string to sign
-            lambda do |string_to_sign|
-              sig = signer.sign OpenSSL::Digest::SHA256.new, string_to_sign
-              sig.unpack("H*").first
+            if signer.is_a? Proc
+              lambda do |string_to_sign|
+                sig = signer.call string_to_sign
+                sig.unpack("H*").first
+              end
+            else
+              signer = OpenSSL::PKey::RSA.new signer unless signer.respond_to? :sign
+              # Sign string to sign
+              lambda do |string_to_sign|
+                sig = signer.sign OpenSSL::Digest::SHA256.new, string_to_sign
+                sig.unpack("H*").first
+              end
             end
           end
 
-          def issuer_and_signer issuer, client_email, signing_key, private_key
+          def issuer_and_signer issuer, client_email, signing_key, private_key, signer
             issuer = determine_issuer issuer, client_email
-            signing_key = determine_signing_key signing_key, private_key
+            signing_key = determine_signing_key signing_key, private_key, signer
             signer = service_account_signer signing_key
             [issuer, signer]
           end
 
-          def canonical_and_signed_headers headers
-            # Headers needs to be in alpha order.
+          def canonical_and_signed_headers headers, virtual_hosted_style, bucket_bound_hostname
+            if virtual_hosted_style && bucket_bound_hostname
+              raise "virtual_hosted_style: #{virtual_hosted_style} and bucket_bound_hostname: " \
+                    "#{bucket_bound_hostname} params cannot both be passed together"
+            end
+
             canonical_headers = headers || {}
             headers_arr = canonical_headers.map do |k, v|
-              [k.downcase, v.strip.gsub(/[^\S\t]+/, " ").gsub(/\t+/, "\t")]
+              [k.downcase, v.strip.gsub(/[^\S\t]+/, " ").gsub(/\t+/, " ")]
             end
             canonical_headers = Hash[headers_arr]
-            canonical_headers["host"] = "storage.googleapis.com"
-
-            canonical_headers = canonical_headers.sort_by do |k, _|
-              k.downcase
-            end.to_h
-            canonical_headers_str = ""
-            canonical_headers.each do |k, v|
-              canonical_headers_str += "#{k}:#{v}\n"
-            end
-            signed_headers_str = ""
-            canonical_headers.each_key { |k| signed_headers_str += "#{k};" }
-            signed_headers_str = signed_headers_str.chomp ";"
+            canonical_headers["host"] = host_name virtual_hosted_style, bucket_bound_hostname
+
+            canonical_headers = canonical_headers.sort_by(&:first).to_h
+            canonical_headers_str = canonical_headers.map { |k, v| "#{k}:#{v}\n" }.join
+            signed_headers_str = canonical_headers.keys.join ";"
             [canonical_headers_str, signed_headers_str]
           end
 
@@ -149,32 +258,108 @@ module Google
             expires
           end
 
-          def canonical_query query, algorithm, credential, goog_date, expires,
-                              signed_headers_str
+          def canonical_query query, algorithm, credential, goog_date, expires, signed_headers_str
             query ||= {}
             query["X-Goog-Algorithm"] = algorithm
             query["X-Goog-Credential"] = credential
             query["X-Goog-Date"] = goog_date
             query["X-Goog-Expires"] = expires
-            query["X-Goog-SignedHeaders"] = CGI.escape signed_headers_str
-            query = query.sort_by { |k, _| k.to_s.downcase }.to_h
-            canonical_query_str = ""
-            query.each { |k, v| canonical_query_str += "#{k}=#{v}&" }
-            canonical_query_str.chomp "&"
+            query["X-Goog-SignedHeaders"] = signed_headers_str
+            query = query.map { |k, v| [escape_query_param(k), escape_query_param(v)] }.sort_by(&:first).to_h
+            query.map { |k, v| "#{k}=#{v}" }.join "&"
+          end
+
+          ##
+          # Only the characters in the regex set [A-Za-z0-9.~_-] must be left un-escaped; all others must be
+          # percent-encoded using %XX UTF-8 style.
+          def escape_query_param str
+            CGI.escape(str.to_s).gsub("%7E", "~")
+          end
+
+          def host_name virtual_hosted_style, bucket_bound_hostname
+            return bucket_bound_hostname if bucket_bound_hostname
+            virtual_hosted_style ? "#{@bucket_name}.storage.googleapis.com" : "storage.googleapis.com"
           end
 
           ##
           # The URI-encoded (percent encoded) external path to the file.
-          def ext_path
-            path = "/#{@bucket_name}"
-            path += "/#{String(@file_name)}" if @file_name && !@file_name.empty?
-            Addressable::URI.escape path
+          def file_path path_style
+            path = []
+            path << "/#{@bucket_name}" if path_style
+            path << "/#{String(@file_name)}" if @file_name && !@file_name.empty?
+            CGI.escape(path.join).gsub "%2F", "/"
+          end
+
+          ##
+          # The external path to the bucket, with trailing slash.
+          def bucket_path path_style
+            return "/#{@bucket_name}/" if path_style
+          end
+
+          ##
+          # The external url to the file.
+          def ext_url scheme, virtual_hosted_style, bucket_bound_hostname
+            url = GOOGLEAPIS_URL.dup
+            if virtual_hosted_style
+              parts = url.split "//"
+              parts[1] = "#{@bucket_name}.#{parts[1]}"
+              parts.join "//"
+            elsif bucket_bound_hostname
+              raise ArgumentError, "scheme is required" unless scheme
+              URI "#{scheme.to_s.downcase}://#{bucket_bound_hostname}"
+            else
+              url
+            end
+          end
+
+          def path_style? virtual_hosted_style, bucket_bound_hostname
+            !(virtual_hosted_style || bucket_bound_hostname)
+          end
+
+          ##
+          # The external path to the file, URI-encoded.
+          # Will not URI encode the special `${filename}` variable.
+          # "You can also use the ${filename} variable..."
+          # https://cloud.google.com/storage/docs/xml-api/post-object
+          #
+          def post_object_ext_path
+            path = "/#{@bucket_name}/#{@file_name}"
+            escaped = Addressable::URI.escape path
+            special_var = "${filename}"
+            # Restore the unencoded `${filename}` variable, if present.
+            if path.include? special_var
+              return escaped.gsub "$%7Bfilename%7D", special_var
+            end
+            escaped
           end
 
           ##
           # The external url to the file.
-          def ext_url
-            "#{GOOGLEAPIS_URL}#{ext_path}"
+          def post_object_ext_url scheme, virtual_hosted_style, bucket_bound_hostname
+            url = GOOGLEAPIS_URL.dup
+            if virtual_hosted_style
+              parts = url.split "//"
+              parts[1] = "#{@bucket_name}.#{parts[1]}/"
+              parts.join "//"
+            elsif bucket_bound_hostname
+              raise ArgumentError, "scheme is required" unless scheme
+              URI "#{scheme.to_s.downcase}://#{bucket_bound_hostname}/"
+            else
+              url
+            end
+          end
+
+          def generate_signature signing_key, data
+            packed_signature = nil
+            if signing_key.is_a? Proc
+              packed_signature = signing_key.call data
+            else
+              unless signing_key.respond_to? :sign
+                signing_key = OpenSSL::PKey::RSA.new signing_key
+              end
+              packed_signature = signing_key.sign OpenSSL::Digest::SHA256.new, data
+            end
+            packed_signature.unpack("H*").first.force_encoding "utf-8"
           end
         end
       end