This feature requires at least version 2.0 of the nvme-cli utility.
Lightbits supports in-band authentication per the NVMe Express Base Specification, allowing the client and target to authenticate each other's identities during connection. The client and target confirm a pre-shared key during initial connection, without exchanging the actual secret.
Enabling authentication requires adding a trusted host and secrets to the Lightbits control plane using new API endpoints or CLI commands.
- A
trusted hostrefers to a host (client) whose NVMe Qualified Name (NQN) is registered with the Lightbits control plane. The trusted-host setting means the specified host must authenticate itself to the NVMe target before connecting. trusted-host-secretsspecified the secrets for the trusted-host. You can update the client configuration with the keys specified in thetrusted-host-secretsobject.
In-band authentication is enabled per subsystem, which means all targets in the Lightbits cluster.
To use the in-band authentication 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.
- Connect the client to the cluster using the nvme CLI.
- Configure discovery-client.
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 may change in future versions.
Enabling In-Band Authentication Feature Support
The InBand authentication feature flag is optional and set to false by default. To enable the in-band authentication feature flag, run lbcli enable feature-flag in-band-authentication. This command enables the feature within the Lightbits control plane.
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).
To validate that the feature is enabled, run lbcli list feature-flag. The output should indicate that InBandAuthentication is enabled.
Once the feature flag is enabled, in-band-auth can be enabled for the DefaultSubSystem:
lbcli enable in-band-auth --sub-system="DefaultSubSystem"
To confirm that in-band-auth is enabled, inspect the
JSON output using lbcli get cluster -o json. Then review for authentication settings.
Enable Feature Flag API
The following sections of this document provide additional information on each of the APIs. Full details on the CLIs/APIs are available in the Lightbits REST and lbcli documentation.
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.
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}"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.
To create a trusted host in the control plane, use lbcli create trusted-host --project-name=default --name="my-host" --host-nqn="my-hostnqn". This registers a host as trusted with the provided NQN.
| Name | UUID | Host NQN | Project |
|---|---|---|---|
my-host | d3fe3ce7-777b-4324-b3ec-20e7a130017f | my-hostnqn | default |
After creation, my-host requires authentication.
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.
Use secrets that comply with NVMe specifications. Human-readable secrets will not work. Generate secrets using the nvme CLI utility or let the Lightbits control plane create them.
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.
Adding Secrets in the Trusted Host
To add a secret to the host, generate the key with:
lbcli set trusted-host-secrets --project-name=default --name my-hostThis stores the newly generated secret for the host.
To get the stored keys from the control plane:
lbcli get trusted-host-secrets --project-name=default --name my-host -o json{ "host": { "name": "my-host", "projectName": "default", "UUID": "d3fe3ce7-777b-4324-b3ec-20e7a130017f", "hostNqn": "my-hostnqn", "labels": [ ], "authRequired": "true" }, "hostSecret": "DHHC-1:00:g7NtLRGRc1JwOaY4wuLKtkZqLwNXfVzCPBX9Lr3ojc6VdvC2:", "targetSecret": ""}Connecting the Client Via nvme-cli
With keys configured, connect the client to the cluster using the nvme CLI:
nvme connect -t tcp -a 10.20.73.4 -s 4420 -q my-hostnqn \-n nqn.2016-01.com.lightbitslabs:uuid:c2ba57ac-c56f-4ac8-b127-95b2bd6952a3:suffix \ --dhchap-secret DHHC-1:00:g7NtLRGRc1JwOaY4wuLKtkZqLwNXfVzCPBX9Lr3ojc6VdvC2:The kernel logs on the client show the following entries when authentication is successful:
nvme nvme12: qid 0: authenticated with hash hmac(sha256) dhgroup ffdhe2048This confirms successful client authentication to the target.
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}"Configuring discovery-client
To configure the discovery-client, secrets must be added to discovery-client.yaml. Note that the keys themselves must be enclosed in double quotes.
dhChapSecret"MY_KEY"dhChapCtrlSecret"IF_APPLICABLEParameter Details
dhChapSecret: (Mandatory for authentication) Specifies the host secret.dhChapCtrlSecret: (Optional) Specifies the target secret.
Authentication Modes
- Unidirectional Authentication: Specify only the
dhChapSecret. - Bidirectional Authentication: Specify both
dhChapSecretanddhChapCtrlSecret. - Authentication Disabled: If neither secret is specified, authentication is assumed to be disabled.
The keys are global and used for any configured subsystem NQN to which Lightbits connects.