Guides
Home
Home

How to Use API Key Credentials

Step-by-step instructions for using API Key Credentials

Introduction

How are API Key Credentials used? Ubiq uses credentials that provide two specific tasks for the Ubiq Client Libraries:

  1. Provide authentication and authorization of the Ubiq Client Library to work with the Application Master Keys stored in the Ubiq Cloud
  2. Create a secure private tunnel connection between the Ubiq Client Library and the Ubiq Cloud Key Storage to ensure integrity and prevent eavesdropping

Therefore, API Key Credentials need to be supplied to the Ubiq Client Libraries. There are four ways in which to supply these credentials:

  1. Explicitly set the credentials
  2. Using environment variables
  3. Loading from a specific credentials file
  4. Loading from the default credentials file

Instructions for Supplying API Key Credentials to Ubiq Client Libraries

A. Production and Production-Like Use

❗️

In a production deployment, it is critical to maintain the secrecy of Ubiq API Key Credentials (SECRET_CRYPTO_ACCESS_KEY and SECRET_SIGNING_KEY) and API tokens (ACCESS_KEY_ID).

These items SHOULD be stored in a secrets management server or password vault. They should NOT be stored in a standard data file, embedded in source code, committed to a source code repository, or insecurely used in environmental variables.

After API Key Credentials are obtained from the security server or vault by the client application, the Ubiq API Key Credential values can then be passed to the Credentials() function as strings. This is illustrated in the code example below.

credentials = Credentials(access_key_id = obtainAccessKeyID(), secret_signing_key = obtainSecretSigningKey(), secret_crypto_access_key=obtainSecretCryptoAccessKey())

B. Development Use

During initial development of an application, it may be desirable to use a simpler, insecure mechanism to store Ubiq API Key Credentials. The sections below provide some examples.

1. Explicitly Set the API Key Credentials in Source Code

To explicitly set the credential parameters, pass the values in when initializing the credentials objects.

Example:

# This example is for development use only - Storing Ubiq API Key Credentials in source code is INSECURE!
credentials = ubiq.credentials(access_key_id = "...", secret_signing_key = "...", secret_crypto_access_key = "...")

# This example is for development use only - Storing Ubiq API Key Credentials in source code is INSECURE!
credentials = Credentials(access_key_id = "...", secret_signing_key = "...", secret_crypto_access_key = "...")

// This example is for development use only - Storing Ubiq API Key Credentials in source code is INSECURE!
const credentials = new Credentials('<access_key_id>', '<secret_signing_key>', '<secret_crypto_access_key>')

/* This example is for development use only - Storing Ubiq API Key Credentials in source code is INSECURE!*/
struct ubiq_platform_credentials * credentials;

ubiq_platform_credentials_create_explicit(
    "..." /* access key id */,
    "..." /* secret signing key */,
    "..." /* secret crypto access key */,
    "..." /* Ubiq API server, may be NULL */,
    &credentials);

/* This example is for development use only - Storing Ubiq API Key Credentials in source code is INSECURE!*/
ubiq::platform::credentials credentials(
    "..." /* access key id */,
    "..." /* secret signing key */,
    "..." /* secret crypto access key */,
    "..." /* Ubiq API server, may be unspecified */);

// This example is for development use only - Storing Ubiq API Key Credentials in source code is INSECURE!
var credentials = UbiqFactory.CreateCredentials(accessKeyId: "...", secretSigningKey: "...", secretCryptoAccessKey: "...");

// This example is for development use only - Storing Ubiq API Key Credentials in source code is INSECURE!
UbiqCredentials credentials = UbiqFactory.createCredentials("<yourAccessKey>", "<yourSigningKey>", "<yourCryptoKey>", null);

/* This example is for development use only - Storing Ubiq API Key Credentials in source code is INSECURE!*/
credentials, err := ubiq.NewCredentials(
        "..." /* access key id */,
        "..." /* secret signing key */,
        "..." /* secret crypto access key */,
        "..." /* Ubiq API server, may omit this parameter */)

/* This example is for development use only - Storing Ubiq API Key Credentials in source code is INSECURE!*/
$credentials = new Ubiq\Credentials();
$credentials->set(
    '...' /* access key id */,
    '...' /* secret signing key */,
    '...' /* secret crypto access key */,
    '...' /* Ubiq API server, may omit this parameter */
);

2. Using Environment Variables

The library can look for environment variables for the necessary credentials. The following environment variable values are used to pass the credential information to the client library.

UBIQ_ACCESS_KEY_ID
UBIQ_SECRET_SIGNING_KEY
UBIQ_SECRET_CRYPTO_ACCESS_KEY

Example:

# This example is for development use only - Storing Ubiq API Key Credentials in environmental variables is not generally recommended
credentials = ubiq.credentials()

# This example is for development use only - Storing Ubiq API Key Credentials in environmental variables is not generally recommended
credentials = Credentials()

// This example is for development use only - Storing Ubiq API Key Credentials in environmental variables is not generally recommended
const credentials = new ubiq.Credentials()

/* This example is for development use only - Storing Ubiq API Key Credentials in environmental variables is not generally recommended */
struct ubiq_platform_credentials * credentials;

