CipherStash Documentation


Device Code authentication

When running CipherStash interactively, most likely when you are doing local development, you can authenticate with CipherStash using device code authentication.

To connect to CipherStash and authenticate, use Stash.connect().

import { Stash } from "@cipherstash/stashjs";

const stash = await Stash.connect();

Pass a profileName option to load a specific profile from ~/.cipherstash.

For example

import { Stash } from "@cipherstash/stashjs";

const stash = await Stash.connect({ profileName: "dev-local" });

Or instead of stating the profile name to load everytime, you can set a profile name in an environment variable CS_PROFILE_NAME.

Stash.connect() will always load that profile.

If you don’t specify a profile name option, or have an environment profile set, Stash.connect() will load the profile in this folder ~/.cipherstash/default.

When Stash.connect() is run, you will be redirected to your browser to log in.

Once you have completed the log in steps you will now be able to use the stash client.

Machine to Machine authentication

To connect to CipherStash programmatically (i.e in Production or CI), you will need to use a CipherStash access key.

To generate an access key follow the instructions here.

Then set the below environment variables.

Ensure that these are the only environment variables set for CipherStash. You will find these environment variable values in the profile you created the access key for, in this location ~/.cipherstash/<profile>/profile-config.json.

You can read more about these configuration options here

  • CS_SERVICE_FQDN: This is the fqdn (fully qualified domain name) of the CipherStash service in which this workspace exists.

    The default is To check what fqdn your workspace exists in, you can check your profile set in ~/.cipherstash/<profile>/profile-config.json,

  • CS_WORKSPACE: The id of the workspace the access key is for.

  • CS_IDP_CLIENT_SECRET: The CipherStash access key you created.

  • CS_KMS_KEY_ARN: Set in ~/.cipherstash/<profile>/profile-config.json, keyManagement.key.arn.

  • CS_NAMING_KEY: Set in ~/.cipherstash/<profile>/profile-config.json, keyManagement.key.namingKey.

  • CS_KMS_KEY_REGION: Set in ~/.cipherstash/<profile>/profile-config.json, keyManagement.key.region.

For CipherStash managed KMS keys add the below:

  • CS_AWS_REGION: Set in ~/.cipherstash/<profile>/profile-config.json, keyManagement.awsCredentials.region.

  • CS_KMS_FEDERATION_ROLE_ARN: Set in ~/.cipherstash/<profile>/profile-config.json, keyManagement.awsCredentials.roleArn

If you are managing your own KMS keys add these environment variables:

  • CS_AWS_ACCESS_KEY_ID: Set in ~/.cipherstash/<profile>/profile-config.json, keyManagement.awsCredentials.accessKeyId

  • CS_AWS_SECRET_ACCESS_KEY: Set in ~/.cipherstash/<profile>/profile-config.json, keyManagement.awsCredentials.secretAccessKey

Load profile using environment variables

To authenticate using these environment variables use Stash.loadProfileFromEnv(). This will create a stash profile to pass to Stash.connect()

import { Stash } from "@cipherstash/stashjs";

const profile = Stash.loadProfileFromEnv();

const stash = await Stash.connect(profile);