Contents
Configuring TLS Parameters in Configuration Manager
Introduction
As described earlier, the Platform SDK Application Template Application Block allows both client and server applications to read TLS parameters from configuration objects. This page describes how to set TLS parameters correctly in those configuration objects.
Configuration objects that will be used, and their relations, are shown in the diagram below:
To edit TLS-related parameters for these objects, you will need to have access to the Annex tab in Configuration Manager.
Precedence of Configuration Objects
Platform SDK uses different sets of configuration objects to configure client- and server-side TLS settings. For TLS parameters, these objects are searched from the most specific object to the most general one. Parameters found in specific objects take precedence over those in more general objects.
Note: This search occurs independently for each supported TLS parameter.
Location of specific TLS parameters can differ for each object, but is detailed in the appropriate section on this page.
| Application type | Configuration Objects Used, in Order of Precedence |
|---|---|
| Client |
|
| Server |
|
- If the tls parameter is not set to 1 in both the client Application and Connection objects, then the client application will look to the Port object for the target server to determine if TLS should be turned on. Configuration Manager does not automatically add the tls=1 parameter to Connection Transport parameters when it is linked to a server's secure Port. This is the only case when a client application considers settings in the server's configuration objects.
Displaying the Annex Tab in Configuration Manager
By default, Configuration Manager does not show Annex tab in Object Properties windows. This tab can contain TLS parameters for Host and Application objects.
To show the Annex tab, select View > Options... from the main menu and ensure the Show Annex tab in object properties and Show Advanced Security Information options are selected.
Application Objects
Host Object
The properties window for a Host object includes most common TLS parameters on the General tab:
- Certificate
- Certificate Key
- Trusted CA
These fields allow copy/paste operations, so they can be set manually by copying and pasting the "Thumbprint" field values from certificates in Windows Certificate Services (WCS) into the related field in Configuration Manager.
To select a certificate, use the button next to Certificate field. This opens the Select certificate window, displaying a list of certificates installed in WCS under the Local Computer account for the local machine.
The Annex tab contains a security section that holds TLS settings for this object. Any change made to TLS-related fields on the General tab are mirrored between the Annex tab automatically. You can also specify additional TLS parameters here that aren't reflected on the General tab.
Server Application Object
For the server Application object, TLS-related fields are located on the Server Info tab of the properties window. Note the Certificate View controls group, where the server can be set to use Host TLS parameters (generally recommended for Genesys Framework) or application-specific ones.
If using application-specific TLS parameters, use the button next to the certificate information field to open a certificate selection window where you can choose from a list of certificates installed for the Local Computer account or manually enter certificate information:
Port Object
For port objects, TLS-related fields are located on the Server Info tab of the properties window. You can see here whether a port is secured (TLS-enabled) or not, and have the option to edit existing ports to update TLS parameters or to add new ports.
When adding or editing a port, TLS parameters are specified on the following tabs:
- Port Info — Turn on Secured listening mode for the port (the same as adding the tls=1 string to transport parameters).
- Certificate — Show certificate information, open a certificate selection window, or delete the current certificate information.
- Advanced — Manually edit the Transport Protocol Parameters field. TLS parameters not reflected on the Certificate tab can be added here.
Client Application Object
For client Application objects, TLS-related fields are located under the security sections of both the Options and Annex tabs. There is no certificate selection window provided, but TLS parameters can be configured manually in either section.
When processing a client Application object, Platform SDK looks at parameters from both sections. If any parameters are specified in both places, then the values from the Options tab take precedence.
Connection Object
The properties window for all Application objects includes a Connection tab where connections to servers can be added or edited. Each connection determines if TLS mode should be enabled based on port settings for the target server.
Similar to the Port properties window, the Certificate tab allows you to select from a list of certificates or manually edit certificate properties. You can also use the Advanced tab to edit TLS settings not included with the certificate. However, the Transport Protocol Parameters field behaves differently for this object — which may result in lost or incorrect settings in some cases. See the Notes and Issues section for details.
List of TLS Parameters
The following table lists all TLS parameters supported by Platform SDK, with their valid value ranges and purpose:
| Parameter Name | Acceptable Values | Purpose |
|---|---|---|
| tls | Boolean value.
Possible values are "1"/"0", "yes"/"no", "on"/"off", "true"/"false". Example:
|
Client:
1 - perform TLS handshake immediately after connecting to server. 0 – do not turn on TLS immediately but autodetect can still work. |
| provider | "PEM", "MSCAPI", "PKCS11"
Not case-sensitive. Example:
|
Explicit selection of security provider to be used. For example, MSCAPI and PKCS11 providers can contain all other parameters in their internal database. This parameter allow configuration of TLS through security provider tools. |
| certificate | PEM provider: path to a X.509 certificate file in PEM format. Path can use both forward and backward slash characters.
MSCAPI provider: thumbprint of a certificate – string with hexadecimal SHA-1 hash code of the certificate. Whitespace characters are allowed anywhere within the string. PKCS11 provider: this parameter is ignored. Examples:
|
Specifies location of X.509 certificate to be used by application.
MSCAPI provider keeps certificates in internal database and can identify them by hash code; so called thumbprint. In Java, PKCS#11 provider does not allow selection of the certificate; it must be configured using provider tools. Note: When using autodetect (upgrade) TLS connection, this option MUST be specified in application configuration, otherwise Configuration Server would return empty TLS parameters even if other options are set. |
| certificate-key | PEM provider: path to a PKCS#8 private key file without password protection in PEM format. Path can use both forward and backward slash characters.
Examples:
|
Specifies location of PKCS#8 private key to be used in pair with the certificate by application.
MSCAPI provider keeps private keys paired with certificates in internal database. In Java, PKCS#11 provider does not allow selection of the private key; it must be configured using provider tools. |
| trusted-ca | PEM provider: path to a X.509 certificate file in PEM format. Path can use both forward and backward slash characters.
MSCAPI provider: thumbprint of a certificate – string with hexadecimal SHA-1 hash code of the certificate. Whitespace characters are allowed anywhere within the string. PKCS11 provider: this parameter is ignored. Examples:
|
Specifies location of a X.509 certificate to be used by application to validate remote party certificates. The certificate is designated as Trusted Certification Authority certificate and application will only trust remote party certificates signed with the CA certificate.
MSCAPI provider keeps CA certificates in internal database and can identify them by hash code; so called thumbprint. In Java, PKCS#11 provider does not allow selection of the CA certificate; it must be configured using provider tools. |
| tls-mutual | Boolean value.
Possible values are "1"/"0", "yes"/"no", "on"/"off", "true"/"false". Example:
|
Has meaning only for server application. Client applications ignore this value. When turned on, server will require connecting clients to present their certificates and validate the certificates the same way as client applications do. |
| tls-crl | All providers: path to a Certificate Revocation List file in PEM format. Path can use both forward and backward slash characters.
Example:
|
Applications will use CRL during certificate validation process to check if the (seemingly valid) certificate was revoked by CA. This option is useful to stop usage of leaked certificates by unauthorized parties. |
| tls-target-name-check | "host" or none. Not case-sensitive.
Example:
|
When set to "host", enables matching of certificate’s Alternative Subject Name or Subject fields against expected host name. PSDK supports DNS names and IP addresses as expected host names. |
| cipher-list | String consisting of space-separated cipher suit names. Information on cipher names can be found online.
Example:
|
Used to calculate enabled cipher suites. Only ciphers present in both the cipher suites supported by security provider and the cipher-list parameter will be valid. |
| fips140-enabled | Boolean value.
Possible values are "1"/"0", "yes"/"no", "on"/"off", "true"/"false". Example:
|
PSDK Java: when set to true, effectively is the same as setting "provider=PKCS11" since only PKCS11 provider can support FIPS-140. If set to true while using other provider type, PSDK will throw exception. |
Notes and Issues
- Key/value pairs in Transport Protocol Parameters fields should be separated only with a single semicolon character. Adding space characters to improve readability can cause applications, including those based on Platform SDK, unable to parse these parameters correctly.
- Transport Protocol Parameters fields in Configuration Manager are limited to 256 characters in length. Be sure to keep your parameter list as short as possible. For example: certificate thumbprints for MSCAPI provider take 40 characters without spaces and 49 characters with them, and long paths to certificate files can easily eat up all available space.
- The Connection properties window behaves differently from the Port properties window, as described below. Be sure to double-check TLS settings for Connection objects.
- It does not save content of the Transport Protocol Parameters field unless a certificate was selected using UI controls on the Certificate tab.
- If certificate information is deleted from the Certificate tab, then all transport protocol parameters are also erased (including those entered manually).
- In some cases it does not save additional TLS parameters that were entered manually.
- Configuration Server reads its own TLS parameters from Application or from Host object only during startup. If you use an Application or Host object as a source of TLS parameters for Configuration Server, be sure to restart the server after any changes to the parameters.