ubiq_platform_credentials_create(&credentials);

/* This example is for development use only - Storing Ubiq API Key Credentials in environmental variables is not generally recommended */
ubiq::platform::credentials credentials;

// This example is for development use only - Storing Ubiq API Key Credentials in environmental variables is not generally recommended
var credentials = UbiqFactory.CreateCredentials()

// This example is for development use only - Storing Ubiq API Key Credentials in environmental variables is not generally recommended
UbiqCredentials credentials = UbiqFactory.createCredentials(null, null, null, null);

/* This example is for development use only - Storing Ubiq API Key Credentials in environmental variables is not generally recommended */
credentials, err := ubiq.NewCredentials()

/* This example is for development use only - Storing Ubiq API Key Credentials in environmental variables is not generally recommended */
$credentials = new Ubiq\Credentials();

If both environment variables and explicit values are passed in, the explicit values will have priority.

Credentials File Format

The credentials file can support many sets of different credentials. This is accomplished by supporting
different profile sections within the credentials file.

[default]
ACCESS_KEY_ID = .somevalues..
SECRET_SIGNING_KEY = .somevalues..
SECRET_CRYPTO_ACCESS_KEY =.somevalues.. 

[profile1]
ACCESS_KEY_ID = .somevalues..
SECRET_SIGNING_KEY = .somevalues..
SECRET_CRYPTO_ACCESS_KEY =.somevalues.. 

[profile2]
ACCESS_KEY_ID = .somevalues..
SECRET_SIGNING_KEY = .somevalues..
SECRET_CRYPTO_ACCESS_KEY =.somevalues..

3. Read Credentials from a Specific File

The following example demonstrates how to load Credentials from a user supplied Credentials file. If the profile parameter is supplied, then data in that profile will be used if it is found, otherwise, the library uses the values in default profile if they exist.

Example:

# This example is for development use only - Storing Ubiq API Key Credentials in a file is not recommended
credentials = ubiq.configCredentials(config_file = "some-credential-file", profile = "some-profile")

# This example is for development use only - Storing Ubiq API Key Credentials in a file is not recommended
credentials = ConfigCredentials.new( "some-credential-file", "some-profile").get_attributes

// This example is for development use only - Storing Ubiq API Key Credentials in a file is not recommended
const credentials = new ubiq.ConfigCredentials(credentials_file, profile)

/* This example is for development use only - Storing Ubiq API Key Credentials in a file is not recommended */
struct ubiq_platform_credentials * credentials;

ubiq_platform_credentials_create_specific(
    "/path/to/credentials", "profile-name", &credentials);

/* This example is for development use only - Storing Ubiq API Key Credentials in a file is not recommended */
ubiq::platform::credentials credentials(
    "/path/to/credentials", "profile-name");

// This example is for development use only - Storing Ubiq API Key Credentials in a file is not recommended
var credentials = UbiqFactory.ReadCredentialsFromFile("some-credential-file", "some-profile");

// This example is for development use only - Storing Ubiq API Key Credentials in a file is not recommended
UbiqCredentials credentials = UbiqFactory.readCredentialsFromFile("some-credential-file", "some-profile");

/* This example is for development use only - Storing Ubiq API Key Credentials in a file is not recommended */
credentials, err := ubiq.NewCredentials(
        "/path/to/credentials", "profile-name")

/* This example is for development use only - Storing Ubiq API Key Credentials in a file is not recommended */
$credentials = new Ubiq\Credentials();
$credentials->load(
    '/path/to/credentials', 'profile-name'
);

4. Read Credentials from Default (~/.ubiq/credentials) File

If the config_file parameter is not supplied, then the Client Library will look in the ~/.ubiq directory for the credentials file. If the profile parameter isn't supplied, then the library will assume default.

Example:

# This example is for development use only - Storing Ubiq API Key credentials in a file is not recommended
credentials = ubiq.configCredentials()

# This example is for development use only - Storing Ubiq API Key credentials in a file is not recommended
credentials = ConfigCredentials.new().get_attributes

// This example is for development use only - Storing Ubiq API Key credentials in a file is not recommended
const credentials = new ubiq.ConfigCredentials()

/* This example is for development use only - Storing Ubiq API Key credentials in a file is not recommended */
struct ubiq_platform_credentials * credentials;

ubiq_platform_credentials_create(&credentials);

/* This example is for development use only - Storing Ubiq API Key credentials in a file is not recommended */
ubiq::platform::credentials credentials;

// This example is for development use only - Storing Ubiq API Key credentials in a file is not recommended
var credentials = UbiqFactory.ReadCredentialsFromFile(string.Empty, null);

// This example is for development use only - Storing Ubiq API Key credentials in a file is not recommended
UbiqCredentials credentials = UbiqFactory.readCredentialsFromFile("", "default");

/* This example is for development use only - Storing Ubiq API Key credentials in a file is not recommended */
credentials, err := ubiq.NewCredentials()

/* This example is for development use only - Storing Ubiq API Key credentials in a file is not recommended */
$credentials = new Ubiq\Credentials();

Updated 8 months ago

© 2022 Ubiq Security, Inc. All rights reserved.