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.
Stefan.Beck (talk | contribs) (Description added: How can I configure a customized certificate for the https access to DLS-GUI) |
Stefan.Beck (talk | contribs) (Added hints to DLS multinode installations) |
||
| Line 78: | Line 78: | ||
| Subject | | Subject | ||
| Distinguished name (DN) of the DLS web server | | 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 | + | | 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 | | Subject Public Key Info | ||
| Line 101: | Line 101: | ||
* '''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. | * '''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.) | 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. | + | * 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). | + | * 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) | + | * 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==== | ====Step-by-Step Instruction==== | ||
Revision as of 11:38, 27 August 2009
Contents
General
What is DLS ?
- See Deployment Service.
What is DlsAPI ?
- See DlsAPI.
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?
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:
- 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.
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 2459.
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 |
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-Cert.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-Cert.p12into 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"toKeystoreFile="conf/My-Cert.p12" - Change
keystorePass="qe13.eq31"toKeystorePass="My-Passphrase"
- Change
- 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.
