Sangoma Phones and 802.1X

Defaults

By default, the phone does not perform its own 802.1X authentication nor does the phone allow pass-through of EAPOL packets, except for D80, nor does it perform automatic logoff of PC-port attached clients.  All of these options must be turned on.

Recommended Firmware

For D6x phones, it is recommended to use firmware 2_7_0 or greater.  Versions prior to this may experience problems when validating certificate start dates.  For the D80, it is recommended to use firmware 1_9_0 or greater.

Compatibility

D80 model phones do not support 802.1X auto log-off.

Important Notes

Older versions of phone firmware did not validate the certificate of the authentication server unless the 8021x_root_cert setting was invoked.  The old versions also allowed separate downloads of 802.1X Root CA, Client Certificate, and Client Key.  The old versions also required combination of client certificates and client keys into the same file.

Firmware versions 2_7_0 and greater do validate the certificate of the authentication server by default.  This can be disabled by setting the enable_insecure_ssl setting on the phone.

Firmware versions 2_7_0 and greater do not allow separate downloads of 802.1X Root CA, Client Certificate, or Client Key files.  Rather, all of these are now embedded in the main phone configuration file using the cert, clientcert, and clientkey directives.  It is highly recommended to utilize the md5 parameter when specifying the certificates, as the phone only knows to kick off a reboot to use a new, loaded via an updated configuration file after the phone is already running, certificate if the md5 value has changed.  To specify a privately-signed root CA, client certificate and client key, the phone's config should include a certs element, e.g.:

EAP-MD5

To configure EAP-MD5 for the phone, users should set the following:

With this method set, a user must supply their username, an anonymous identifier (which can be the special-case literal PHONE_MAC the causes the phone to send its own MAC address as the anonymous identifier), and their password.  Some systems may require the regular username to be transmitted as the anonymous identifier.

802.1X Pass-through and EAPOL Auto-Logoff

To configure pass-through, users should set:

By default, these values are zero, meaning that pass-through is blocked and no auto-logoff occurs.  When pass-through is enabled, the phone will allow EAPOL packets to traverse the switch (from the PC port-attached device to the upstream LAN port-attached ethernet switch).  When EAPOL disconnect is enabled, the phone will keep a record of the MAC addresses of all devices that it sees sending EAPOL events from the PC port to the LAN port and will, when the PC port-attached device drops link, send an EAPOL Logoff message to the upstream authenticator on-behalf of the device, impersonating its MAC.

EAP-PEAPv0/MSCHAPv2

To configure EAP-PEAPv0/MSCHAPv2, users should set:

This sets the method to EAP-PEAPv0/MSCHAPv2 and passes in the supplied username and password.

EAP-TLS

To configure EAP-TLS, users should set:

EAP-TLS requires an identity, a client certificate and a client key, as well as validation of the server's Root CA.  The client certificate and client key should be in-lined in the phone's config using the clientcert and clientkey configuration parameters.  If the authentication server does not have a valid, publicly-signed certificate, an additional cert need be in-lined in the phone's config.  The value specified in the definition of the 8021x_client_cert and 8021x_client_key settings must match the label of the clientcert and clientkey that you wish to use, respectively.

EAP-PEAPv0/EAP-GTC

To configure EAP-PEAPv0/EAP-GTC, users should set:

This sets the method to EAP-PEAPv0/EAP-GTC and passes in the supplied username and password.

EAP-TTLS/EAP-MSCHAPv2

To configure EAP-TTLS/EAP-MSCHAPv2, users should set:

This sets the method to EAP-TTLS/EAP-MSCHAPv2 and passes in the supplied username and password.

EAP-TTLS/GTC

To configure EAP-TTLS/GTC, users should set:

This sets the method to EAP-TTLS/GTC and passes in the supplied username and password.

Debugging

To configure 802.1X debugging, users should set:

or:

for even more verbose logs.

In the event that 802.1X logins fail, a user should enable debugging, reboot their phone, allow it to attempt to authenticate, wait for it to fail, turn up the switch port manually, allow it to acquire an IP, and then capture a phone debug by taking a web browser to:

the debug file should be provided to Digium's Support department.

Replacing Certificates

When a phone is factory defaulted, any stored certificates are deleted.

If a user needs to cause a phone to switch to a different certificate, then the md5 parameter for the in-line cert, clientcert, and/or clientkey should be changed.  This will cause the phone to restart to use the new certificate.  If the phone receives an updated config in which the md5 parameter has not changed, the phone will not know to restart and will have to be manually restarted.

Disabling 802.1X Authentication

By default, a phone will not perform any 802.1X authentication.  The phone disables 802.1X authentication when the following parameter is configured null, the default:

Any additional 8021x_method_xyz parameters are ignored when 8021x_method is set to null.