Secure Communication Profiles

< Previous		Next >

Overview

Secure network connectivity is defined using secure communication profiles. These profiles define characteristics such as:

key stores.
trust stores.
the secure transport protocols to use, or not use.
the cipher suites to use or not use.

There are both client and server profiles. Client profiles define the security characteristics for outbound connections to external systems and nodes. Server profiles define the security characteristics for network listeners started by nodes and engines. This is shown in Figure 1, “Secure communication profiles”.

Secure communication profiles

Secure client communication profiles are configured using the SecureCommunicationClientProfile root configuration object described in Secure Communication Client Profile Configuration.

Secure server communication profiles are configured using the SecureCommunicationServerProfile root configuration object described in Secure Communication ServerProfile Configuration.

A secure server communication profile is used to control the security characteristics of these listeners:

data transport listener
administration (epadmin) listener
web server listener

See Communication for details on configuring a SecureCommunicationServerProfile for these listeners. See [Accessing a node section to be ported] for details on specifying credentials when using epadmin.

Key and Trust Stores

Key and trust stores are supported both for node security and epadmin client security.

Trust stores are used to validate a node's or client's certificates.
Key stores contain certificates and private keys when using client authentication.

These key and trust store encoding types are supported on nodes and can be specified in secure communication profiles:

all Java key and trust store types, for example Java Key Store (JKS) and Java Cryptography Extension Key Store (JCEKS). Actual supported types are dependent on the installed JRE being used by a node.
Public-Key Cryptography Standards #12 (PKCS12)

These key and trust store encoding types are supported by the epadmin client:

Public-Key Cryptography Standards #12 (PKCS12)
Privacy Enhanced Mail (PEM) format

Secure Communication Client Profile Configuration

The SecureCommunicationClientProfile root configuration object defines a secure communication profile for client connectivity. Figure 2, “SecureCommunicationClientProfile relationships” shows the relationships to other configuration objects.

SecureCommunicationClientProfile relationships

A detailed description of the configuration object properties is in SecureCommunicationClientProfile object properties and a snippet for these properties is in Example 1, “SecureCommunicationClientProfile object snippet”.

SecureCommunicationClientProfile object properties

Name	Type	Description
`excludedCipherSuitePatterns`	String [ ]	A list of Java regular expression patterns for excluded cipher suites. This value is exclusive of the `includedCipherSuites` property. Optional. Default is `^.*_(MD5\|(?<!TLS_DHE_RSA_WITH_AES_\\d\\d\\d_CBC_)SHA\|SHA1)$` if no `includedCipherSuites` are specified.
`includedCipherSuites`	String [ ]	A list of allowed cipher suites. This value is exclusive of the `excludedCipherSuitePatterns` property. Optional. Default is the JRE's full set of supported cipher suites.
`includedProtocols`	String [ ]	A list of allowed protocols. Optional. Default is `TLSv1.1` and `TLSv1.2`. An empty array uses the JRE's full set of supported protocols.
`keyPassword`	String	The password to access the key within the keystore. Opaque text credentials are generated using the epadmin secret target. See epadmin-secret(1). Optional. Default is `keyStorePassword`.
`keyStorePassword`	String	Key store password, used to access the key store contents. Opaque text credentials are generated using the epadmin secret target. See epadmin-secret(1). Required if `keyStore` specified.
`keyStore`	String	Absolute path to a key store file that contains the client's certificate as well as optional trust store information, depending on key store format. If the key store contains multiple private key entries (aliases), the first is used. This file must be valid on the machine where the client is running. If provided, clients can perform mutual authentication with a server. Optional. No default.
`keyStoreType`	String	Key store type (see Key and Trust Stores). Optional. Default is `JKS`.
`name`	String	The name of the profile. This name must be unique across all secure communication profiles — both client and server. Required.
`requireClientAuthentication`	Boolean	Enable (`true`) or disable (`false`) required client authentication. If enabled a `keyStore` must be configured to sign the secure communication protocol handshake. Optional. Default is `false`.
`trustStore`	String	An absolute file path to the trust store used to verify client trust. This file must be valid on the machine where the client is running. Required.
`trustStorePassword`	String	The password to access the trust store. Opaque text credentials are generated using the `epadmin secret` target. See epadmin-secret(1). Required if `trustStore` specified.
`trustStoreType`	Enumeration. Valid values are `JCEKS`, `JKS`, or `PKCS12.`	Trust store type (see Key and Trust Stores). Optional. Default is `JKS`.

Example 1. SecureCommunicationClientProfile object snippet

name = "my-secure-client-settings"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration =
{
    SecureCommunicationClientProfile =
    {
        name = "my-secure-client-profile"
        keyStore = "/absolute/path/myKeyStore.jks"
        keyStorePassword = "secret"
        keyPassword = "anothersecret"
        keyStoreType = "jceks"
        trustStore = "/absolute/path/myTrustStore.jks"
        trustStorePassword = "athirdsecret"
        trustStoreType = "JCEKS"
        requireClientAuthentication = true
        excludedCipherSuitePatterns = [ "^.*_(MD5|SHA|SHA1)$" ]
        includedProtocols = [ ] // use JRE's supported protocols
    }
}

