Authentication - linux-nvme/nvme-cli GitHub Wiki

How to setup inband authentication

Generating DH-HMAC-CHAP keys

The DH-HMAC-CHAP keys are generated with

# nvme gen-dhchap-key
DHHC-1:00:2wKd3YDIcRMN/rCJa/k60E8xBQMw+2D9UnigSQ6YFkEHV3Yy:

which will print out the key in the so-called transport encoding format. Per default no HMAC transformation of the key is requested; if a transformation is required specify the --hmac option. Be aware that the HMAC transformation requires the NQN of the entity for which the key is generated (ie the Host NQN for a host or the Subsystem NQN for a subsystem); this needs to be specified with the --nqn parameter. If the parameter is not present the Host NQN of the system where the key is generated is used.

The length of the key depends on the selected hash function (SHA-256 will generate 32 bytes, SHA-384 48 bytes, and SHA-512 64 bytes); if no hash function is specified the key length can be selected via the --key-length option.

# nvme gen-dhchap-key --hmac=2 --nqn=nqn.2014-08.org.nvmexpress:uuid:befdec4c-2234-11b2-a85c-ca77c773af36
DHHC-1:02:d4gmzh5i0I3npDMWAmJX/nAvAw7ioKmS2w44ceutFeObYDFG/r6zOB3UW0FLzevsI7XDJg==:

Secure concatenation only supports SHA-256 and SHA-384 (ie --hmac=1 or --hmac=2), so keys with SHA-512 should not be used with secure concatenation as the remaining bits of the key will be ignored for hash functions using shorter hash lengths.

Establishing an authenticated connection

There are two types of authentication, unidirectional (controller) authentication, and bidirectional (controller and host) authentication. For unidirectional authentication the host authenticates the controller; for bidirectional authentication the controller additionally authenticates the host.

A connection with unidirectional authentication can be create with

nvme connect --transport tcp --traddr 192.168.154.148 --trsvcid 4420 \
             --hostnqn nqn.2014-08.org.nvmexpress:uuid:befdec4c-2234-11b2-a85c-ca77c773af36 \
             --dhchap-secret DHHC-1:00:2wKd3YDIcRMN/rCJa/k60E8xBQMw+2D9UnigSQ6YFkEHV3Yy:

A connection with bidirectional authentication can be created with:

nvme connect --transport tcp --traddr 192.168.154.148 --trsvcid 4420 \
             --hostnqn nqn.2014-08.org.nvmexpress:uuid:befdec4c-2234-11b2-a85c-ca77c773af36 \
             --dhchap-secret DHHC-1:00:2wKd3YDIcRMN/rCJa/k60E8xBQMw+2D9UnigSQ6YFkEHV3Yy: \
             --dhchap-ctrl-secret DHHC-1:00:G8VM77bVd+P4GVG8GFhbrUqqapcRfKLC4T63ADOaHSVLtWE3:

Configuring the target

Target configuration for DH-HMAC-CHAP is done in the 'host' section:

{
  "hosts": [
    {
      "nqn": "nqn.2014-08.org.nvmexpress:uuid:befdec4c-2234-11b2-a85c-ca77c773af36",
      "dhchap_key": "DHHC-1:00:2wKd3YDIcRMN/rCJa/k60E8xBQMw+2D9UnigSQ6YFkEHV3Yy:",
      "dhchap_ctrl_key": "DHHC-1:00:G8VM77bVd+P4GVG8GFhbrUqqapcRfKLC4T63ADOaHSVLtWE3:",
      "dhchap_hash": "hmac(sha256)",
      "dhchap_dhgroup": "null"
    }
  ],
}

The authentication type (uni- or bidirectional) is controlled by the host, so a uni-direction authentication will be successful even if both (host and controller keys) are present in the target configuration.

The parameter dhchap_hash specifies which HMAC function will be used for the DH-HMAC-CHAP protocol. Possible values are hmac(sha256) (the default), hmac(sha384), and hmac(sha512). The value is independent on the --hmac parameter specified for the HMAC transformation of the key, but the key length of the key should be larger or equal than the hash size required by the selected HMAC function.

The parameter dhchap_dhgroup specifies which FFDHE group should be used for the DH-HMAC-CHAP protocol. Possible values are ffdhe2048, ffdhe3072, ffdhe4096, ffdhe6144, and ffdhe8192. If no group is specified the Diffie-Hellman exchange of the DH-HMAC-CHAP protocol is not performed, and no shared secret will be generated. For secure concatenation a non-null value is required as the TLS key is generated from the shared secret of the Diffie-Hellman exchange.

References