<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/2041/1/7/_/styles/combined.css?spaceKey=TOP&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://wiki.asterisk.org/wiki/display/TOP/Ice+Support+for+SSL+and+TLS">Ice Support for SSL and TLS</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~khunt">Ken Hunt</a>
</h4>
<br/>
<h4>Changes (5)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-unchanged" >h4. Introduction <br></td></tr>
<tr><td class="diff-changed-lines" >This page provides information on support for [Secure Sockets Layer (SSL)|http://en.wikipedia.org/wiki/Secure_Sockets_Layer] <span class="diff-added-words"style="background-color: #dfd;">and [Transport Layer Security (TLS)|http://en.wikipedia.org/wiki/Transport_Layer_Security]</span> in Ice. It is not intended as a replacement for ZeroC's own [Ice documentation related to <span class="diff-changed-words">SSL<span class="diff-added-chars"style="background-color: #dfd;"> and TLS</span>|http://www.zeroc.com/doc/Ice-3.4.1/manual/IceSSL.html],</span> but rather a discussion / overview of relevant points as this functionality pertains to Asterisk SCF. <br></td></tr>
<tr><td class="diff-unchanged" > <br>Note that this page is relevant to communications over Ice, which means communications between Asterisk SCF components. It does not address communications between Asterisk SCF and external components using other (i.e. non-Ice) protocols. For example, Asterisk SCF's SIP Session Gateway communicates externally using the SIP protocol, and internally (to other Asterisk SCF components such as the Routing Service) using Ice. Such Gateway components of Asterisk SCF will provide other mechanisms for securing non-Ice-based communication. <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >h4. IceSSL Plugin and Configuration <br> <br></td></tr>
<tr><td class="diff-changed-lines" ># Ice provides support for SSL <span class="diff-added-words"style="background-color: #dfd;">and TLS</span> via the IceSSL plugin. The IceSSL plugin is built on [OpenSSL|http://www.openssl.org/]. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"># The IceSSL plugin can be configured to support SSL, TLS or both via the {{IceSSL.Protocols}} property, as documented [here|http://www.zeroc.com/doc/Ice-3.4.1-IceTouch/manual/PropRef.50.12.html]. <br></td></tr>
<tr><td class="diff-changed-lines" ># Integrating <span class="diff-changed-words">SSL<span class="diff-added-chars"style="background-color: #dfd;">/TLS</span></span> will typically require no changes to source code, but rather to a component's configuration. <br></td></tr>
<tr><td class="diff-unchanged" >{code:title=Defining multiple endpoints on an adapter} <br>MyAdapter.Endpoints=tcp ‑p 4063:ssl ‑p 4064:udp ‑p 4063 <br>{code} <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{info} The IceSSL plugin handles both SSL and TLS using the "ssl" protocol identifier. Since the distinction between SSL and TLS, from the API perspective, is non-existent, other than the {{IceSSL.Protocols}} property already mentioned. The rest of this write-up will refer to SSL / TLS simply as "SSL" unless a further distinction required.{info} <br></td></tr>
<tr><td class="diff-unchanged" >#* Note that UDP can use the same port number as TCP or SSL since it's a different protocol with its own set of ports. SSL is a layer over TCP, so SSL and TCP endpoints can't have the same port number. <br>#* To provide only secure endpoints for an object adapter: {code}MyAdapter.Endpoints=ssl ‑p 4064{code} <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<h4><a name="IceSupportforSSLandTLS-Introduction"></a>Introduction</h4>
<p>This page provides information on support for <a href="http://en.wikipedia.org/wiki/Secure_Sockets_Layer" class="external-link" rel="nofollow">Secure Sockets Layer (SSL)</a> and <a href="http://en.wikipedia.org/wiki/Transport_Layer_Security" class="external-link" rel="nofollow">Transport Layer Security (TLS)</a> in Ice. It is not intended as a replacement for ZeroC's own <a href="http://www.zeroc.com/doc/Ice-3.4.1/manual/IceSSL.html" class="external-link" rel="nofollow">Ice documentation related to SSL and TLS</a>, but rather a discussion / overview of relevant points as this functionality pertains to Asterisk SCF.</p>
<p>Note that this page is relevant to communications over Ice, which means communications between Asterisk SCF components. It does not address communications between Asterisk SCF and external components using other (i.e. non-Ice) protocols. For example, Asterisk SCF's SIP Session Gateway communicates externally using the SIP protocol, and internally (to other Asterisk SCF components such as the Routing Service) using Ice. Such Gateway components of Asterisk SCF will provide other mechanisms for securing non-Ice-based communication. </p>
<h4><a name="IceSupportforSSLandTLS-IceSSLPluginandConfiguration"></a>IceSSL Plugin and Configuration</h4>
<ol>
<li>Ice provides support for SSL and TLS via the IceSSL plugin. The IceSSL plugin is built on <a href="http://www.openssl.org/" class="external-link" rel="nofollow">OpenSSL</a>.</li>
<li>The IceSSL plugin can be configured to support SSL, TLS or both via the <tt>IceSSL.Protocols</tt> property, as documented <a href="http://www.zeroc.com/doc/Ice-3.4.1-IceTouch/manual/PropRef.50.12.html" class="external-link" rel="nofollow">here</a>.</li>
<li>Integrating SSL/TLS will typically require no changes to source code, but rather to a component's configuration.
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Defining multiple endpoints on an adapter</b></div><div class="codeContent panelContent">
<script type="syntaxhighlighter" class="toolbar: false; theme: Confluence; brush: java; gutter: false"><![CDATA[
MyAdapter.Endpoints=tcp ‑p 4063:ssl ‑p 4064:udp ‑p 4063
]]></script>
</div></div>
<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>The IceSSL plugin handles both SSL and TLS using the "ssl" protocol identifier. Since the distinction between SSL and TLS, from the API perspective, is non-existent, other than the <tt>IceSSL.Protocols</tt> property already mentioned. The rest of this write-up will refer to SSL / TLS simply as "SSL" unless a further distinction required.</td></tr></table></div>
<ul>
<li>Note that UDP can use the same port number as TCP or SSL since it's a different protocol with its own set of ports. SSL is a layer over TCP, so SSL and TCP endpoints can't have the same port number.</li>
<li>To provide only secure endpoints for an object adapter: <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<script type="syntaxhighlighter" class="toolbar: false; theme: Confluence; brush: java; gutter: false"><![CDATA[MyAdapter.Endpoints=ssl ‑p 4064]]></script>
</div></div></li>
</ul>
</li>
<li>In addition to changes to an Asterisk SCF component's object adapter configuration, the IceSSL plugin also requires configuration data, which can be placed in the component's configuration file.
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>IceSSL plugin configuration parameters</b></div><div class="codeContent panelContent">
<script type="syntaxhighlighter" class="toolbar: false; theme: Confluence; brush: java; gutter: false"><![CDATA[
Ice.Plugin.IceSSL=IceSSL:createIceSSL # Enable IceSSL plugin. This loads the plugin's DLL.
IceSSL.DefaultDir=/opt/certs # Identifies location of certificates
IceSSL.CertFile=pubkey.pem # Identifies filename within the DefaultDir specified above.
IceSSL.KeyFile=privkey.pem # " " "
IceSSL.CertAuthFile=ca.pem # " " "
IceSSL.Password=password # The password of the private key (if key files are encrypted).
# For DSA-generated keys, or using both RSA and DSA, refer to additional configuration parameters in the Ice docs.
# Additional configuration also applies to using Anonymous Diffie-Hellman (ADH) cipher, where no keys are involved. Again, refer to the Ice docs.
]]></script>
</div></div>
<ul>
<li>Storing passwords in a plain-text file (as shown above) is viable only if your server is in a highly secure environment.</li>
<li>Alternatives:
<ol>
<li>Use unsecured key file (again, only in a secure, controlled environment)</li>
<li>Application takes additional responsibility for managing authentication. Examples such as password callbacks and custom certificate verifier plugins <a href="http://www.zeroc.com/doc/Ice-3.4.1/manual/IceSSL.42.6.html" class="external-link" rel="nofollow">described here</a>.</li>
</ol>
</li>
</ul>
</li>
<li>Cyphersuites (particular combinations of encryption, authentication and hashing algorithm) that can be used during handshake negotiation with a peer can be configured. This is useful, for example, if you wanted to eliminate relatively insecure ciphersuites, such as ADH.
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<script type="syntaxhighlighter" class="toolbar: false; theme: Confluence; brush: java; gutter: false"><![CDATA[
IceSSL.Ciphers=ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH
]]></script>
</div></div>
<ul>
<li>For more information on configuring cyphersuites, read the <a href="http://www.zeroc.com/doc/Ice-3.4.1/manual/IceSSL.42.4.html" class="external-link" rel="nofollow">Ice documentation</a>.</li>
</ul>
</li>
<li>Ice can take additional steps to determine whether a peer should be trusted, beyond what OpenSSL already does.
<ul>
<li>The Ice.TrustOnly properties define a collection of acceptance and rejection filters. For details, read the Ice documents on <a href="http://www.zeroc.com/doc/Ice-3.4.1-IceTouch/manual/PropRef.50.12.html" class="external-link" rel="nofollow">IceSSL Properties</a>.</li>
</ul>
</li>
<li>Components written in C++ and Java can interact directly with the IceSSL plugin.
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<script type="syntaxhighlighter" class="toolbar: false; theme: Confluence; brush: java; gutter: false"><![CDATA[
class Plugin : public Ice:Plugin
{
plugin:
// ....
virtual void setCertificateVerifier(const CertificateVerifierPtr&) = 0;
virtual void setPasswordPrompt(const PasswordPromptPtr&) = 0;
// ...
]]></script>
</div></div>
<ul>
<li>The <tt>setCertificateVerifier</tt> allows a custom verifier object to be set that gets invoked for each new connection. Ice provides defined classes for obtaining SSL connection information, including providing access to installed certificates, to make writing Certificate Verifiers relatively easy to do. Refer to the <a href="http://www.zeroc.com/doc/Ice-3.4.1/manual/IceSSL.42.5.html" class="external-link" rel="nofollow">Ice documents for more information</a>
<ul>
<li>Note: Glacier2, an optional Ice firewall solution, provides its own custom certificate verifier. Refer to <a href="http://www.zeroc.com/doc/Ice-3.4.1-IceTouch/manual/Glacier2.html" class="external-link" rel="nofollow">Glacier2 documentation for more information</a>.</li>
</ul>
</li>
<li>The <tt>setPasswordPrompt</tt> provides a means for applications (i.e. Asterisk SCF components) to supply the IceSSL plugin with passwords as an alternate to plain-text in configuration files.</li>
</ul>
</li>
</ol>
<h4><a name="IceSupportforSSLandTLS-SecurityandProxies"></a>Security and Proxies</h4>
<ol>
<li>Based on the adapter configuration (such as the one shown in the sample code above labeled "Defining multiple endpoints on an adapter"), a proxy may contain a combination of secure and insecure endpoints.</li>
<li>Asterisk SCF makes <b>heavy use of passing proxies between components.</b></li>
<li>A component that cares about secure communications can only ensure that locally-created proxies are secure.
<ul>
<li>Never assume that proxies received over the wire are configured to use secure endpoints.</li>
<li>The component can call <tt>SomePrx->ice_secure(true);</tt> to ensure only secure endpoints are used between the component and the remote servant located by <tt>SomePrx</tt>.</li>
<li>As an alternative to making such a change in a component's code, setting the following configuration property will result in the component using only secure endpoints for all proxies:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<script type="syntaxhighlighter" class="toolbar: false; theme: Confluence; brush: java; gutter: false"><![CDATA[Ice.Override.Secure=1]]></script>
</div></div>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Remember Exception Handling</b><br />Attempting to establish a connection on a proxy that's been set to "secure" when that proxy doesn't contain a secure endpoint results in <tt>NoEndpointException</tt>.</td></tr></table></div></li>
<li>If you want to allow non-secure endpoints, but give precedence to secure endpoints: <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<script type="syntaxhighlighter" class="toolbar: false; theme: Confluence; brush: java; gutter: false"><![CDATA[ Ice.Default.PreferSecure=1]]></script>
</div></div></li>
</ul>
</li>
</ol>
<h4><a name="IceSupportforSSLandTLS-CertificateAuthority"></a>Certificate Authority </h4>
<ul>
<li>Ice provides the Python script <b>iceca</b> to hide the complexities of using the underlying OpenSSL to setup your own certificate authority (CA) to create new certificates.</li>
<li>Using the CA capabilities of OpenSSL, you can create and sign your own certificates for testing.</li>
</ul>
<h4><a name="IceSupportforSSLandTLS-Authoringplugins"></a>Authoring plugins</h4>
<ul>
<li>Ice provides a plugin model for extending Ice functionality. While Asterisk SCF does not require developers to create Ice Plugins, advanced users may wish to use this facility. If you do, be aware that plugins can be developed to have dependencies on one another. A common situation is for plugins to depend on the IceSSL plugin to provide secure operation. In this case, some care must be taken in the order that plugins are loaded, as described in the <a href="http://www.zeroc.com/doc/Ice-3.4.1-IceTouch/manual/Adv_server.33.25.html" class="external-link" rel="nofollow">Ice documentation on creating plugins</a>.</li>
</ul>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;">
<a href="https://wiki.asterisk.org/wiki/users/viewnotifications.action" class="grey">Change Notification Preferences</a>
</div>
<a href="https://wiki.asterisk.org/wiki/display/TOP/Ice+Support+for+SSL+and+TLS">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=12550659&revisedVersion=34&originalVersion=33">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/TOP/Ice+Support+for+SSL+and+TLS?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>