Wi-SUN FAN Security Concepts and Design Considerations#

Wi-SUN FAN security mechanisms are built on widely-used industry standards. Access control is based on IEEE 802.1X and IEEE 802.11i concepts, providing mutual authentication and establishment of a security association between the joining node and the Wi-SUN Border Router. Frame security uses AES-CCM* from IEEE 802.15.4, providing both data confidentiality and data authenticity.

This page discusses security in terms of:

Authentication#

Wi-SUN authentication is done using the Extensible Authentication Protocol - Transport Layer Security (EAP-TLS) protocol over Extensible Authentication Protocol over LAN (EAPOL). The authentication results in a Pairwise Master Key (PMK), a unique key shared between the border router and the device.

The PMK is used in the 4-way-handshake procedure with the border router. During the authentication, the border router delivers up to four Group Transient Keys (GTKs) to the devices. GTKs are shared between all connected devices in the network. The flow is described in the diagram below.

Wi-SUN AuthenticationWi-SUN Authentication

In the Wi-SUN FAN context, authentication is considered to be an “expensive” operation. This is reflected in the default lifetime of various authentication keys. Silicon Labs' Wi-SUN FAN stack stores the authentication keys and the TX frame counter in non-volatile storage in order to make reconnection faster after a reboot or a loss of connection.

Key

Default Lifetime

Refresh Procedure

Pairwise Master Key (PMK)

4 months

EAP-TLS

Pairwise Transient Key (PTK)

2 months

4-way-handshake

Group Transient Key (GTK)

1 month

4-way-handshake or 2-way-handshake

Wi-SUN Router#

Each Wi-SUN device has a unique X.509 certificate (NIST EC P-256) signed by a Certification Authority (CA). A Wi-SUN device must store at least two certificates:

  • The device certificate: Used to authenticate the device to an authentication server. The authentication server may run on the border router or on the backhaul network.

  • The CA root certificate: Used by the device to verify the authentication server.

Device Certificate#

Each Wi-SUN node has a secure identity based on a unique per-device X.509 certificate and its corresponding private key, using the Secure Device Identifier (DevID) concept from IEEE 802.1AR. Wi-SUN device certificates must adhere to the requirements in the table below.

X.509 w/ v3 Extensions#

Fields and Extensions

Value

version

v3

serialNumber

an unique serial number

signature

ecdsa-with-SHA256

issuer

copied from issuer's subject field

notBefore

issuing time and date in UTC (GeneralizedTime)

notAfter

99991232235959Z (GeneralizedTime)

subjectPublicKeyInfo

id-ecPublicKey, namedCurve secp256r1

signatureAlgorithm

ecdsa-with-SHA256

keyUsage

digitalSignature, keyAgreement

extendedKeyUsage

clientAuth, id-kp-wisun-fan-device

authorityIdentifier

only the keyIdentifier field

subjectAltName

id-on-hardwareModuleName

id-kp-wisun-fan-device#

In addition to clientAuth, all Wi-SUN device certificates must contain the id-kp-wisun-fan-device object identifier.

id-kp-wisun-fan-device OBJECT IDENTIFIER ::= { iso(1) identified-organization(3) dod(6) internet(1) private(4) enterprise(1) Wi-SUN (45605) FieldAreaNetwork(1) }

id-on-hardwareModuleName#

All Wi-SUN device certificates must contain one and only one alternative name of type OtherName of type id-on-hardwareModuleName. The sequence is specified in RFC4108.

HardwareModuleName ::= SEQUENCE { hwType OBJECT IDENTIFIER, hwSerialNum OCTET STRING }

hwType is an object identifier that, at a minimum, identifies the manufacturer's enterprise number (IANA) but may optionally be subtyped to contain manufacturer-specific information, such as the device model.

hwSerialNum is the serial number of the hardware module. No particular structure is imposed on the serial number. However, the combination of the hwType and hwSerialNum uniquely identifies the hardware module.

Device Private Key#

In addition to a plaintext key in the buffer, the stack also accepts a PSA key reference to the device private key. When using the key reference, the PSA key attributes must be set according to the following table.

Attribute

Value

psa_set_key_usage_flags

