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"}).

profileName

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

The name of the CipherStash profile to load all other configuration parameters from. If you only have one profile defined (that is, only one subdirectory under ~/.cipherstash), then you do not need to use this configuration parameter, and the defined profile will be used by default. Otherwise, you must specify the profile to use.

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
  • Set in ~/.cipherstash/<profile>/profile-config.json, identityProvider.clientId

This is an internal parameter that the IdP uses during authentication. The default is suitable for interactive (”device code”) authentication typically used during development. You will be provided with another client ID by the CipherStash support team when you’re deploying your application.

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 ID and a client secret in order to get an access token. You can get a client ID and client secret to use for your workspace by contacting the CipherStash support team.

accessToken

  • Environment variable: CS_ACCESS_TOKEN
  • Type: String
  • Set in ~/.cipherstash/<profile>/auth-token.json, 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.

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?