GCSSign (GCSSign v1.0.0) View Source

GCSSign helps signing URLs and HTTP form requests for Google Cloud Storage.

Examples

Signing URLs

# Use a service account key
credentials = "GCP_CREDENTIALS" |> System.fetch_env!() |> Jason.decode!()

# Sign a simple URL
sign_opts = [bucket: "demo-bucket", key: "test.txt"]
url = GCSSign.sign_url_v4(credentials, sign_opts)

# Sign a URL with custom expiration time
sign_opts = [bucket: "demo-bucket", key: "test.txt", expires_in: 60]
url = GCSSign.sign_url_v4(credentials, sign_opts)

# Sign a URL with custom headers
headers = [
  # Or use https://hex.pm/packages/content_disposition
  # {"response-content-disposition", ContentDisposition.format(disposition: :attachment, filename: "file.txt")},
  {"response-content-disposition", "inline; filename=\"file.txt\"; filename*=UTF-8''file.txt"},
  {"response-content-type", "text/plain"}
]
sign_opts = [bucket: "demo-bucket", key: "test.txt", expires_in: 60]
url = GCSSign.sign_url_v4(credentials, sign_opts)

Signing XML POST Policies

Signed POST policies can be used to allow external parties limited upload access to a bucket. A policy document can be used to limit in which bucket, with what key a file can be uploaded, and it supports setting file-size limits.

GCSSign.sign_post_policy_v4/2 can be used to sign a POST policy. It requires a bucket and key and returns a map with a URL and a map of fields that should be passed as parameters in the upload request.

Google's documentation describes how this can be used to perform a multipart upload.

# Use a service account key
credentials = "GCP_CREDENTIALS" |> System.fetch_env!() |> Jason.decode!()

# Sign a simple URL
sign_opts = [
  expires_in: 600,
  bucket: "demo-bucket",
  key: "test.txt",
  fields: %{
    "content-type" => "text/plain",
    "cache-control" => "public, max-age=31536000"
  },
  conditions: [["content-length-range", 0, 2_000_000]]
]

{:ok, policy} = GCSSign.sign_post_policy_v4(credentials, sign_opts)

Authorizer options

Google Cloud Storage accepts two different options for passing the credential scope's authorizer:

  • client_id: The ID of the service account key
  • client_email: The service account email

GCSSign will use the client_id by default because it exposes the least information when used in XML POST with HTML forms. You can optionally set authorizer: :client_email in sign_opts to make the credential scope use client_email.

Read more about authorizer in Google's documentation

Link to this section Summary

Link to this section Types

Specs

authorizer() :: :client_id | :client_email

Specs

common_option() ::
  {:method, http_verb()}
  | {:authorizer, authorizer()}
  | {:expires_in, non_neg_integer()}
  | {:bucket, String.t()}
  | {:path, String.t()}
  | {:key, String.t()}
  | {:utc_now, Calendar.datetime()}

Specs

condition() :: term()

Specs

credentials() :: %{required(String.t()) => term()}

Specs

headers() :: [{String.t(), String.t()}]

Specs

http_verb() :: atom() | String.t()

Specs

post_policy_option() :: {:conditions, [condition()]} | {:fields, map()}

Specs

query() :: [{String.t() | atom(), String.t()}]

Specs

signed_policy() :: %{url: String.t(), fields: map()}

Specs

url_option() ::
  {:payload, String.t() | nil}
  | {:host, String.t()}
  | {:query, query()}
  | {:headers, headers()}

Link to this section Functions

Link to this function

sign_post_policy_v4(credentials, sign_opts)

View Source

Specs

sign_post_policy_v4(credentials(), [common_option() | post_policy_option()]) ::
  {:ok, signed_policy()}

Signs a POST policy

Signed POST policies can be used to allow external parties limited upload access to a bucket. A policy document can be used to limit in which bucket, with what key a file can be uploaded, and it supports setting file-size limits.

Google's documentation describes how this can be used to perform a multipart upload.

Options

  • :bucket - String.t() - The name of the GCS bucket.
  • :key - The key to the file in the bucket, without leading slash.
  • :method - The key to the file in the bucket, without leading slash. Default: "GET"
Link to this function

sign_url_v4(credentials, sign_opts)

View Source

Specs

sign_url_v4(credentials(), [common_option() | url_option()]) :: String.t()