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-2.4.tar.gz (16K) event 05/11/2020 security SHA256:205aa54ef00752bf3245276b7104a512f6deb5fe09948aaaa309ce8db2dc5d9e.


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 Authority) certificate valid for 20 years. This will function as the sast (System Administrator Security Token) certificate.

~/certutils$ ./gencert -r -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 and tftp certificate.

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

~/certutils$ ./gencert -c ca.pem -E secp384r1 -C "Apache-EC" -y 1 -o apache-EC.pem
4. 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 HTTP, HTTPS or TFTP
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. A .tlv can have a maximum of 2 certificates with the sast function.

1. Create an 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. Optionally, use HTTPS provisioning for SEPMAC.cnf.xml and signing for the other configuration files. Note: the certificate used to verify the HTTPS connection must use an EC (Elliptic Curve) key.

~/certutils$ ./tlvfile -b /var/lib/tftpboot/ITLFile.tlv -v 1.1 -c ca.pem \ -r asterisk.pem -f tftp -r apache-EC.pem -f tftp
5. 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.


To use secure (encrypted) RTP libsrtp must be installed. The latest release is available from the open_in_browser libsrtp GitHub repository.

~/libsrtp-2.3.0$ ./configure --prefix=/usr --enable-openssl ~/libsrtp-2.3.0$ make shared_library ~/libsrtp-2.3.0$ sudo make install


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