CipherStash
CipherStash Documentation

Client Configuration

Your CipherStash client needs configuration to work. To suit different use cases, this configuration can be specified in a variety of ways, including:

  • Configuration files
  • Environment variables
  • Being passed directly to the client library

This page describes these different methods, which methods take precedence over others, and all available configuration options in their various forms.

Configuration Methods and Precedence

For each configuration parameter, the following locations are examined to determine its value. CipherStash will use the the first location that provides a value.

  1. CLI / client constructor argument: if a configuration parameter is passed directly to the CLI or client constructor, that overrides all other sources of information.

  2. Environment variable: each configuration parameter has a corresponding environment variable. This is particularly suited to configuring your deployed application, or in CI environments, where other methods of configuration may be less convenient.

  3. Configuration file: stored under ~/.cipherstash, configuration files store JSON objects that are parsed to determine configuration parameter values. Some configuration is user-level (such as the default profile name), while most configuration parameters are set on a per-profile basis. The description of each configuration parameter lists the file and the JSON “path” which is examined.

  4. Service-provided configuration: some configuration parameters can be supplied by the CipherStash service itself. These are non-sensitive values that are typically required to be the same for all clients using a given workspace.

Configuration Parameters

Detailed below are all configuration parameters which are accepted by CipherStash. The name of the parameter is used both as the CLI option name, and the parameter in the client constructor. For example, a parameter named fooBar would be specified on the command line as --fooBar, and in the StashJS client constructor as Stash.connect({fooBar: "XXX"}).

configPath

  • Environment variable: CS_CONFIG_PATH
  • Type: String
  • Default: ~/.cipherstash
  • Only accepted via the environment variable or client constructor argument (cannot be set in a config file)

The path of the directory where all CipherStash configuration files are located. This directory contains profiles and user-level configuration. Each profile is stored in a directory that is named after the profile, <configPath>/<profile>/. User-level configuration is stored in <configPath>/config.json.

If configPath is explicitly set (either via the environment variable or constructor argument), the client will raise an error if the directory does not exist. However, the directory does not have to exist (for example, in a CI or production environment) when the default is used.

profileName

  • Environment variable: CS_PROFILE_NAME
  • Type: String
  • Default: default
  • Set in ~/.cipherstash/config.json, defaultProfile

The name of the CipherStash profile to load configuration parameters from. All configuration parameters except for profileName and configPath can be set in a profile.

If a profileName is explicitly set (either via the environment variable, constructor argument, or the defaultProfile property in ~/.cipherstash/config.json), the client will raise an error if the profile does not exist. If profileName is not set, the CipherStash client will attempt to load configuration from a profile named default. The default profile is not required to exist (for example, in a CI or production environment).

workspace

  • Environment variable: CS_WORKSPACE
  • Type: String
  • Set in ~/.cipherstash/<profile>/profile-config.json, service.workspace

The ID of the workspace to use. This must be a workspace to which you have been granted access, otherwise — unsurprisingly — your connection attempts will fail. This workspace ID will have been provided for you when you signed up. Contact CipherStash support if you need to recover it.

serviceFqdn

  • Environment variable: CS_SERVICE_FQDN
  • Type: String
  • Default: ap-southeast-2.aws.stashdata.net
  • Set in ~/.cipherstash/<profile>/profile-config.json, service.host

The FQDN of the CipherStash service in which your workspace exists.

servicePort

  • Environment variable: CS_SERVICE_PORT
  • Type: Integer, 1 - 65,535
  • Default: 443
  • Set in ~/.cipherstash/<profile>/profile-config.json, service.port

The TCP port of the CipherStash service in which your workspace exists.

serviceTrustAnchor

  • Environment variable: CS_SERVICE_TRUST_ANCHOR
  • Type: String (PEM-formatted X.509 certificate(s))
  • Default: unset
  • Set in ~/.cipherstash/<profile>/profile-config.json, service.trustAnchor

The issuing Certificate Authority (or Authorities) which are trusted to issue TLS certificates for the service named in serviceName. If left unset (the default), then a built-in set of trust anchors will be used, which is suitable for practically all standard usage. Multiple X.509 certificates can be specified by concatenating all the PEM-formatted X.509 certificates together, ensuring that there is a newline between the END CERTIFICATE and BEGIN CERTIFICATE lines of each certificate.

idpHost

  • Environment variable: CS_IDP_HOST
  • Type: String (URL)
  • Default: https://auth.cipherstash.com/
  • Set in ~/.cipherstash/<profile>/profile-config.json, identityProvider.host

