Device Security

The default list of valid X509 certificates is specified in a file called ITLFile.tlv. These certificates are used to verify SIP-TLS and HTTPS connections as well as optionally sign configuration files.

An archive containing the scripts need to generate X509 certificates, build .tlv and .sgn files can be downloaded from the URL below.

file_download certutils.tar.bz2 (15K) event 08/03/2018 security SHA256:3eaa9e5f975eea3e315229e8648cf0969d831294d18c0ebc8169d59a81278744.


gencert is basic script to generate RSA private keys and sign X509 certificates. If you already have certificates they can be used instead.

1. Create a CA certificate valid for 20 years. This will function as the SAST (System Administrator Security Token) certificate.

~/certutils$ ./gencert -n -C "Certificate Authority" -b 2048 -y 20 -o CA.pem
2. Create a certificate for Asterisk signed by the CA for 1 year. This will function as the CCM certificate.

~/certutils$ ./gencert -c CA.pem -C Asterisk -b 2048 -y 1 -o asterisk.pem
3. Create a certificate for Apache signed by the CA for 1 year (optional). This will function as an HTTPS certificate.

~/certutils$ ./gencert -c CA.pem -C Apache -b 2048 -y 1 -o apache.pem


tlvfile is used to build or parse .tlv files. Each certificate has an function specifying where it is used and the same certificate can be included multiple times to provide different functions. Valid functions are listed below.

SAST System Administrator Security Token, signs and verifies .tlv files
CCM Verifies the SIP-TLS connection to Asterisk
TFTP Signs and verifies provisioning files downloaded via TFTP or HTTP
CCM+TFTP Combined CCM and TFTP functions
HTTPS Verifies HTTPS connections to phone services

Note: Once a phone has installed a .tlv new versions of that file can only be signed by a previously known certificate with the SAST function.

1. Create ITLFile.tlv in the tftpboot provisioning directory, the certificate used to sign the .tlv file is automatically included as providing the SAST function.

~/certutils$ ./tlvfile -b /var/lib/tftpboot/ITLFile.tlv -c CA.pem \ -r asterisk.pem -f ccm -r apache.pem -f https
2. Optionally, the default ITLFile.tlv can be overridden using a file name based on the MAC address of the phone, eg: ITLSEP58971ECC97C1.tlv.

~/certutils$ ./tlvfile -b /var/lib/tftpboot/ITLSEP58971ECC97C1.tlv -c CA.pem \ -r asterisk1.pem -f ccm -r asterisk2.pem -f ccm -F ITLFile.tlv
3. Optionally, additional certificates can be included using a file name based on the MAC address of the phone, eg: CTLSEP58971ECC97C1.tlv.

~/certutils$ ./tlvfile -b /var/lib/tftpboot/CTLSEP58971ECC97C1.tlv -c CA.pem \ -r apache1.pem -f https -r apache2.pem -f https -F CTLFile.tlv
4. Enable SIP-TLS mode by setting <transportLayerProtocol> to 3 and setting <deviceSecurityMode> to either 2 (Authenticated) or 3 (Encrypted) in SEPMAC.cnf.xml. Optionally, any XML services can be configured to use HTTPS.


sgnfile is used to build or parse .sgn files which are any non-firmware files the phone downloads during provisioning with a digital signature added. You only need to sign files if the TFTP function has been included in the phone's .tlv file.

1. Sign SEPMAC.cnf.xml, soft-key and dial-plan files.

~/certutils$ ./sgnfile -b /var/lib/tftpboot/SEP58971ECC97C1.cnf.xml -c asterisk.pem ~/certutils$ ./sgnfile -b /var/lib/tftpboot/SoftKeys.xml -c asterisk.pem ~/certutils$ ./sgnfile -b /var/lib/tftpboot/DialTemplate.xml -c asterisk.pem
2. Sign network and user locale files.

~/certutils$ ./sgnfile -b /var/lib/tftpboot/New_Zealand/g3-tones.xml -c asterisk.pem \ -F New_Zealand/g3-tones.xml.sgn ~/certutils$ ./sgnfile -b /var/lib/tftpboot/New_Zealand/mk-sip.jar -c asterisk.pem \ -F New_Zealand/mk-sip.jar.sgn
3. Sign ring-tones (optional).

~/certutils$ ./sgnfile -b /var/lib/tftpboot/Ringlist.xml -c asterisk.pem ~/certutils$ ./sgnfile -b /var/lib/tftpboot/Old_Telephone.raw -c asterisk.pem
4. Sign background images (optional).

~/certutils$ ./sgnfile -b /var/lib/tftpboot/Desktops/320x196x4/List.xml -c asterisk.pem \ -F Desktops/320x196x4/List.xml.sgn ~/certutils$ ./sgnfile -b /var/lib/tftpboot/Desktops/320x196x4/Logo.png -c asterisk.pem \ -F Desktops/320x196x4/Logo.png.sgn ~/certutils$ ./sgnfile -b /var/lib/tftpboot/Desktops/320x196x4/Logo_Preview.png -c asterisk.pem \ -F Desktops/320x196x4/Logo_Preview.png.sgn