The XBee Hive for Wi-SUN provides the following configuration modes for authorization:

Allow-list only (default)

To join the network, devices must meet these criteria:

  • The device must present a certificate that was issued by a trusted root in the certificate store.

  • The device must be explicitly listed in the allowlist.

Open

Any device with a certificate that was issued by a trusted root can join the network. This mode offers convenience, as Wi-SUN nodes can connect to the XBee Hive for Wi-SUN without requiring manual configuration or pre-registration in the device allow-list.

+ However, this approach comes with security trade-offs. Unless you have exclusive control over the certificate authority (CA) and all issued certificates within your Wi-SUN network, the mode may be considered insecure. Any device possessing a certificate signed by the same CA trusted by the XBee Hive for Wi-SUN could potentially join the network.

+ By default, both the XBee Hive for Wi-SUN and XBee for Wi-SUN are configured to trust certificates issued by the Digi CA. Open authorization mode should only be used with joining nodes using your own identity certificates, and the Include Digi CA option disabled. Otherwise, any XBee for Wi-SUN may join the Wi-SUN network if configured correctly, including nodes outside of your control.

RADIUS

Authorization is handled exclusively through an external RADIUS server.

When RADIUS is selected, the XBee Hive for Wi-SUN no longer uses its local identity, trust store, or allowlist. Instead, it forwards authentication requests to the external server, which then decides whether a device is allowed to join the network.

Trusted CA certificates

When the authorization method is set to Open or Allow-list only, the XBee Hive for Wi-SUN requires all joining Wi-SUN FAN nodes to present an identity certificate signed by a configured CA.

During the joining process, a Wi-SUN device sends its device identity certificate (often called an "end-entity certificate" or a "leaf certificate") to the network’s Border Router. The Border Router must establish trust in that identity certificate before proceeding further. The XBee Hive for Wi-SUN does this by verifying that the identity certificate was issued and signed by one of the trusted CAs.

Include Digi CA

The factory device identity certificates of all Wi-SUN devices manufactured by Digi are issued by a single CA certificate. When the Include Digi CA option is enabled, the Digi Wi-SUN CA certificate is added to the user-supplied CA certificates.

This option is enabled by default. Turn this option off if you know that all devices joining your XBee Hive for Wi-SUN will present identities issued by other CAs.

CA certificates

Each trusted CA entry is identified in the device configuration by a unique name. This name exists only in the device configuration, and is not visible on the Wi-SUN network. Digi suggests giving each CA entry a meaningful name to identify what type of device it relates to.

Trusted CA certificate fields

The content configuration field contains one or more trusted X.509 CA certificates in PEM format. When multiple certificates exist, they must be concatenated. Certificates do not need to be in any particular order, but each certificate must start with -----BEGIN CERTIFICATE----- and end with -----END CERTIFICATE-----.

Consult with your Wi-SUN FAN device vendor for information on obtaining the public CA certificate(s) to use when authenticating your devices.

Because local Wi-SUN device authorization only needs to establish trust in the device certificate and its issuer, only the certificate of the issuer needs to be configured. This issuer will typically be an intermediate CA.

Allowlist feature

When the allowlist feature is enabled, a Wi-SUN FAN node is permitted to join the network only if the device identity certificate meets the following criteria:

  • The certificate is signed by a configured certificate authority, and

  • The hardware type and hardware serial number values in the id-on-hardwareModuleName Subject Alternative Name extension are in the configured allowlist.

If these criteria are not met, the device is not allowed to join the Wi-SUN network.

Allowlist fields

The items in the allowlist each consist of the following configuration fields:

Key Description Example(s)

hardware_type

X.660 OID string (integers separated by periods)

1.3.6.1.4.1.39873.1

serial_number

Hardware serial number, in hexadecimal form (case-insensitive)

 
0001
3132333435
102E5D
78f03a

Consult with your Wi-SUN FAN device vendor for information on obtaining these values for devices connecting to your Wi-SUN network.

RADIUS feature

See Use a RADIUS server for authentication.