The URL of the Identity Provider (IdP) to use to obtain an access token for the CipherStash service.

idpClientId

  • Environment variable: CS_IDP_CLIENT_ID
  • Type: String
  • Default: CtY9DNGongoSvZaAwbb6sw0Hr7Gl7pg7 (when also using the default idpHost)
  • Set in ~/.cipherstash/<profile>/profile-config.json, identityProvider.clientId

When running CipherStash in an interactive environment (such as development) and using device code authorization, you need to provide a client ID. Typically, the client ID will be provided for you and you will not need to change the default value.

idpClientSecret

  • Environment variable: CS_IDP_CLIENT_SECRET
  • Type: String
  • Set in ~/.cipherstash/<profile>/profile-config.json, identityProvider.clientSecret

When running CipherStash in a non-interactive environment (such as production or CI), you need to present a client secret in order to get an access token. You can get a client secret to use for your workspace by following these steps.

accessToken

  • Environment variable: CS_ACCESS_TOKEN
  • Type: String
  • Set in ~/.cipherstash/<profile>/profile-config.json, identityProvider.accessToken

In certain circumstances, it may be necessary to obtain an access token via out-of-band mechanisms and pass it directly into CipherStash. However, as access tokens expire, this is not recommended for general-purpose use.

kmsKeyArn

  • Environment variable: CS_KMS_KEY_ARN
  • Type: String
  • Set in ~/.cipherstash/<profile>/profile-config.json, keyManagement.key.arn
  • Service-provided configuration item

The ARN or ID of the AWS KMS key that is being used to encrypt all data in CipherStash. You should not ordinarily have to set this yourself, as CipherStash will obtain the KMS key ARN for the given workspace from CipherStash itself.

kmsKeyRegion

  • Environment variable: CS_KMS_KEY_REGION
  • Type: String
  • Set in ~/.cipherstash/<profile>/profile-config.json, keyManagement.key.region
  • Service-provided configuration item

The AWS region in which the specified KMS key resides. You should not ordinarily have to set this yourself, as CipherStash will obtain the KMS key region for the given workspace from CipherStash itself.

localKey

  • Environment variable: CS_LOCAL_KEY
  • Type: String (32 hex characters)
  • Set in ~/.cipherstash/<profile>/profile-config.json, keyManagement.key.key

If you wish to use a locally-specified wrapping key for your CipherStash data, rather than a KMS key, you can do so by specifying it as a hex-encoded string. Note that using a local key, rather than a KMS key, leaves the key vulnerable to exfiltration or other persistent compromise.

A local key should be created from the output of a cryptographically-secure random number generator. It must be specified as 32 hex characters, which are then decoded into the 16 octets used by the cryptographic library.

namingKey

  • Environment variable: CS_NAMING_KEY
  • Type: String
  • Set in ~/.cipherstash/<profile>/profile-config.json, keyManagement.key.namingKey
  • Service-provided configuration item

All collection names in CipherStash are encrypted using this symmetric key. This key is itself encrypted using the KMS key specified by kmsKeyArn.

kmsFederationRoleArn

  • Environment variable: CS_KMS_FEDERATION_ROLE_ARN
  • Type: String
  • Set in ~/.cipherstash/<profile>/profile-config.json, keyManagement.awsCredentials.roleArn
  • Service-provided configuration item

The role ARN to use to federate to AWS in order to get access credentials for the KMS key. AWS Federation is only used when you’re running in local development (interactive) mode, and with a CipherStash-managed KMS key.

awsAccessKeyId

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

The access key ID that is needed to use the KMS key which encrypts all CipherStash data. This is needed when you’re using your own KMS key, or when your application is running non-interactively (in production or CI). For CipherStash-managed KMS keys, you can get an access key ID by contacting the CipherStash support team.

See also: Why doesn’t CipherStash use the standard AWS environment variables?

awsSecretAccessKey

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

The secret access key that is needed to use the KMS key which encrypts all CipherStash data. This is needed when you’re using your own KMS key, or when your application is running non-interactively (in production or CI). For CipherStash-managed KMS keys, you can get a secret access key by contacting the CipherStash support team.

See also: Why doesn’t CipherStash use the standard AWS environment variables?

awsRegion

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

The region in which authentication operations should be performed. In almost every case, this should be the same as the KMS key region.

See also: Why doesn’t CipherStash use the standard AWS environment variables?