Views

Difference between revisions of "DLS FAQ"

The Wiki of Unify contains information on clients and devices, communications systems and unified communications. - Unify GmbH & Co. KG is a Trademark Licensee of Siemens AG.

Jump to: navigation, search
m (→‎format update)
 
(9 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
<div class="breadcrumb">
+
{{Breadcrumb|0|0|Deployment Service}}
−
{{up}} [[FAQ]]
 
−
</div>
 
  
−
==== What is DLS ? ====
+
== General ==
 +
 
 +
=== What is DLS ? ===
 
: See [[Deployment Service]].
 
: See [[Deployment Service]].
  
−
==== What is DlsAPI ? ====
+
=== What is DlsAPI ? ===
 
: See [[DlsAPI]].
 
: See [[DlsAPI]].
 +
 +
=== What is WPI ? ===
 +
: See [[OpenStage_WPI|WPI]].
 +
 +
== DLS Server Administration ==
 +
 +
=== How can I access the web-based management of DLS (DLS-GUI)? ===
 +
: See the current DLS release notes, chapter 4.5.5.
 +
 +
=== How can I configure a customized certificate for the https access to DLS-GUI? ===
 +
 +
==== For DLS Version V6 and onwards ====
 +
 +
The DLS server certificates used for Server authentication during HTTPS access to the DLS-GUI can be customized via the DLS-GUI (Administration -> Server Configuration -> TLS Connector Configuration).<br>
 +
 +
Change the certificates used for server authentication on the HTTPS interface to the DLS GUI. Use customer’s CA, or configure internal DLS CA to generate DLS certificates or import customer certificates as files.
 +
 +
----
 +
==== For DLS Version V3 ====
 +
 +
====Introduction====
 +
DLS provides both http (default port 18080) and https (port 10443) for browser-based access to DLS-GUI.<br/>
 +
https is [http://en.wikipedia.org/wiki/Transport_Layer_Security TLS/SSL]-protected http and provides the same access to the web server as http, with the following security add-ons:
 +
* end-to-end encryption of all data exchanged between the browser and the web server
 +
* authentication of the web server by the browser
 +
 +
DLS uses [http://tomcat.apache.org/ Apache Tomcat 5.5] as web server, and is equipped with a default certificate that is used to establish https connections.
 +
This provides end-to-end encryption without further configuration steps.<br/>
 +
However, the browser is not able to authenticate the web server based on its default certificate for two reasons:
 +
* The certificate authority (CA) that has signed the DLS server's default certificate is not trusted in the customer's corporate network.<br/>(All trusted CAs are or have to be configured in the customer employee's browser, but the signing CA of the default certificate is not / should not be among them.)
 +
* The name of the default certificate ("Deployment Service V2") does not match the domain name (or IP address) of the DLS server as installed in the customer's corporate network.<br/>(There is no binding of a particular certificate to a particular server.)
 +
Missing authentication makes the encrypted connection between the browser and the DLS web server prone to [http://en.wikipedia.org/wiki/Man-in-the-middle_attack Man-in-the-Middle Attacks].
 +
 +
It is therefore recommended to customize the DLS server installation in the following two ways:
 +
# enable https (i.e. SSL-protected http) only, and disable http
 +
# install and activate a customized SSL certificate for use by the DLS web server
 +
The description below is a step-by-step instruction to achieve this.<br/>
 +
In general, the configuration steps are conformant to typical Apache Tomcat installations.
 +
For further technical details you may therefore refer to the [http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html Tomcat 5.5 SSL configuration guide].
 +
 +
Notes:
 +
* This description is also valid for https access to the DlsAPI (port 10444).
 +
* Future versions of DLS may switch to [http://tomcat.apache.org/ Apache Tomcat 6.x]. The description remains valid; for technical details, you may then refer to [http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html Tomcat 6.x SSL configuration guide].
 +
* The description is '''not''' valid for OpenScape Voice / Linux-based installations of the DLS server.<br/>Here, DLS does not provide its own Apache Tomcat web server, but makes use of the Tomcat web server provided by the OpenScape application platform. The associated instructions will be provided soon.
 +
 +
====Certificate Requirements====
 +
 +
The certificate must be a X.509 v3 certificate according to the [http://en.wikipedia.org/wiki/X.509 X.509 standard], as defined in [http://tools.ietf.org/html/rfc5280 RFC 5280].<br/>
 +
The following table provides a summary of recommended settings in certificate fields and extensions.
 +
 +
'''Contact the customer's IT or PKI administration to order an appropriate certificate.'''
 +
 +
{| {{DefaultTable}}
 +
! X.509 v3 Extension
 +
! Description
 +
! Value
 +
|-
 +
| Version
 +
| X.509 Version
 +
| 3
 +
|-
 +
| Serial Number
 +
| Serial number of the certificate as issued by the Certificate Authority (CA)
 +
| automatically ''(must be unique for each certificate signed by the same CA)''
 +
|-
 +
| Signature
 +
| ID of signature algorithm
 +
| sha1withRSAEncryption ''(avoid the use of MD5 as signature algorithm, as this is considered insecure, see e.g. [http://www.kb.cert.org/vuls/id/836068])''
 +
|-
 +
| Issuer
 +
| Distinguished name of the customer's enterprise server CA
 +
| ''as defined by the customer's CA''
 +
|-
 +
| Validity
 +
| Validity period of the certificate
 +
| ''depends on customer's policy - typically 1 to 3 years''
 +
|-
 +
| Subject
 +
| Distinguished name (DN) of the DLS web server
 +
| The Common Name (CN) as part of the DN is not a person's name, but must be the domain name (FQDN) of the DLS web server<br/>(in multinode server installations, this must be the FQDN of the '''virtual''' DLS server address)
 +
|-
 +
| Subject Public Key Info
 +
| Algorithm and key length of the public key the certificate is created for
 +
| Algorithm: rsaEncryption<br/>Keylength: 1024 or 2048 bits (4098 bits are unusual, but supported as well)
 +
|-
 +
| Basic Constraints
 +
| X.509 v3 constraints of the certificate
 +
| CA:FALSE
 +
|-
 +
| Key Usage
 +
| Intended purpose of the key contained in the certificate
 +
| digitalSignature, keyEncipherment
 +
|-
 +
| Extended Key Usage
 +
| Intended purpose of the key contained in the certificate.<br/>Defined in addition to or in place of the basic purposes indicated in ''Key Usage'' above.
 +
| id-kp-serverAuth (i.e. TLS WWW server authentication)
 +
|-
 +
|}
 +
 +
====Preconditions - What you need====
 +
* A PKCS#12 file that contains the private key and certificate you want to enable for DLS server (usually used extension for this file type on Windows OS is: ".p12").<br/>''The sample filename used in this instruction is: <code>My-DLS-Server-Credentials.p12</code>''
 +
* The passphrase this PKCS#12 file is encrypted with.<br/>''The sample passphrase is: <code>My-Passphrase</code>''
 +
 +
====Notes====
 +
* '''The private key contained in the PKCS#12 file needs to be protected to prevent the server certificate from misuse by unauthorized persons!'''<br/>Therefore, ensure that only authorized DLS server administrators and customer IT/PKI administrators have access to this file.
 +
This particularly also applies to the location where the file is stored on the DLS server (see step-by-step instructions below.)
 +
* You can configure an '''individual certificate per port'''; for example: keep DlsAPI port 10444 running with the default certificate, and apply the configuration change to DLS-GUI port 10443 only. The description below changes both to the same new individual certificate.
 +
* Do '''not''' change the configuration for the '''Workpoint Interface''' (https ports 18443 / 18444).
 +
* The changes may be lost, when the '''DLS server SW is updated''' -> you need to repeat the steps after DLS software update is done.<br/>(The default contents of server.xml may change with any new DLS version. After update do not just copy a saved version of your server.xml, but repeat the edit steps again, based on the new default server.xml file)
 +
* In case of '''DLS multinode installations''' (up to 4 DLS nodes share the same '''virtual''' FQDN & IP address):
 +
** All DLS nodes share the same certificate, which has to be issued for the virtual FQDN
 +
** The changes described below must be applied to all DLS nodes
 +
 +
====Step-by-Step Instruction====
 +
 +
* On DLS Server, copy <code>My-DLS-Server-Credentials.p12</code> into the directory: <DLS-Installdirectory>\Tomcat5\conf
 +
* Stop DLS Service
 +
* Edit the Tomcat configuration file: <DLS-Installdirectory>\Tomcat5\conf\server.xml:
 +
** Search for the connectors for DLS-GUI/http (port=18080), DLS-GUI/https (port=10443) and DlsAPI/https (port=10444); connectors are indicated by the XML tags:
 +
<pre>
 +
<Connector ... port=nnn ...>
 +
...
 +
</Connector>
 +
</pre>
 +
** Delete the connector for http completely
 +
** Within the https connectors, replace the following XML attributes:
 +
*** Change <code>keystoreFile="conf/DeploymentServiceV2.p12"</code> to <code>KeystoreFile="conf/My-DLS-Server-Credentials.p12"</code>
 +
*** Change <code>keystorePass="qe13.eq31"</code> to <code>KeystorePass="My-Passphrase"
 +
** Save the changes of the file server.xml and quit the editor
 +
* Start DLS Service - the DLS web service now starts using the freshly installed customized SSL certificate.

Latest revision as of 08:25, 16 January 2014

You are here:  

Icon linkarrow.gif Home  Icon linkarrow.gif Deployment Service  Icon linkarrow.gif DLS FAQ

General

What is DLS ?

See Deployment Service.

What is DlsAPI ?

See DlsAPI.

What is WPI ?

See WPI.

DLS Server Administration

How can I access the web-based management of DLS (DLS-GUI)?

See the current DLS release notes, chapter 4.5.5.

How can I configure a customized certificate for the https access to DLS-GUI?

For DLS Version V6 and onwards

The DLS server certificates used for Server authentication during HTTPS access to the DLS-GUI can be customized via the DLS-GUI (Administration -> Server Configuration -> TLS Connector Configuration).

Change the certificates used for server authentication on the HTTPS interface to the DLS GUI. Use customer’s CA, or configure internal DLS CA to generate DLS certificates or import customer certificates as files.

For DLS Version V3

Introduction

DLS provides both http (default port 18080) and https (port 10443) for browser-based access to DLS-GUI.
https is TLS/SSL-protected http and provides the same access to the web server as http, with the following security add-ons:

  • end-to-end encryption of all data exchanged between the browser and the web server
  • authentication of the web server by the browser

DLS uses Apache Tomcat 5.5 as web server, and is equipped with a default certificate that is used to establish https connections. This provides end-to-end encryption without further configuration steps.
However, the browser is not able to authenticate the web server based on its default certificate for two reasons:

  • The certificate authority (CA) that has signed the DLS server's default certificate is not trusted in the customer's corporate network.
    (All trusted CAs are or have to be configured in the customer employee's browser, but the signing CA of the default certificate is not / should not be among them.)
  • The name of the default certificate ("Deployment Service V2") does not match the domain name (or IP address) of the DLS server as installed in the customer's corporate network.
    (There is no binding of a particular certificate to a particular server.)

Missing authentication makes the encrypted connection between the browser and the DLS web server prone to Man-in-the-Middle Attacks.

It is therefore recommended to customize the DLS server installation in the following two ways:

  1. enable https (i.e. SSL-protected http) only, and disable http
  2. install and activate a customized SSL certificate for use by the DLS web server

The description below is a step-by-step instruction to achieve this.
In general, the configuration steps are conformant to typical Apache Tomcat installations. For further technical details you may therefore refer to the Tomcat 5.5 SSL configuration guide.

Notes:

  • This description is also valid for https access to the DlsAPI (port 10444).
  • Future versions of DLS may switch to Apache Tomcat 6.x. The description remains valid; for technical details, you may then refer to Tomcat 6.x SSL configuration guide.
  • The description is not valid for OpenScape Voice / Linux-based installations of the DLS server.
    Here, DLS does not provide its own Apache Tomcat web server, but makes use of the Tomcat web server provided by the OpenScape application platform. The associated instructions will be provided soon.

Certificate Requirements

The certificate must be a X.509 v3 certificate according to the X.509 standard, as defined in RFC 5280.
The following table provides a summary of recommended settings in certificate fields and extensions.

Contact the customer's IT or PKI administration to order an appropriate certificate.

X.509 v3 Extension Description Value
Version X.509 Version 3
Serial Number Serial number of the certificate as issued by the Certificate Authority (CA) automatically (must be unique for each certificate signed by the same CA)
Signature ID of signature algorithm sha1withRSAEncryption (avoid the use of MD5 as signature algorithm, as this is considered insecure, see e.g. [1])
Issuer Distinguished name of the customer's enterprise server CA as defined by the customer's CA
Validity Validity period of the certificate depends on customer's policy - typically 1 to 3 years
Subject Distinguished name (DN) of the DLS web server The Common Name (CN) as part of the DN is not a person's name, but must be the domain name (FQDN) of the DLS web server
(in multinode server installations, this must be the FQDN of the virtual DLS server address)
Subject Public Key Info Algorithm and key length of the public key the certificate is created for Algorithm: rsaEncryption
Keylength: 1024 or 2048 bits (4098 bits are unusual, but supported as well)
Basic Constraints X.509 v3 constraints of the certificate CA:FALSE
Key Usage Intended purpose of the key contained in the certificate digitalSignature, keyEncipherment
Extended Key Usage Intended purpose of the key contained in the certificate.
Defined in addition to or in place of the basic purposes indicated in Key Usage above. 		id-kp-serverAuth (i.e. TLS WWW server authentication)

Preconditions - What you need

  • A PKCS#12 file that contains the private key and certificate you want to enable for DLS server (usually used extension for this file type on Windows OS is: ".p12").
    The sample filename used in this instruction is: My-DLS-Server-Credentials.p12
  • The passphrase this PKCS#12 file is encrypted with.
    The sample passphrase is: My-Passphrase

Notes

  • The private key contained in the PKCS#12 file needs to be protected to prevent the server certificate from misuse by unauthorized persons!
    Therefore, ensure that only authorized DLS server administrators and customer IT/PKI administrators have access to this file.

This particularly also applies to the location where the file is stored on the DLS server (see step-by-step instructions below.)

  • You can configure an individual certificate per port; for example: keep DlsAPI port 10444 running with the default certificate, and apply the configuration change to DLS-GUI port 10443 only. The description below changes both to the same new individual certificate.
  • Do not change the configuration for the Workpoint Interface (https ports 18443 / 18444).
  • The changes may be lost, when the DLS server SW is updated -> you need to repeat the steps after DLS software update is done.
    (The default contents of server.xml may change with any new DLS version. After update do not just copy a saved version of your server.xml, but repeat the edit steps again, based on the new default server.xml file)
  • In case of DLS multinode installations (up to 4 DLS nodes share the same virtual FQDN & IP address):
    • All DLS nodes share the same certificate, which has to be issued for the virtual FQDN
    • The changes described below must be applied to all DLS nodes

Step-by-Step Instruction

  • On DLS Server, copy My-DLS-Server-Credentials.p12 into the directory: <DLS-Installdirectory>\Tomcat5\conf
  • Stop DLS Service
  • Edit the Tomcat configuration file: <DLS-Installdirectory>\Tomcat5\conf\server.xml:
    • Search for the connectors for DLS-GUI/http (port=18080), DLS-GUI/https (port=10443) and DlsAPI/https (port=10444); connectors are indicated by the XML tags:
	<Connector ... port=nnn ...>
		...
	</Connector>
    • Delete the connector for http completely
    • Within the https connectors, replace the following XML attributes:
      • Change keystoreFile="conf/DeploymentServiceV2.p12" to KeystoreFile="conf/My-DLS-Server-Credentials.p12"
      • Change keystorePass="qe13.eq31" to KeystorePass="My-Passphrase"
    • Save the changes of the file server.xml and quit the editor
  • Start DLS Service - the DLS web service now starts using the freshly installed customized SSL certificate.
Retrieved from "http://wiki.unify.com/index.php?title=DLS_FAQ&oldid=40914"