How to configure multiple SSL certificates on a single Host Port (SNI)

SSL certificates are tied to fully qualified domain names such as www.mycompany.com or wildcard domains such as *.mycompany.com. This article describes how to configure Wowza Streaming Engine™ to use multiple SSL certificates on a single Host Port definition, which enables a single Wowza Streaming Engine port to respond to SSL requests from multiple domains.

To use multiple SSL certificates on a single Host Port, you must create a map file that maps domain names or domain wildcards to Java Key Store (JKS) files. Mapping domain names to Java KeyStores relies on a Transport Layer Security (TLS) extension called Server Name Identification (SNI) that is supported by most browsers. When using SNI, the domain name of a given HTTPS or RTMPS request is sent to a server as part of the TLS handshake process.

Note: Wowza Streaming Engine 4.5.0 or later is required.

Create a map file

First, create a text file named DomainToKeyStoreMap.txt in the [install-dir]/conf folder. This is the map file that maps domain names to Java KeyStore files. The format of the map file should contain the following template:
 
[domain-name-1]={"keyStorePath":"${com.wowza.wms.context.VHostConfigHome}/conf/[keystore1].jks", "keyStorePassword":"[password1]", "keyStoreType":"JKS"}
[domain-name-2]={"keyStorePath":"${com.wowza.wms.context.VHostConfigHome}/conf/[keystore2].jks", "keyStorePassword":"[password2]", "keyStoreType":"JKS"}
Where the [domain-name] placeholders are either a fully qualified domain name (www.mycompany.com), a wild-carded domain name (*.mycompany.com), or an asterisk (*) character (matches all domains). Domain name matching begins at the top of the file and progress down the domain name list until there is a match. If there isn't a match, the last entry in the file is used. If the web server does not send SNI information, the last entry in the file is used.

The following is an example map file:
 
*.mycompany.com={"keyStorePath":"${com.wowza.wms.context.VHostConfigHome}/conf/mycompany.com.jks", "keyStorePassword":"123456", "keyStoreType":"JKS"}
www.acme.com={"keyStorePath":"${com.wowza.wms.context.VHostConfigHome}/conf/www.acme.com.jks", "keyStorePassword":"123456", "keyStoreType":"JKS"}
*={"keyStorePath":"${com.wowza.wms.context.VHostConfigHome}/conf/global.jks", "keyStorePassword":"123456", "keyStoreType":"JKS"}
You can use multiple map files or share a map file between multiple Host Port configurations that use SSL. Wowza Streaming Engine will read the map file on start and will monitor the map file every few seconds for changes. If the file changes, Wowza Streaming Engine reloads the file and the new map entries are used for future connections. If there are any syntax errors while reading the file, they are logged and the older version of the map file will be used by the server until a properly formatted map file is read.

Create a Host Port

Second, create a new Host Port in Wowza Streaming Engine Manager:
 
  1. Click Server at the top of the manager page, and then click Virtual Host Setup in the contents panel.
     
  2. In the Virtual Host Setup page, click Edit and then in the Host Ports section, click Add Host Port.
     
  3. Enter a Name, IP Address, and Port.
     
  4. Click Add and then click Save to add the Host Port and save your changes. Restart the media server to apply the changes.

Add your map file to VHost.xml

Third, configure VHost.xml to use your map file instead of a single Java KeyStore file:
 
  1. Open [install-dir]/conf/VHost.xml in a text editor and navigate to the <HostPort>/<SSLConfig> container.
  2. Add a the DomainToKeyStoreMapPath property and set the path to your map file as the value. The <HostPort>/<SSLConfig> container should look like the following:
     
    <HostPort>
    	...
    	<SSLConfig>
    		<KeyStorePath></KeyStorePath>
    		<KeyStorePassword></KeyStorePassword>
    		<KeyStoreType>JKS</KeyStoreType>
    		<DomainToKeyStoreMapPath>${com.wowza.wms.context.VHostConfigHome}/conf/DomainToKeyStoreMap.txt</DomainToKeyStoreMapPath>
    		<SSLProtocol>TLS</SSLProtocol>
    		<Algorithm>SunX509</Algorithm>
    		<CipherSuites></CipherSuites>
    		<Protocols></Protocols>
    	</SSLConfig>
    	...
    </HostPort>
After configured, it's best not to use Wowza Streaming Engine Manager to edit this Host Port entry.

To debug mapping from domain to Java KeyStore, add the following property to the Properties container at the bottom of [install-dir]/conf/VHost.xml:
 
<Property>
	<Name>sslLogConnectionInfo</Name>
	<Value>true</Value>
	<Type>Boolean</Type>
</Property>

Originally Published: For Wowza Streaming Engine 4.5.0 on 06-23-2016.
 

If you're having problems or want to discuss this article, post in our forum.