This feature requires at least version 2.0 of the nvme-cli utility.
NVM Express TP-8006 (NVMe-oF In-Band Authentication) and NVMe Express Base Specification v2.0 add provisions for In-Band Authentication mechanisms applicable to NVMe/TCP, with DH-HMAC-CHAP as the defined initial authentication protocol.
Lightbits will provide support for this, via dedicated functionality to control and manage the set of NVMe hosts (clients) that are allowed to connect to a given NVMe target (Lightbits cluster member), as well as restrict the set of NVMe targets that a given NVMe host will “trust” and allow for connection.
In-Band Authentication is enabled per subsystem, which means all targets in the Lightbits cluster.
In order to support authentication for specific hosts:
- A new resource named “trusted-host” has been added. Trusted hosts need to be explicitly configured in the Lightbits cluster to allow them to connect to the cluster.
- A new command was added to set the secrets used to authenticate the connection (for each such trusted host).
- A new Enable In-Band Authentication command was added.
To use the feature, the following sequence should be followed:
- Enable the In-Band Authentication feature flag.
- Create a trusted host resource for each host that you want to connect to the cluster.
- Set the secrets for each of these trusted hosts.
- Enable In-Band Authentication.
The order of some of these steps can be changed. Enabling the feature flag must be the first step, but hosts can be created in any order, and secrets can be set or changed at any time. Once In-Band Authentication is enabled, only hosts that have a trusted-host resource with secrets set will be able to connect to the cluster. Connected trusted-hosts that are removed or have secrets changed to be incorrect will currently not be disconnected. This could change in future versions.
The following sections of this document provide additional detail on each of the APIs. Full details on the APIs/CLIs are available in the Lightbits REST and lbcli documentation.
Enabling In-Band Authentication Feature Support
The InBand authentication feature flag is optional and set to false by default. In order to use this feature, you will first need to enable the in-band-authentication feature flag. This operation only enables availability of In-Band Authentication features. It does not configure the cluster to require authenticated connections (this requires ‘lbcli enable in-band-auth’, which is described later in this article).
This step is only required while this feature is under development, and can be skipped once officially available.
Enable Feature Flag API
CLI
lbcli enable feature-flag in-band-authenticationREST
POST /api/v2/featureFlags/inBandAuth/enableTrusted Host
For each host that is allowed to connect to the cluster, you should create a trusted host resource. This resource will have a unique name for easy access, and the host-nqn identifying the host on the network. The trusted host resource is currently not scoped by the project internally. As usual, the admin configures which hosts can access which volumes (see volume ACL). The project given via CLI or API is not used; trusted-host names and NQNs must be unique across all projects.
A host can only perform NVMe connect to a cluster where it is defined as a trusted host resource. Otherwise, the connection will be refused.
For ease of management, resources can be assigned labels, so that they can be searched for or identified easily. The standard operations are supported for this resource: create, get, list, update, and delete.
CLI
lbcli create trusted-host [flags]lbcli get trusted-host [flags]lbcli list trusted-hosts [flags]lbcli update trusted-host [flags]lbcli delete trusted-host [flags]REST
(create) post: "/api/v2/projects/{projectName}/trustedHosts"(get) get: "/api/v2/projects/{projectName}/trustedHosts/{name}"(list) get: "/api/v2/hosts"(list) get: "/api/v2/projects/{projectName}/trustedHosts"(update) put: "/api/v2/projects/{projectName}/trustedHosts/{name}"(delete) delete: "/api/v2/projects/{projectName}/trustedHosts/{name}"Set/Get Secrets
Once a trusted host has been configured, secrets for this host can be configured via CLI/API.
Each trusted host resource has up to two secrets - the host-secret and the target-secret. The host-secret is used for authenticating the host to the Lightbits cluster, and the target-secret is used for authenticating the target (the Lightbits cluster member) to the host.
A trusted host has an "auth-required" property, which defaults to True.
If this is changed to False for a host, then no secrets are required, and that particular defined trusted host is allowed to connect without authentication. But by default it is True, and the shared host-secret is required.
This host-secret format is like "nvme gen-dhchap-key". It can be configured directly by the admin, or it can be left empty and the cluster will generate a random host-secret. In this case the admin must then get the generated secret and configure it on the host/client.
The shared target-secret is optional. If set, the connection handshake will include a second authentication of target back to host. Like host-secret, it can also be auto-generated. If not configured or generated, no target-to-host authentication is performed.
Set/Get secrets are separated from the create/update/get trusted hosts to allow different levels of authorizations for these commands, though in the initial release they share the same access rights configurations.
CLI
lbcli set trusted-host-secret [flags]lbcli get trusted-host-secret [flags]REST
(set) put: "/api/v2/projects/{projectName}/trustedHostSecrets/{name}"(get) get: "/api/v2/projects/{projectName}/trustedHostSecrets/{name}"Enabling In-Band Authentication
Once trusted hosts are configured, In-Band Authentication can be enabled. Once enabled, only defined trusted hosts that successfully authenticate can connect to the cluster (subsystem).
CLI
lbcli enable in-band-auth [flags]REST
post: "/api/v2/cluster/inBandAuth/enable"The current configuration can be verified by invoking the get cluster command:
CLI
lbcli get clusterREST
get: "/api/v2/cluster"