forked from usecallmanagernz/usecallmanagernz.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathdevice-security.html
More file actions
212 lines (212 loc) · 17 KB
/
device-security.html
File metadata and controls
212 lines (212 loc) · 17 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
<!DOCTYPE html>
<html lang="en">
<head>
<title>Device Security</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1,shrink-to-fit=no">
<link rel="shortcut icon" href="images/logo.svg">
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto">
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:FILL@0..1">
<link rel="stylesheet" href="includes/theme.css">
<link rel="stylesheet" href="includes/prettify.css">
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script>
<script src="includes/prettify.js"></script>
<script>
jQuery(window).on("load", function () {
prettyPrint();
});
</script>
</head>
<body>
<header>
<a href="/"><img src="images/logo.svg" alt=""></a>
<h2><<span>proxy</span>></h2><h1><span>USECALLMANAGER</span>.nz</h1><h2></<span>proxy</span>></h2>
</header>
<main>
<nav>
<ul>
<li><a href="documentation-overview.html"><span class="icon">home</span> Documentation Overview</a></li>
<li><a href="patching-asterisk.html"><span class="icon">build</span> Patching Asterisk</a></li>
<li><a href="change-log.html"><span class="icon">news</span> Change Log</a></li>
</ul>
<ul>
<li><h3>Network Configuration</h3></li>
<li><a href="dhcp-options.html"><span class="icon">settings_ethernet</span> DHCP Options</a></li>
<li><a href="http-provisioning.html"><span class="icon">file_download</span> HTTP Provisioning</a></li>
<li><a href="tftp-provisioning.html"><span class="icon">file_download</span> TFTP Provisioning</a></li>
</ul>
<ul>
<li><h3>Phone Configuration</h3></li>
<li><a href="sepmac-cnf-xml.html"><span class="icon">settings_phone</span> SEPMAC.cnf.xml</a></li>
<li><a href="dial-template.html"><span class="icon">dialpad</span> Dial Template</a></li>
<li><a href="application-dial-rules.html"><span class="icon">bluetooth</span> Application Dial Rules</a></li>
<li><a href="soft-keys.html"><span class="icon">power_input</span> Soft Keys</a></li>
<li><a href="line-keys.html"><span class="icon">format_list_bulleted</span> Line Keys</a></li>
<li><a href="feature-policy.html"><span class="icon">fact_check</span> Feature Policy</a></li>
<li><a href="network-locale.html"><span class="icon">language</span> Network Locale</a></li>
<li><a href="user-locale.html"><span class="icon">face</span> User Locale</a></li>
<li><a href="load-information.html"><span class="icon">file_upload</span> Firmware Load Information</a></li>
<li><a href="background-images.html"><span class="icon">wallpaper</span> Background Images</a></li>
<li><a href="ring-tones.html"><span class="icon">ring_volume</span> Ring Tones</a></li>
<li><span class="icon selected">security</span> <b>Device Security</b></li>
<li><a href="trust-verification.html"><span class="icon">verified</span> Trust Verification</a></li>
<li><a href="certificate-enrollment.html"><span class="icon">card_membership</span> Certificate Enrollment</a></li>
<li><a href="vpn-connection.html"><span class="icon">vpn_key</span> VPN Connection</a></li>
</ul>
<ul>
<li><h3>Asterisk Configuration</h3></li>
<li><a href="sip-peers.html"><span class="icon">dialer_sip</span> SIP Peers</a></li>
<li><a href="sip-notify-commands.html"><span class="icon">settings_power</span> SIP Notify Commands</a></li>
<li><a href="dialplan-extensions.html"><span class="icon">format_list_numbered</span> Dialplan Extensions</a></li>
<li><a href="call-parking.html"><span class="icon">local_parking</span> Call Parking</a></li>
<li><a href="sip-peer-options.html"><span class="icon">code</span> SIPPEER Options</a></li>
<li><a href="rtp-streaming.html"><span class="icon">volume_up</span> RTP Streaming</a></li>
<li><a href="command-line.html"><span class="icon">keyboard_arrow_right</span> Command Line</a></li>
<li><a href="freepbx-integration.html"><span class="icon">view_kanban</span> FreePBX Integration</a></li>
</ul>
<ul>
<li><h3>XML Services</h3></li>
<li><a href="phone-services.html"><span class="icon">settings</span> Phone Services</a></li>
<li><a href="cgi-execute.html"><span class="icon">phone_forwarded</span> CGI Execute</a></li>
</ul>
<ul>
<li><h3>Additional Features</h3></li>
<li><a href="as-feature-events.html"><span class="icon">extension</span> AS Feature Events</a></li>
</ul>
</nav>
<article>
<h1>Device Security</h1>
The default list of valid X509 certificates is specified in a file called <code class="literal">ITLFile.tlv</code>. These certificates are used to verify SIP-TLS and HTTPS connections as well as optionally sign configuration files.<br>
<br>
An archive containing scripts to generate X509 certificates, build <code class="literal">.tlv</code> and <code class="literal">.sgn</code> files can be downloaded from the URL below.<br>
<br>
<a href="https://github.com/usecallmanagernz/certutils/archive/v4.13.tar.gz" download><span class="icon">file_download</span> certutils-4.13.tar.gz</a> (19K) <span class="icon">event</span> 29/08/2024 <span class="icon">security</span> SHA256:4b801f29cda8de4a5b2ff0c861637739d365176204938214e7a082790b636f72.<br>
<br>
<h2 id="mkcert">mkcert <a href="#mkcert" title="Link">link</a></h2>
<code class="literal">mkcert</code> is basic script to generate RSA private keys and self-signed X509 certificates. If you already have certificates they can be used instead, commonName (<code class="literal">CN</code>), organizationName (<code class="literal">O</code>) and organizationalUnitName (<code class="literal">OU</code>) attributes are required. <b>Note:</b> When generating RSA keys the maximum supported size is <code class="literal">2048</code> bits and when generating EC keys the recommended curves are <code class="literal">secp256r1</code>, <code class="literal">secp384r1</code> or <code class="literal">secp521r1</code>.<br>
<br>
<b>1.</b> Create a certificate to sign <code class="literal">ITLFile.tlv</code>. This will have the <code class="literal">SAST</code> (System Administrator Security Token) role.<br>
<br>
<code class="command-line"><span class="prompt">~/certutils-X.X$</span> sudo ./mkcert --common "SAST" --organization "SAST" --unit "SAST" --years 20 /etc/ssl/private/sast.pem</code>
<br>
<b>2.</b> Create a certificate for Asterisk. This will have the <code class="literal">CCM</code> role for SIP-TLS connections. Optionally, this can also have the <code class="literal">TFTP</code> role to sign provisioning files.<br>
<br>
<code class="command-line"><span class="prompt">~/certutils-X.X$</span> sudo ./mkcert --common "Asterisk" --organization "Asterisk" --unit "Asterisk" /etc/asterisk/keys/asterisk.pem</code>
<br>
<b>3.</b> Optionally, create a certificate for Apache with an EC (elliptic curve) key. This will have the <code class="literal">TFTP</code> role for HTTPS provisioning. See <a href="http-provisioning.html#Secure-Provisioning">Secure Provisioning</a> for more information.<br>
<br>
<code class="command-line"><span class="prompt">~/certutils-X.X$</span> sudo ./mkcert --common "Apache-EC" --organization "Apache-EC" --unit "Asterisk-EC" --curve secp384r1 /etc/apache/ssl-certs/apache-ec.pem</code>
<br>
<b>4.</b> Optionally, create a certificate for Apache. This will have the <code class="literal">APP-SERVER</code> role for secure XML services.<br>
<br>
<code class="command-line"><span class="prompt">~/certutils-X.X$</span> sudo ./mkcert --common "Apache" --organization "Apache" --unit "Apache" /etc/apache/ssl-certs/apache.pem</code>
<br>
<h2 id="tlvfile">tlvfile <a href="#tlvfile" title="Link">link</a></h2>
<code class="literal">tlvfile</code> is used to build or parse <code class="literal">.tlv</code> 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.<br>
<br>
<table>
<tbody>
<tr>
<td><b>SAST</b></td>
<td>System Administrator Security Token, signs and verifies <code class="literal">.tlv</code> files</td>
</tr>
<tr>
<td><b>CCM</b></td>
<td>Verifies the SIP-TLS connection to Asterisk</td>
</tr>
<tr>
<td><b>TFTP</b></td>
<td>Signs provisioning files downloaded via HTTP or TFTP (RSA) and verifies HTTPS provisioning connections (EC)</td>
</tr>
<tr>
<td><b>CCM+TFTP</b></td>
<td>Combined <code class="literal">CCM</code> and <code class="literal">TFTP</code> roles</td>
</tr>
<tr>
<td><b>CAPF</b></td>
<td>Verifies the SSL connection to the Certificate Authentication Proxy Service</td>
</tr>
<tr>
<td><b>APP-SERVER</b></td>
<td>Verifies HTTPS connections to phone XML services</td>
</tr>
<tr>
<td><b>TVS</b></td>
<td>Verifies the SSL connection to the Trust Verification Service</td>
</tr>
</tbody>
</table>
<br>
<b>Note</b>: Once a phone has installed a <code class="literal">.tlv</code> new versions of that file can only be signed by a previously known certificate with the <code class="literal">SAST</code> role. A <code class="literal">.tlv</code> can have a maximum of <code class="literal">2</code> certificates with the <code class="literal">SAST</code> role.<br>
<br>
<b>1.</b> Create an <code class="literal">ITLFile.tlv</code> in the tftpboot provisioning directory, the certificate used to sign the <code class="literal">.tlv</code> file is automatically included as providing the <code class="literal">SAST</code> role.<br>
<br>
<code class="command-line"><span class="prompt">~/certutils-X.X$</span> 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</code>
<br>
<b>2.</b> Optionally, the default <code class="literal">ITLFile.tlv</code> can be overridden using a file name based on the MAC address of the phone, eg: <code class="literal">ITLSEP58971ECC97C1.tlv</code>.<br>
<br>
<code class="command-line"><span class="prompt">~/certutils-X.X$</span> 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</code>
<br>
<b>3.</b> Optionally, additional certificates can be included using a file name based on the MAC address of the phone, eg: <code class="literal">CTLSEP58971ECC97C1.tlv</code>.<br>
<br>
<code class="command-line"><span class="prompt">~/certutils-X.X$</span> 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</code>
<br>
<b>4.</b> Optionally, use HTTPS provisioning for SEPMAC.cnf.xml and signing for the other configuration files. <b>Note</b>: the certificate used to verify the HTTPS connection must use an EC (Elliptic Curve) key and have a version of <code class="literal">1.1</code>.<br>
<br>
<code class="command-line"><span class="prompt">~/certutils-X.X$</span> 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</code>
<br>
<b>5.</b> Enable SIP-TLS mode by setting <<code class="tag">transportLayerProtocol</code>> to <code class="literal">3</code> and setting <<code class="tag">deviceSecurityMode</code>> to either <code class="literal">2</code> (Authenticated) or <code class="literal">3</code> (Encrypted) in <a href="sepmac-cnf-xml.html">SEPMAC.cnf.xml</a>. Optionally, any XML services can be configured to use HTTPS.<br>
<br>
<h2 id="libsrtp">libsrtp <a href="#libsrtp" title="Link">link</a></h2>
To use secure (encrypted) RTP <code class="literal">libsrtp</code> must be installed. The latest release is available from the <a href="https://github.com/cisco/libsrtp/releases"><span class="icon">open_in_browser</span> libsrtp GitHub repository</a>.<br>
<br>
<code class="command-line"><span class="prompt">~/libsrtp-X.X.X$</span> ./configure --prefix=/usr --enable-openssl
<span class="prompt">~/libsrtp-X.X.X$</span> make shared_library
<span class="prompt">~/libsrtp-X.X.X$</span> sudo make install</code>
<br>
<h2 id="sgnfile">sgnfile <a href="#sgnfile" title="Link">link</a></h2>
<code class="literal">sgnfile</code> is used to build or parse <code class="literal">.sgn</code> 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 <code class="literal">TFTP</code> role has been included in the phone's <code class="literal">.tlv</code> file.<br>
<br>
<b>1.</b> Sign SEPMAC.cnf.xml, soft-key and dial-plan files.<br>
<br>
<code class="command-line"><span class="prompt">~/certutils-X.X$</span> sudo ./sgnfile --build /var/lib/tftpboot/SEP58971ECC97C1.cnf.xml --tftp /etc/asterisk/keys/asterisk.pem
<span class="prompt">~/certutils-X.X$</span> sudo ./sgnfile --build /var/lib/tftpboot/SoftKeys.xml --tftp /etc/asterisk/keys/asterisk.pem
<span class="prompt">~/certutils-X.X$</span> sudo ./sgnfile --build /var/lib/tftpboot/DialTemplate.xml --tftp /etc/asterisk/keys/asterisk.pem</code>
<br>
<b>2.</b> Sign network and user locale files.<br>
<br>
<code class="command-line"><span class="prompt">~/certutils-X.X$</span> sudo ./sgnfile --build /var/lib/tftpboot/New_Zealand/g3-tones.xml --tftp /etc/asterisk/keys/asterisk.pem \
--filename New_Zealand/g3-tones.xml.sgn
<span class="prompt">~/certutils-X.X$</span> sudo ./sgnfile --build /var/lib/tftpboot/New_Zealand/mk-sip.jar --tftp /etc/asterisk/keys/asterisk.pem \
--filename New_Zealand/mk-sip.jar.sgn</code>
<br>
<b>3.</b> Sign ring-tones (optional).<br>
<br>
<code class="command-line"><span class="prompt">~/certutils-X.X$</span> sudo ./sgnfile --build /var/lib/tftpboot/Ringlist.xml --tftp /etc/asterisk/keys/asterisk.pem
<span class="prompt">~/certutils-X.X$</span> sudo ./sgnfile --build /var/lib/tftpboot/Old_Telephone.raw --tftp /etc/asterisk/keys/asterisk.pem</code>
<br>
<b>4.</b> Sign background images (optional).<br>
<br>
<code class="command-line"><span class="prompt">~/certutils-X.X$</span> sudo ./sgnfile --build /var/lib/tftpboot/Desktops/320x196x4/List.xml --tftp /etc/asterisk/keys/asterisk.pem \
--filename Desktops/320x196x4/List.xml.sgn
<span class="prompt">~/certutils-X.X$</span> sudo ./sgnfile --build /var/lib/tftpboot/Desktops/320x196x4/Logo.png --tftp /etc/asterisk/keys/asterisk.pem \
--filename Desktops/320x196x4/Logo.png.sgn
<span class="prompt">~/certutils-X.X$</span> sudo ./sgnfile --build /var/lib/tftpboot/Desktops/320x196x4/Logo_Preview.png --tftp /etc/asterisk/keys/asterisk.pem \
--filename Desktops/320x196x4/Logo_Preview.png.sgn</code>
<br>
<h2 id="enccnf">enccnf <a href="#enccnf" title="Link">link</a></h2>
<code class="literal">enccnf</code> is used to build or parse <code class="literal">.enc.sgn</code> files which is an encrypted SEPMAC.cnf.xml phone configuration file that has a signature from a certificate with the <code class="literal">TFTP</code> role. The public key from the phone's MIC or LSC is used to encrypt the file, see <a href="certificate-enrollment.html">Certificate Enrollment</a> for more information. <b>Note</b>: <code class="literal">enccnf</code> will delete the <code class="literal">.cnf.xml</code> file after creating the <code class="literal">.sgn</code> and <code class="literal">.enc.sgn</code> file.<br>
<br>
<code class="command-line"><span class="prompt">~/certutils-X.X$</span> sudo ./enccnf --build /var/lib/tfptboot/SEP58971ECC97C1.cnf.xml --tftp /etc/asterisk/keys/asterisk.pem \
--certificate /var/lib/capf/SEP58971ECC97C1.pem</code>
</article>
</main>
<footer>
<span class="icon">copyright</span> Gareth Palmer and individual contributors. Documentation distributed under <a href="LICENSE">CC BY 4.0</a>.
</footer>
</body>
</html>