Storage: add support for V4 signed URLs

storage/google/cloud/storage/blob.py

@@ -54,7 +54,8 @@
 from google.api_core.iam import Policy
 from google.cloud.storage._helpers import _PropertyMixin
 from google.cloud.storage._helpers import _scalar_property
-from google.cloud.storage._signing import generate_signed_url
+from google.cloud.storage._signing import generate_signed_url_v2
+from google.cloud.storage._signing import generate_signed_url_v4
 from google.cloud.storage.acl import ACL
 from google.cloud.storage.acl import ObjectACL
 
@@ -96,6 +97,12 @@
 _READ_LESS_THAN_SIZE = (
     "Size {:d} was specified but the file-like object only had " "{:d} bytes remaining."
 )
+_SIGNED_URL_V2_DEFAULT_MESSAGE = (
+    "You have generated a signed URL using the default v2 signing "
+    "implementation. In the future, this will default to v4. "
+    "You may experience breaking changes if you use longer than 7 day "
+    "expiration times with v4. To opt-in to the behavior specify version='v2'."
+)
 
 _DEFAULT_CHUNKSIZE = 104857600  # 1024 * 1024 B * 100 = 100 MB
 _MAX_MULTIPART_SIZE = 8388608  # 8 MB
@@ -302,14 +309,19 @@ def public_url(self):
 
     def generate_signed_url(
         self,
-        expiration,
+        expiration=None,
+        api_access_endpoint=_API_ACCESS_ENDPOINT,
         method="GET",
+        content_md5=None,
         content_type=None,
-        generation=None,
         response_disposition=None,
         response_type=None,
+        generation=None,
+        headers=None,
+        query_parameters=None,
         client=None,
         credentials=None,
+        version=None,
     ):
         """Generates a signed URL for this blob.
 
@@ -332,20 +344,23 @@ def generate_signed_url(
         accessible blobs, but don't want to require users to explicitly
         log in.
 
-        :type expiration: int, long, datetime.datetime, datetime.timedelta
-        :param expiration: When the signed URL should expire.
+        :type expiration: Union[Integer, datetime.datetime, datetime.timedelta]
+        :param expiration: Point in time when the signed URL should expire.
+
+        :type api_access_endpoint: str
+        :param api_access_endpoint: Optional URI base.
 
         :type method: str
         :param method: The HTTP verb that will be used when requesting the URL.
 
+        :type content_md5: str
+        :param content_md5: (Optional) The MD5 hash of the object referenced by
+                            ``resource``.
+
         :type content_type: str
         :param content_type: (Optional) The content type of the object
                              referenced by ``resource``.
 
-        :type generation: str
-        :param generation: (Optional) A value that indicates which generation
-                           of the resource to fetch.
-
         :type response_disposition: str
         :param response_disposition: (Optional) Content disposition of
                                      responses to requests for the signed URL.
@@ -359,6 +374,24 @@ def generate_signed_url(
                               for the signed URL. Used to over-ride the content
                               type of the underlying blob/object.
 
+        :type generation: str
+        :param generation: (Optional) A value that indicates which generation
+                           of the resource to fetch.
+
+        :type headers: dict
+        :param headers:
+            (Optional) Additional HTTP headers to be included as part of the
+            signed URLs.  See:
+            https://cloud.google.com/storage/docs/xml-api/reference-headers
+            Requests using the signed URL *must* pass the specified header
+            (name and value) with each request for the URL.
+
+        :type query_parameters: dict
+        :param query_parameters:
+            (Optional) Additional query paramtersto be included as part of the
+            signed URLs.  See:
+            https://cloud.google.com/storage/docs/xml-api/reference-headers#query
+
         :type client: :class:`~google.cloud.storage.client.Client` or
                       ``NoneType``
         :param client: (Optional) The client to use.  If not passed, falls back
@@ -371,6 +404,11 @@ def generate_signed_url(
                             the URL. Defaults to the credentials stored on the
                             client used.
 
+        :type version: str
+        :param version: (Optional) The version of signed credential to create.
+                        Must be one of 'v2' | 'v4'.
+
+        :raises: :exc:`ValueError` when version is invalid.
         :raises: :exc:`TypeError` when expiration is not a valid type.
         :raises: :exc:`AttributeError` if credentials is not an instance
                 of :class:`google.auth.credentials.Signing`.
@@ -379,6 +417,11 @@ def generate_signed_url(
         :returns: A signed URL you can use to access the resource
                   until expiration.
         """
+        if version is None:
+            version = "v2"
+        elif version not in ("v2", "v4"):
+            raise ValueError("'version' must be either 'v2' or 'v4'")
+
         resource = "/{bucket_name}/{quoted_name}".format(
             bucket_name=self.bucket.name, quoted_name=quote(self.name.encode("utf-8"))
         )