Secure Communication Server Profile Configuration

The SecureCommunicationServerProfile root configuration object defines a secure communication profile for listeners. Figure 3, “SecureCommunicationServerProfile relationships” shows the relationships to other configuration objects.

SecureCommunicationServerProfile relationships

A detailed description of the configuration object properties is in SecureCommunicationServerProfile object properties and a snippet for these properties is in Example 2, “SecureCommunicationServerProfile object snippet”.

SecureCommunicationServerProfile object properties

Name	Type	Description
`excludedCipherSuitePatterns`	String [ ]	A list of Java regular expression patterns for excluded cipher suites. This value is exclusive of the `includedCipherSuites` property. Optional. Default is `^.*_(MD5\|(?<!TLS_DHE_RSA_WITH_AES_\\d\\d\\d_CBC_)SHA\|SHA1)$` if no `includedCipherSuites` are specified.
`includedCipherSuites`	String [ ]	A list of allowed cipher suites. This value is exclusive of the `excludedCipherSuitePatterns` property. Optional. Default is the JRE's full set of supported cipher suites.
`includedProtocols`	String [ ]	A list of allowed protocols. Optional. Default is `TLSv1.1` and `TLSv1.2`. An empty array uses the JRE's full set of supported protocols.
`keyPassword`	String	The password to access the key within the keystore. Opaque text credentials are generated using the `epadmin secret` target. See epadmin-secret(1). Optional. Default is `keyStorePassword`.
`keyStorePassword`	String	Key store password, used to access the key store contents. Opaque text credentials are generated using the `epadmin secret` target. See epadmin-secret(1). Required.
`keyStore`	String	Absolute path to a key store file that contains the server's certificate as well as optional trust store information, depending on key store format. If the key store contains multiple private key entries (aliases), the first is used. This file must be valid on the machine where the node is running. Required.
`keyStoreType`	String	Key store type (see Key and Trust Stores). Optional. Default is `JKS`.
`name`	String	The name of the profile. This name must be unique across all secure communication profiles — both client and server. Required.
`requireClientAuthentication`	Boolean	Enable (`true`) or disable (`false`) required client authentication. If enabled a `trustStore` must be configured to verify client trust. Optional. Default is `false`.
`subjectNameElementToUserNameMappings`	Associative array of certificate based principal names to authorization user names.	A map whose keys are certificate-based principal names and whose values are authorization user names. Used in cases where an incoming client certificate is used for authentication, but none of the elements of its subject name are suitable for mapping to roles during authorization. Optional. No default, subject name element extracted with the `userNameObjectIdentifierSearchPath` must yield a valid user name for authorization purposes.
`trustStore`	String	An absolute file path to the trust store used to verify client trust. This file must be valid on the machine where the node is running. If provided, servers can perform mutual authentication with clients. Optional.
`trustStorePassword`	String	The password to access the trust store. Opaque text credentials are generated using the `epadmin secret` target. See epadmin-secret(1). Required if `trustStore` specified.
`trustStoreType`	Enumeration. Valid values are `JCEKS`, `JKS`, or `PKCS12.`	Trust store type (see Key and Trust Stores). Optional. Default is `JKS`.
`userNameObjectIdentifierSearchPath`	String [ ]	An array of attribute keywords, or X.509 object identifiers (OIDs), indicating the order in which the client's X.509 certificate subject Distinguished Name attributes are searched to find a user name for authorization purposes. This key is only relevant if `requireClientAuthentication` is enabled and a trust store is present. Supported attribute keywords are `userID`, `CN`, `emailAddress`, and `DN`. Optional. Default is the search order `emailAddress`, `CN`, `DN`.

Example 2. SecureCommunicationServerProfile object snippet

name = "my-secure-server-settings"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration =
{
    SecureCommunicationServerProfile =
    {
        name = "my-secure-server-profile"
        excludedCipherSuitePatterns = [ "^.*_(MD5|SHA|SHA1)$" ]
        includedProtocols = [ ] // use JRE's supported protocols
        keyPassword = "anothersecret"
        keyStorePassword = "secret"
        keyStore = "/absolute/path/myKeyStore.jks"
        keyStoreType = "jceks"
        requireClientAuthentication = true
        subjectNameElementToUserNameMappings =
        {   
            "subjectNameElementFoo" = "userNameFoo"
            "subjectNameElementBar" = "userNameBar"
        }
        trustStore = "/absolute/path/myTrustStore.jks"
        trustStorePassword = "athirdsecret"
        trustStoreType = "JCEKS"
        userNameObjectIdentifierSearchPath = [ "userID", "CN", "1.2.3.4", "DN" ]
    }
}