HMAC keys

Setup

This page discusses hash-based message authentication code (HMAC) keys, which you can use to authenticate requests to the Cloud Storage XML API. HMAC keys are useful when you want to move data between other cloud storage providers and Cloud Storage, because HMAC keys allow you to reuse your existing code to access Cloud Storage.

Overview

An HMAC key is a type of credential associated with an account, typically a service account. You use an HMAC key to create signatures using the HMAC-SHA256 signing algorithm. The signatures you create are then included in requests to the Cloud Storage XML API. Signatures show that a given request is authorized by the account associated with the HMAC key.

HMAC keys have two primary pieces, an access ID and a secret.

  • Access ID: An alphanumeric string linked to a specific account.

    • When linked to a service account, the string is 61 characters in length.

    The following shows an example of an access ID:

    GOOGTS7C7FUP3AIRVJTE2BCDKINBTES3HC2GY5CBFJDCQ2SYHV6A6XXVTJFSA

  • Secret: A 40-character Base-64 encoded string that is linked to a specific access ID. A secret is a pre-shared key that only you and Cloud Storage know. You use your secret to create signatures as part of the authentication process. The following shows an example of a secret:

    bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ

Both the access ID and secret uniquely identify an HMAC key, but the secret is much more sensitive information, because it's used to create signatures.

You can optionally enable the restrictAuthTypes constraint on a resource, which restricts access for requests signed by HMAC keys.

Storing secrets

When you create an HMAC key for a service account, you are given the secret for the key once. You must securely store the secret, along with the associated access ID. If you lose the secret, it cannot be retrieved by you or Trusted Cloud by S3NS, and you must create a new HMAC key for the service account to continue authenticating requests.

Best practices for storing secrets

  • Do not share your HMAC key secret. You should treat HMAC key secrets as you would any set of access credentials.

  • As a security best practice, you should regularly change your keys as part of a key rotation.

  • If you think someone else is using your HMAC keys, you should immediately delete the affected HMAC keys and create new ones.

  • When changing HMAC keys, you should update your code with the new HMAC keys before you delete the old keys. When you delete HMAC keys, they become immediately invalid, and they are not recoverable.

Restrictions

  • HMAC keys can only be used to make requests to the XML API, not the JSON API.

  • You can have a maximum of 10 HMAC keys per service account. Deleted keys do not count towards this limit.

  • After creation, it can take up to 60 seconds for a service account HMAC key to become useable. After deleting a service account, the HMAC keys that belong to it might continue to work for up to 5 minutes. Conversely, it can take up to 5 minutes for HMAC keys to become usable again after undeleting the service account that owns them.

  • If you enable the restrictAuthTypes constraint on a resource, you can no longer create or activate HMAC keys for the specified account type in that resource.

What's next