@@ -387,16 +430,24 @@ def generate_signed_url(
             client = self._require_client(client)
             credentials = client._credentials
 
-        return generate_signed_url(
+        if version == "v2":
+            helper = generate_signed_url_v2
+        else:
+            helper = generate_signed_url_v4
+
+        return helper(
             credentials,
             resource=resource,
-            api_access_endpoint=_API_ACCESS_ENDPOINT,
             expiration=expiration,
+            api_access_endpoint=api_access_endpoint,
             method=method.upper(),
+            content_md5=content_md5,
             content_type=content_type,
             response_type=response_type,
             response_disposition=response_disposition,
             generation=generation,
+            headers=headers,
+            query_parameters=query_parameters,
         )
 
     def exists(self, client=None):

storage/google/cloud/storage/bucket.py

@@ -33,8 +33,11 @@
 from google.cloud.storage._helpers import _PropertyMixin
 from google.cloud.storage._helpers import _scalar_property
 from google.cloud.storage._helpers import _validate_name
+from google.cloud.storage._signing import generate_signed_url_v2
+from google.cloud.storage._signing import generate_signed_url_v4
 from google.cloud.storage.acl import BucketACL
 from google.cloud.storage.acl import DefaultObjectACL
+from google.cloud.storage.blob import _SIGNED_URL_V2_DEFAULT_MESSAGE
 from google.cloud.storage.blob import Blob
 from google.cloud.storage.notification import BucketNotification
 from google.cloud.storage.notification import NONE_PAYLOAD_FORMAT
@@ -45,6 +48,7 @@
     "valid before the bucket is created. Instead, pass the location "
     "to `Bucket.create`."
 )
+_API_ACCESS_ENDPOINT = "https://storage.googleapis.com"
 
 
 def _blobs_page_start(iterator, page, response):
@@ -1969,3 +1973,110 @@ def lock_retention_policy(self, client=None):
             method="POST", path=path, query_params=query_params, _target_object=self
         )
         self._set_properties(api_response)
+
+    def generate_signed_url(
+        self,
+        expiration=None,
+        api_access_endpoint=_API_ACCESS_ENDPOINT,
+        method="GET",
+        headers=None,
+        query_parameters=None,
+        client=None,
+        credentials=None,
+        version=None,
+    ):
+        """Generates a signed URL for this bucket.
+
+        .. note::
+
+            If you are on Google Compute Engine, you can't generate a signed
+            URL using GCE service account. Follow `Issue 50`_ for updates on
+            this. If you'd like to be able to generate a signed URL from GCE,
+            you can use a standard service account from a JSON file rather
+            than a GCE service account.
+
+        .. _Issue 50: https://github.com/GoogleCloudPlatform/\
+                      google-auth-library-python/issues/50
+
+        If you have a bucket that you want to allow access to for a set
+        amount of time, you can use this method to generate a URL that
+        is only valid within a certain time period.
+
+        This is particularly useful if you don't want publicly
+        accessible buckets, but don't want to require users to explicitly
+        log in.
+
+        :type expiration: Union[Integer, datetime.datetime, datetime.timedelta]
+        :param expiration: Point in time when the signed URL should expire.
+
+        :type api_access_endpoint: str
+        :param api_access_endpoint: Optional URI base.
+
+        :type method: str
+        :param method: The HTTP verb that will be used when requesting the URL.
+
+        :type headers: dict
+        :param headers:
+            (Optional) Additional HTTP headers to be included as part of the
+            signed URLs.  See:
+            https://cloud.google.com/storage/docs/xml-api/reference-headers
+            Requests using the signed URL *must* pass the specified header
+            (name and value) with each request for the URL.
+
+        :type query_parameters: dict
+        :param query_parameters:
+            (Optional) Additional query paramtersto be included as part of the
+            signed URLs.  See:
+            https://cloud.google.com/storage/docs/xml-api/reference-headers#query
+
+        :type client: :class:`~google.cloud.storage.client.Client` or
+                      ``NoneType``
+        :param client: (Optional) The client to use.  If not passed, falls back
+                       to the ``client`` stored on the blob's bucket.
+
+
+        :type credentials: :class:`oauth2client.client.OAuth2Credentials` or
+                           :class:`NoneType`
+        :param credentials: (Optional) The OAuth2 credentials to use to sign
+                            the URL. Defaults to the credentials stored on the
+                            client used.
+
+        :type version: str
+        :param version: (Optional) The version of signed credential to create.
+                        Must be one of 'v2' | 'v4'.
+
+        :raises: :exc:`ValueError` when version is invalid.
+        :raises: :exc:`TypeError` when expiration is not a valid type.
+        :raises: :exc:`AttributeError` if credentials is not an instance
+                of :class:`google.auth.credentials.Signing`.
+
+        :rtype: str
+        :returns: A signed URL you can use to access the resource
+                  until expiration.
+        """
+        if version is None:
+            version = "v2"
+            warnings.warn(DeprecationWarning(_SIGNED_URL_V2_DEFAULT_MESSAGE))
+        elif version not in ("v2", "v4"):
+            raise ValueError("'version' must be either 'v2' or 'v4'")
+
+        resource = "/{bucket_name}".format(bucket_name=self.name)
+
+        if credentials is None:
+            client = self._require_client(client)
+            credentials = client._credentials
+
+        if version == "v2":
+            helper = generate_signed_url_v2
+        else:
+            helper = generate_signed_url_v4
+
+        return helper(
+            credentials,
+            resource=resource,
+            expiration=expiration,
+            api_access_endpoint=api_access_endpoint,
+            method=method.upper(),
+            headers=headers,
+            query_parameters=query_parameters,
+        )