Skip to main content

Vendor Settings

If you are configuring an Antimatter domain for someone else's use (e.g. if you are a SaaS vendor using Antimatter to provide Bring Your Own Key encryption functionality to your customers), you will want to use the Vendor Settings configuration to control the available options during self-serve key configuration.

Using Vendor Settings in a customer domain lets you:

  • Configure the name and support email of the vendor (this is shown in some contexts in the web UI)
  • Mark a root encryption key as "managed" by the vendor
  • Disable certain features in the customer domain.

At the time of writing, the only feature that can be controlled through the vendor settings is the ability to hold your own key (e.g. configure an externally held root encryption key), but contact us if you have a use case that would benefit from an extension to the vendor settings.

Vendor contact information​

A vendor name and email address can be configured in the Vendor Settings which will be used throughout the web UI to customize branding and end-user experience.

You may update these fields in the Vendor Settings using the CLI, for example:

am domain vendor-settings update \
  --name "Vendor Company" \
  --support-contact "support@vendor.com"

You can view the current vendor-settings with

am domain vendor-settings list

name: Vendor Company
supportContact: support@vendor.com
...

Managed Key ID​

In some cases, a vendor may want to manage a key on behalf of their customers. A newly created Antimatter domain has a default key managed by Antimatter. In some cases, a vendor may want to manage a key on behalf of a customer, as an alternative to a customer holding a key themselves or Antimatter holding the key.

One option is to simply add a root encryption key to the customer domain. For convenience, we've also built in a way to indicate that this key is one managed and recommended by the vendor. This is particularly valuable in the context of the self-serve key onboarding UI, where this key should be presented along side other options like holding your own key, bringing your own key, or using the Antimatter-held default. Another option is to import the key from a different domain.

You can set any non-default key ID as the managed key ID in the Vendor Settings (including imported keys), and this key will then be presented in the self-serve key onboarding UI.

To see available keys, use the keys list command (ignoring the default key). In the example below, the domain imports keys from another domain aliased as "parent". This allows the vendor to manage a key in one place, but import it and recommend it as the vendor managed key in multiple customer domains.

am keys list
- source: imported
  resourcePath: imported
  rekID: parent::b99e19cc-ce32-501d-b3f0-3f38db7db67a
  description: imported
  imported: true
  sourceDomainID: dm-eGQ34fDzBQW
  sourceDomainName: parent
- source: imported
  resourcePath: imported
  rekID: parent::active
  description: Automatically points to the active Root Encryption Key in the peer domain
  imported: true
  sourceDomainID: dm-eGQ34fDzBQW
  sourceDomainName: parent
- source: default
  resourcePath: ''
  rekID: 23ae51cd-4004-578f-b8e1-0dd5cc1db7f8
  description: ''
  imported: false

In the above example, either of the imported keys are valid choices for the managed key field in vendor settings. The "parent::active" key automatically points to the active key in the parent domain and allows the vendor to add new keys (e.g. as part of a rotation schedule) and automatically have all customers that have selected the vendor managed key automatically begin using the new key. This can be configured in vendor settings with:

am domain vendor-settings update --managed-key-id 'parent::active'

Disabling Hold Your Own Key​

Hold your own key encryption, by design, implies that if access to the customer-held key is lost, some or all of the customer's data will no longer be accessible. As a consequence, some vendors may want to discuss the implications of using hold your own key encryption (such as changes to the terms of service or wording of SLAs) before allowing customers to hold their own keys externally. This can be accomplished by setting disableHYOK to true in the vendor settings. In the self-serve key onboarding UI, the hold your own key option will be greyed out, with a tooltip indicating that the customer should contact the vendor support email to enable the option.

This can be done with:

am domain vendor-settings update --disable-hyok true

API Access​

All of the above commands shown with the CLI can also be done through the language bindings and REST API.