PSA_KEY_USAGE_SIGN_HASH

psa_set_key_type

PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1)

psa_set_key_algorithm

PSA_ALG_ECDSA(PSA_ALG_SHA_256)

Credential Cache#

The device maintains a credential cache for the previously connected PAN. If the same PAN is joined again, the device will use the stored credentials to bypass the authentication phase.

NOTE: The credential cache can be cleared before the join attempt by using the API function sl_wisun_clear_credential_cache() but it should be used with care. Clearing the cache on the joining node may prevent it from re-joining the same PAN. This is due to AES-CCM* replay protection security mechanism.

Wi-SUN Border Router#

In the authentication process, the Wi-SUN border router has the Authenticator role. Depending of the architecture, the authentication server can be hosted on the border router or on another device connected over IP. In the latter case, the authentication server must run RADIUS (Remote Authentication Dial-In User Service). The border router/authenticator acts as a RADIUS client while the external device acts as a RADIUS server.

Create your Own Demo Wi-SUN Certificates#

As a prerequisite, install OpenSSL on your machine.

How to View a Certificate#

openssl x509 -in <certificate pem> -text

How to Create the Wi-SUN Demo Certificates#

First, retrieve the openssl-wisun.conf file in this Community post.

  1. Create the certificate database, used to track created certificates.

touch certdb.txt
  1. Generate a Certificate Signing Request (CSR) for the root CA.

openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -keyout wisun_root_ca_key.pem -out wisun_root_ca_req.pem -config openssl-wisun.conf
  1. Self-sign the root CA.

openssl ca -selfsign -rand_serial -keyfile wisun_root_ca_key.pem -in wisun_root_ca_req.pem -out wisun_root_ca_cert.pem -notext -extensions v3_root_ca -config openssl-wisun.conf -subj "/CN=Wi-SUN Demo Root CA"
  1. Generate a CSR for the intermediate 1 CA.

openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -keyout wisun_intermediate1_ca_key.pem -out wisun_intermediate1_ca_req.pem -config openssl-wisun.conf
  1. Sign the intermediate 1 CA with the root CA.

openssl ca -rand_serial -cert wisun_root_ca_cert.pem -keyfile wisun_root_ca_key.pem -in wisun_intermediate1_ca_req.pem -out wisun_intermediate1_ca_cert.pem -notext -extensions v3_ca1 -config openssl-wisun.conf -subj "/CN=Wi-SUN Demo Intermediate 1 CA"
  1. Generate a CSR for the intermediate 2 CA.

openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -keyout wisun_intermediate2_ca_key.pem -out wisun_intermediate2_ca_req.pem -config openssl-wisun.conf
  1. Sign the intermediate 2 CA with the intermediate 1 CA.

openssl ca -rand_serial -cert wisun_intermediate1_ca_cert.pem -keyfile wisun_intermediate1_ca_key.pem -in wisun_intermediate2_ca_req.pem -out wisun_intermediate2_ca_cert.pem -notext -extensions v3_ca2 -config openssl-wisun.conf -subj "/CN=Wi-SUN Demo Intermediate 2 CA"
  1. Generate a CSR for the border router.

openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -keyout wisun_br_key.pem -out wisun_br_req.pem -config openssl-wisun.conf
  1. Sign the border router certificate with the desired CA.

openssl ca -rand_serial -cert wisun_root_ca_cert.pem -keyfile wisun_root_ca_key.pem -in wisun_br_req.pem -out wisun_br_cert.pem -notext -extensions v3_br -config openssl-wisun.conf -subj "/CN=Wi-SUN Demo Border Router"
  1. Generate a CSR for the device.

openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -keyout wisun_device_key.pem -out wisun_device_req.pem -config openssl-wisun.conf
  1. Sign the device certificate with the desired CA.

openssl ca -rand_serial -cert wisun_root_ca_cert.pem -keyfile wisun_root_ca_key.pem -in wisun_device_req.pem -out wisun_device_cert.pem -notext -extensions v3_device -config openssl-wisun.conf -subj "/CN=Wi-SUN Demo Device"

Note that the "openssl-wisun.conf" file contains the Silicon Labs enterprise number. You should replace it with your own (cf. https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers).