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 scripts to generate X509 certificates, build .tlv and .sgn files can be downloaded from the URL below.

file_download certutils-4.13.tar.gz (19K) event 29/08/2024 security SHA256:4b801f29cda8de4a5b2ff0c861637739d365176204938214e7a082790b636f72.

mkcert link

mkcert is basic script to generate RSA private keys and self-signed X509 certificates. If you already have certificates they can be used instead, commonName (CN), organizationName (O) and organizationalUnitName (OU) attributes are required. Note: When generating RSA keys the maximum supported size is 2048 bits and when generating EC keys the recommended curves are secp256r1, secp384r1 or secp521r1.

1. Create a certificate to sign ITLFile.tlv. This will have the SAST (System Administrator Security Token) role.

~/certutils-X.X$ sudo ./mkcert --common "SAST" --organization "SAST" --unit "SAST" --years 20 /etc/ssl/private/sast.pem
2. Create a certificate for Asterisk. This will have the CCM role for SIP-TLS connections. Optionally, this can also have the TFTP role to sign provisioning files.

~/certutils-X.X$ sudo ./mkcert --common "Asterisk" --organization "Asterisk" --unit "Asterisk" /etc/asterisk/keys/asterisk.pem

3. Optionally, create a certificate for Apache with an EC (elliptic curve) key. This will have the TFTP role for HTTPS provisioning. See Secure Provisioning for more information.

~/certutils-X.X$ sudo ./mkcert --common "Apache-EC" --organization "Apache-EC" --unit "Asterisk-EC" --curve secp384r1 /etc/apache/ssl-certs/apache-ec.pem

4. Optionally, create a certificate for Apache. This will have the APP-SERVER role for secure XML services.

~/certutils-X.X$ sudo ./mkcert --common "Apache" --organization "Apache" --unit "Apache" /etc/apache/ssl-certs/apache.pem

tlvfile link

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

SAST	System Administrator Security Token, signs and verifies `.tlv` files
CCM	Verifies the SIP-TLS connection to Asterisk
TFTP	Signs provisioning files downloaded via HTTP or TFTP (RSA) and verifies HTTPS provisioning connections (EC)
CCM+TFTP	Combined `CCM` and `TFTP` roles
CAPF	Verifies the SSL connection to the Certificate Authentication Proxy Service
APP-SERVER	Verifies HTTPS connections to phone XML services
TVS	Verifies the SSL connection to the Trust Verification Service

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 role. A .tlv can have a maximum of 2 certificates with the SAST role.

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 role.

~/certutils-X.X$ sudo ./tlvfile --build /var/lib/tftpboot/ITLFile.tlv --sast /etc/ssl/private/sast.pem \
  --ccm /etc/asterisk/keys/asterisk.pem --app-server /etc/apache2/ssl-certs/apache.pem

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-X.X$ sudo ./tlvfile --build /var/lib/tftpboot/ITLSEP58971ECC97C1.tlv --sast /etc/ssl/private/sast.pem \
  --ccm /etc/asterisk/keys/asterisk-1.pem --ccm /etc/asterisk/keys/asterisk-2.pem --filename 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-X.X$ sudo ./tlvfile --build /var/lib/tftpboot/CTLSEP58971ECC97C1.tlv --sast /etc/ssl/private/sast.pem \
  --app-server /etc/apache2/ssl-certs/apache-1.pem --app-server /etc/apache2/ssl-certs/apache-2.pem --filename 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-X.X$ sudo ./tlvfile --build /var/lib/tftpboot/ITLFile.tlv --version 1.1 --sast /etc/ssl/private/sast.pem \
  --ccm /etc/asterisk/keys/asterisk.pem --tftp /etc/apache2/ssl-certs/apache-ec.pem

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.

libsrtp link

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

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

sgnfile link

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 role has been included in the phone's .tlv file.

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

~/certutils-X.X$ sudo ./sgnfile --build /var/lib/tftpboot/SEP58971ECC97C1.cnf.xml --tftp /etc/asterisk/keys/asterisk.pem
~/certutils-X.X$ sudo ./sgnfile --build /var/lib/tftpboot/SoftKeys.xml --tftp /etc/asterisk/keys/asterisk.pem
~/certutils-X.X$ sudo ./sgnfile --build /var/lib/tftpboot/DialTemplate.xml --tftp /etc/asterisk/keys/asterisk.pem

2. Sign network and user locale files.

~/certutils-X.X$ sudo ./sgnfile --build /var/lib/tftpboot/New_Zealand/g3-tones.xml --tftp /etc/asterisk/keys/asterisk.pem \
  --filename New_Zealand/g3-tones.xml.sgn
~/certutils-X.X$ sudo ./sgnfile --build /var/lib/tftpboot/New_Zealand/mk-sip.jar --tftp /etc/asterisk/keys/asterisk.pem \
  --filename New_Zealand/mk-sip.jar.sgn

3. Sign ring-tones (optional).

~/certutils-X.X$ sudo ./sgnfile --build /var/lib/tftpboot/Ringlist.xml --tftp /etc/asterisk/keys/asterisk.pem
~/certutils-X.X$ sudo ./sgnfile --build /var/lib/tftpboot/Old_Telephone.raw --tftp /etc/asterisk/keys/asterisk.pem

4. Sign background images (optional).

~/certutils-X.X$ sudo ./sgnfile --build /var/lib/tftpboot/Desktops/320x196x4/List.xml --tftp /etc/asterisk/keys/asterisk.pem \
  --filename Desktops/320x196x4/List.xml.sgn
~/certutils-X.X$ sudo ./sgnfile --build /var/lib/tftpboot/Desktops/320x196x4/Logo.png --tftp /etc/asterisk/keys/asterisk.pem \
  --filename Desktops/320x196x4/Logo.png.sgn
~/certutils-X.X$ sudo ./sgnfile --build /var/lib/tftpboot/Desktops/320x196x4/Logo_Preview.png --tftp /etc/asterisk/keys/asterisk.pem \
  --filename Desktops/320x196x4/Logo_Preview.png.sgn

enccnf link

enccnf is used to build or parse .enc.sgn files which are encrypted SEPMAC.cnf.xml phone configuration file and signed by a certificate with the TFTP role. The public key from the phone's MIC or LSC is used to encrypt the file, see Certificate Enrollment for more information. Note: enccnf will delete the .cnf.xml file after creating the .sgn and .enc.sgn file.

~/certutils-X.X$ sudo ./enccnf --build /var/lib/tfptboot/SEP58971ECC97C1.cnf.xml --tftp /etc/asterisk/keys/asterisk.pem \
  --certificate /var/lib/capf/SEP58971ECC97C1.pem

<proxy>

USECALLMANAGER.nz

</proxy>