dot1x_certificates

set dot1x_certificates installs an 802.1X certificate chain on one or more devices: the private key, the device certificate, and any intermediate certificates. A device uses the chain to authenticate with EAP-TLS on a switch port that enforces 802.1X.


Command Type	SDVoE
Minimum Version	3.x.x

Usage

set <target> dot1x_certificates <file_names> [password <password>]

Arguments

Argument	Required	Description
`target`	Yes	Hostname or MAC address of a single device, or a device group (`ALL`, `ALL_TX`, `ALL_RX`).
`file_names`	Yes	Comma-separated list of the certificate files, in this order: private key, device certificate, then intermediate certificates. See Certificate files.
`password`	No	The private key's password. Required only when the key file is encrypted. Spaces are not supported.

Certificate files

Requirement	Value
Format	PEM (Base64). Certificates are X.509.
Key type	ECDSA, curve P-256 (secp256r1). RSA keys are rejected.
Chain size	The complete chain must not exceed 4 KB.
Location	The files are read from DisplayNet Server, not sent in the command.

Behavior

The complete chain must be installed in a single command.
Each command replaces any chain already on the device. This is how a certificate is renewed.
There is no command to remove a chain from a device.
Devices do not ship with a factory 802.1X certificate.
Installing a chain does not turn 802.1X on or off. Enforcement is configured on the network switch and the RADIUS server, and the RADIUS server must also use an ECDSA P-256 certificate.

To give each device its own certificate, send one command per device. To install a shared certificate on a group, use a group target.

Examples

Install a certificate chain with an encrypted private key on one device
set 001ec0f03668 dot1x_certificates client.key,client.pem,intermediate.pem password s3cret

Install a shared certificate chain on all receivers
set ALL_RX dot1x_certificates shared.key,shared.pem,intermediate.pem

Return value

set 001ec0f03668 dot1x_certificates client.key,client.pem,intermediate.pem password s3cret
{
  "status": "PROCESSING",
  "request_id": 57,
  "result": null,
  "error": null
}

The completed request, read with request, lists each device the chain was installed on:

{
  "status": "SUCCESS",
  "request_id": 57,
  "result": {
    "dot1x_certificates": [
      {
        "device_id": "001ec0f03668",
        "device_name": "001ec0f03668"
      }
    ],
    "error": []
  },
  "error": null
}

Errors

Error	Cause
`ILLEGAL_ARGUMENT`	The target is not a valid device ID or group name
`IO_ERROR`	One of the listed files cannot be read
`DOT1X`	The password is wrong, a file is not in PEM format, the key is not ECDSA P-256, or the chain exceeds 4 KB

Checking status

Two members of the device object report 802.1X information, both returned by get <target> settings:

Member	Meaning
`capabilities.dot1x`	`true` if the device supports 802.1X
`configuration.dot1x_certificate`	`true` if a certificate chain is installed

DisplayNet cannot see whether the switch has authorized a device's port. A device whose certificate is missing, expired, or rejected appears offline.

REST API

Endpoint type	SDVoE API command, forwarded to the Control Server
Address	`/api/device/{target}`
Role	Governed by the device lock rather than by a DisplayNet role

POST /api/device/{target}
{
  "op": "set:dot1x_certificates",
  "password": "String",
  "file_names": "String"
}

`password` is optional. `file_names` is a comma-separated list: key, device certificate, intermediates.

Values labeled with a type name such as String or Integer are placeholders, not literal text. Replace them with actual values; fields marked (optional) can be omitted.

{target} takes a DisplayNet device name as readily as a device ID, and a locked device refuses a mutating operation. See SDVoE API operations for what DisplayNet adds to these calls.

Usage​

Arguments​

Certificate files​

Behavior​

Examples​

Return value​

Errors​

Checking status​

REST API​

See also​