6 Configuring Security Between Service Broker Components

This chapter describes the security model for Oracle Communications Service Broker and explains how to configure it.

About the Service Broker Security Model

See the Service Broker Security Guide for an overview of the Service Broker security model and philosophy. This chapter explains the details of setting up security for your Service Broker implementation.

Briefly, Service Broker The security model is based on Secure Socket Layer (SSL) and files system-level access privileges.

Securing Administration Clients, Processing Servers, and Signaling Servers

The Processing Servers and Signaling Servers expose Java MBeans. There is an MBean server in each of these servers. The MBean server is using a JMX SSL connection that requires both the server and an administration client to authenticate. Administration clients includes:

Standalone Administration Console
Web Administration Console server
Scripting Engine

The same security mechanisms that applies to these tools also applies to any administration client that uses JMX to configure, administer, and operate Service Broker.

Oracle recommends that you secure the JMX port with SSL encryption to enable client authentication. SSL encryption is enabled by default and is controlled by using entries in the Oracle_home/ocsb60/admin_console/properties/common.properties file. See Table A-9 in System Administrator's Reference for details on these entries.

SSL encryption requires a public key infrastructure (PKI) where each server has a public key and a private key. The key-pair is stored in an entry in a keystore. The private key is used by the server itself. The public key is used by the administration clients.

Each administration client also has a private key and a public key.

A public key is wrapped in a certificate, a public certificate. A certificate can be either self-signed or issued by a Certificate Authority (CA).

Each server has two stores:

Server keystore
Administration client truststore

Each administration client has two stores:

Administration client keystore
Server truststore

Figure 6-1 shows the relationship between the server stores and the administration stores.

Figure 6-1 Keystores, Truststores, and Exchange of Certificates

A keystore contains keystore entries. A truststore contains public certificates. Figure 6-2 shows the structure of the keystore and truststore.

Figure 6-2 Keystores and truststores

The keystores, truststores, and certificates are files. Certificates are exported from keystores, or provided by CAs, and imported to truststores.

Each keystore has a name and a password. Each keystore entry has an alias that identifies a key-pair and a password for the entry.

Each truststore has a password. A truststore can contain one or more certificate.

The certificate contains the public key and data about the certificate such as serial number, subject (the entity being identified by the certificate), and issuer of the certificate.

It is possible to use the same certificate for all administration clients, meaning that the server truststore contains only one administration client certificate. This approach is less secure than having individual certificates for each administration client.

Domain Configuration Security

File system-level security mechanisms are used for controlling access to the domain configuration. The user that starts any of the following administration clients must have read and write privileges to the domain configuration directory and all files in it:

Standalone Administration Console
Web Administration Console server
Scripting Engine

The Domain Web server must have read access to the domain configuration directory and all files in it.

Use operating-system specific commands to:

Configure users that have privilege to start the administration clients.
Make sure these users have read-write or read access to the domain configuration directory.

Oracle recommends that you only allow the owner or a trusted user group to have any privileges to the directory.

Securing Hosted Domains

When using a hosted domain configuration that is accessed using a Domain Web server, you can choose to access it using HTTP or HTTPS. The default is to use HTTPS with SSL client certificate authentication.

These settings are controlled by entries in the Oracle_home/ocsb60/admin_console/properties/hosting.properties file. See Table A-3 in System Administrator's Reference for details on these entries.

When HTTPS and client authentication are enabled, you must configure the trusted client certificates on the managed servers in your domain. You have these options for storing the client certificates:

Import them into default domain hosting keystore specified by the javax.net.ssl.keyStore parameter in common.properties (clientkeystore is the default). This is somewhat counter-intuitive. The Service Broker hosted domain reads trusted client authentication certificates from its client keystore.
Import them into a different keystore that you specify by uncommenting the org.eclipse.equinox.http.jetty.ssl.keystore=jettysslkeystore entry in the hosting.properties file. You can either use the default jettysslkeystore, or specify a different keystore.

Securing the Web Administration Console-Server Connection

An HTTPS connection is used between the Web Administration Console and the Web Administration Console server.

The first time the Web Administration Console is accessed, you are prompted to accept the certificate provided in a keystore in the Web Administration Console server. How you are prompted depends on:

The Web browser you use
If a self-signed certificate is used or if the certificate was provided by a certificate authority

The Web Administration Console user is required to authenticate with the Web Administration Console server, using the HTTP Basic Authentication mechanism.

The authentication requires the user to enter a user name and password in the browser. The user name and password is provided when the Web Administration Console server is started and the same credentials are used when the Web Administration Console is accessed.

Securing the Administration Port

Configuration updates and deployment updates are propagated to Processing Servers and Signaling Servers over the administration port defined for the server.

Oracle recommends that you secure the port with SSL encryption and to have client authentication enabled. Set the axia.ssl domain properties to true.

The property axia.admin.verify.hostname specifies if hostname verification is used for the SSL connection between the Administration Console and the servers. If set to true, each server must specify a host identity that matches the managed server listening address as specified in its key.

See "Enabling and Disabling SSL".

There are also requirements on how the SSL certificates are generated:

If the server name is specified as a host name in the domain configuration, one of the following applies as to how the common name (CN) in the certificate for the server is specified:
- The CN in the certificate for the server is identical to the server name defined in the domain configuration.
  
  In this case, a certificate must be created for each server.
- The CN in the certificate is set to *.domain.
  
  In this case, all servers can use the same certificate.
  
  This requires that the server names must be specified with their full names, including the domain, in the domain configuration. For example if the servers names are server1.us.oracle.com, server2.us.oracle.com, and so on, the CN is set to *.us.oracle.com.
If the server name is specified as an IP-address in the domain configuration, a certificate must be generated for each server.

For more information on server identity certificate validation in HTTP/TLS, see section 3.1. Server Identity in RFC 2818:

http://www.ietf.org/rfc/rfc2818.txt

Setting Service Broker Console Password Strength Validation

By default, all passwords used for the Web Administration Console and the Domain Web server must be at least six characters long, contain at least one lower case character, one upper case character, and one digit.

You have the option of changing these password strength requirements using property in the Oracle_home/ocsb60/admin_console/properties/common.properties file:

Whether the password is validated.
A minimum length for the password
Whether an upper-case character is required in the password.
Whether a lower-case character is requried in the password.
Whether an integer is requried in the password.

When you change these properties, you need to restart all Processing Servers, Signaling Servers, the Web Administration Console server, and the Domain Web server. SSL is enabled or disabled on deployment level, so all servers and administration clients must have the same setting.

See Table A-10 in "System Administrator's Reference" for a details on these properties.

Enabling and Disabling SSL

Note:

Oracle recommends that you do not disable SSL.

The Java system property axia.ssl specifies if SSL is enabled or disabled. By default, SSL is enabled.

If SSL is enabled, use HTTPS to connect to the Web Administration Console server or Domain Web server. If SSL is disabled, use HTTP.

The Java system property axia.ssl specifies if SSL is enabled or disabled for the administration port. Configuration updates and deployment operations are propagated to Processing Servers and Signaling Servers over this port.

The property axia.ssl.cipher_suites specifies the enabled platform SSL cipher suites. See Java Cryptography Architecture Sun Providers Documentation Cipher Suite documentation for Sun JSSE Provider for supported values, including how to use unlimited encryption options. The property is set to a comma-separated list of cipher suites.

For a complete list of the domain properties see "System Administrator's Reference".

Defining Keystores and Truststores

The default keystore and the truststore for each server and administration client are located in these directories:

Oracle_home/ocsb60/managed_server

Oracle_home/ocsb60/admin_console

The default keystore name is keystore. The default truststore is truststore. You can change the names and location of the stores. The Java system property:

javax.net.ssl.keyStore specifies the location and name of the keystore.
javax.net.ssl.trustStore specifies the location and name of the truststore.

See "System Properties" in "System Administrator's Reference" for details.

Setting up Public Key Infrastructures for Service Broker Components

This section provides an overview of the keytool program and then explains how to set up the Service Broker public Key infrastructure (PKI). Service Broker uses the PKI to store the credentials required to communicate between administration clients, Processing Servers, and Signaling Servers.

About Keytool and X.500 Distinguished Names

You set up the Service Broker PKI using keytool, a key and a certificate management tool. keytool is a part of the Oracle Java Development Kit (JDK) and is located in the Oracle_home/ocsb60/jdk/bin by default. See:

http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/keytool.html

A Distinguished Name (DN) identifies an entity. A DN is used when generating X.509 certificates. keytool uses a string notation for DN, immediately following the -dname parameter.

CN=common_name, OU=organization_unit, O=organization_name, L=locality, S=state, C=country_code

Where:

common_name is the common name of a person or a server host name. Example: Alice Smith or myserver.mydomain.com.

organization_unit is the department or division of an organization. Example: Operations.

organization_name is the organization or company. Example: Acme.

locality is the locality such as city. Example: Redwood City.

state is the state or province. Example: California.

country_code is the two-letter country code per ISO 3166-1. Example: US.

If a value contains a comma, it must be escaped with the “\" character. Example: Acme\, Inc.

Setting Up the PKI

This section explains how to use the keytool program to set up the PKI between administration clients, Processing Servers, and Signaling Servers using self-signed X.500 certificates.

To set up the PKI with self-signed certificates:

Generate the public and private keys for each Processing Server and Signaling Server. Repeat this for each server:
1. Generate the keys for the server:
  
  keytool -genkeypair “distinguished_name" -alias server_keystore_entry -keypass key_password -keystore server_keystore -storepass server_keystore_password
  
  Where:
  
  distinguished_name is a X.500 distinguished name for the issuer of the certificate. See "About Keytool and X.500 Distinguished Names".
  
  server_keystore_entry is a keystore entry for the certificate chain and the private key for the server.
  
  key_password is a password used to protect the private key.
  
  server_keystore is a name of the server keystore. Oracle suggests that you name your keystore so it can be identified with the server it will be used with. Example: ssu_server_1_keystore, ssu_server_2_keystore, and so on.
  
  server_keystore_password is the password that protects the server keystore.
2. Export the public key from the server keystore entry into a self-signed certificate:
  
  keytool -exportcert -alias server_keystore_entry -keystore server_keystore -storepass server_keystore_password -rfc -file server_certificate.cer
  
  Where:
  
  server_keystore_entry is the keystore entry for the certificate chain and the private key for the server. Same as the server_keystore_entry used when the keys were generated in the previous step.
  
  server_keystore is the name of the server keystore to export the certificate from. Same as the server_keystore used when the keys were generated in the previous step. Example: ssu_server_1_keystore, ssu_server_2_keystore, and so on.
  
  server_keystore_password is the password setup to protect the server keystore. Same as the server_keystore_password used when the keys were generated in the previous step.
  
  server_certificate is the name of the certificate. This certificate shall be imported to each administration client's truststore. Oracle suggests that you name your certificate so it can be identified with the server it originates from. Example: ssu_server_1.cer, ssu_server_2.cer, and so on.
Generate the public and private keys for each administration client. Repeat this for each administration client:
1. keytool -genkeypair “distinguished_name" -alias client_keystore_entry -keypass key_password -keystore client_keystore -storepass client_keystore_password
  
  Where:
  
  distinguished_name is a X.500 distinguished name for the issuer of the certificate.
  
  client_keystore_entry is a keystore entry for the certificate chain and the private key for the administration client.
  
  key_password is a password used to protect the private key.
  
  client_keystore is a name of the administration client keystore. Oracle suggests that you name your keystore so it can be identified with the administration client it will be used with. Example: client_1_keystore, client_2_keystore, and so on.
  
  client_keystore_password is the password that protects the administration client keystore.
2. Export the public key from the administration client keystore entry into a self-signed certificate:
  
  keytool -exportcert -alias client_keystore_entry -keystore client_keystore -storepass client_keystore_password -rfc -file client_certificate.cer
  
  Where:
  
  client_keystore_entry is the keystore entry for the certificate chain and the private key for the administration client. Same as the client_keystore_entry used when the keys were generated in the previous step.
  
  client_keystore is the name of the administration client keystore to export the certificate from.
  
  client_keystore_password is the password setup to protect the administration client keystore. Same as the client_keystore_password used when the keys were generated in the previous step.
  
  client_certificate is the name of the certificate. This certificate is imported to each server's truststore. Oracle suggests that you name your certificate so it can be identified with the administration client it originates from. Example: client_1.cer, client_2.cer, and so on.
Import the server certificate into the administration client truststore. Repeat this for each administration client:

keytool -importcert -file server_certificate -keystore client_truststore -storepass client_truststore_password -noprompt

Where:

server_certificate is the name of the server certificate. Example: ssu_server_1.cer, ssu_server_2.cer, and so on.

client_truststore is a name for the administration client truststore.

client_truststore_password is the password that protects the administration client truststore.
Import the administration client certificate into the server truststore. Repeat this for each server:

keytool -importcert -file client_certificate -keystore server_truststore -storepass server_truststore_password -noprompt

Where:

client_certificate is the name of the administration client certificate. Example: client_1.cer, client_2.cer, and so on.

server_truststore is a name for the server truststore.

server_truststore_password is the password that protects the server truststore.
Distribute the keystores and truststores to the servers and administration clients.

Note:
The keystores and trustores might be in different directories and might have different names than specified below. The following directories and filenames are according to default settings. See "Defining Keystores and Truststores".
1. Identify which keystore-truststore pair belongs to which server or administration client.
2. Copy the keystore-truststore pair to the correct server. Repeat this for each server:
  
  Copy or use FTP to put the keystore in:
  
  Oracle_home/ocsb60/managed_server/serverkeystore
  
  Copy or use FTP to put the truststore in:
  
  Oracle_home/ocsb60/managed_server/servertruststore
3. Copy the keystore-truststore pair to the correct administration client. Repeat this for each administration client:
  
  Copy or use FTP to put the keystore in:
  
  Oracle_Home/ocsb60/admin_console/clientkeystore
  
  Copy or use FTP to put the truststore in:
  
  Oracle_Home/ocsb60/admin_console/clienttruststore

Defining the Keystore for Administration Console SSL Connections

The public certificate used to secure the connection between the Web Administration Console and the Web Administration Console server is stored in a keystore accessed by the Web Administration Console server.

The certificate can be stored in either the same keystore as the Web Administration Console server uses when it authenticates with the Processing Servers and the Signaling Servers or it can use a separate keystore.

If the system property org.eclipse.equinox.http.jetty.ssl.keystore is not defined, the administration client keystore is used.

If the system property org.eclipse.equinox.http.jetty.ssl.keystore is defined, a separate keystore is used.

Using the Administration Client Keystore for Web Administration Console Security

To use the administration client keystore for Web Administration Console security:

Make sure the system property org.eclipse.equinox.http.jetty.ssl.keystore is not defined. Make sure there is a hash-sign (#) before the entry in the file:

Oracle_home/admin_console/properties/web.properties.

Example: #org.eclipse.equinox.http.jetty.ssl.keystore=jettysslkeystore
Open a command shell and change the directory to:

Oracle_home/admin_console
Use Keytool to generate a public and private key for the Web Administration Console server and store them in the administration client keystore:

keytool -genkeypair "distinguished_name" -alias keystore_entry -keypass key_password -keystore keystore -storepass keystore_password

Where:

distinguished_name is a X.500 distinguished name for the issuer of the certificate. See "About Keytool and X.500 Distinguished Names".

keystore_entry is a keystore entry for the certificate chain and the private key for the server.

key_password is a password used to protect the private key.

keystore is the name of the keystore defined for the Administration Console keystore. Example: console_keystore.

keystore_password is the password that protects the administration client keystore.
Use Keytool to export the public key from the keystore entry into a self-signed certificate:

keytool -exportcert -alias keystore_entry -keystore keystore -storepass keystore_password -rfc -file certificate.cer

Where:

keystore_entry is the keystore entry for the certificate chain and the private key for the server. Same as the keystore_entry used when the keys were generated in the previous step.

keystore is the name of the keystore to export the certificate from. Same as the keystore used when the keys were generated in the previous step. Example: console_keystore.

keystore_password is the password setup to protect the administration client keystore. Same as the keystore_password used when the keys were generated in the previous step.

certificate is the name of the certificate. This certificate shall be imported to the Web Administration Console server truststore. Oracle suggests that you name your certificate so it can be identified with the Web Administration Console server. Example: web_console_server.cer.
Use Keytool to import the certificate into the Web Administration Console server truststore:

keytool -importcert -file certificate -keystore truststore -storepass truststore_password -noprompt

Where:

certificate is the name of the server certificate. Example: web_console_server.cer.

truststore is the name for the Web Administration Console server truststore.

truststore_password is the password that protects the truststore.

Using a Separate Keystore for Web Administration Console Security

To use a separate keystore for Web Administration Console security

Make sure the system property org.eclipse.equinox.http.jetty.ssl.keystore is defined. The property is defined in the file:

Oracle_home/admin_console/properties/web.properties

The value of this property is the filename of and path to the keystore. When using relative paths, it is relative to the directory admin_console.

Example: org.eclipse.equinox.http.jetty.ssl.keystore=jettysslkeystore
Open a command shell and change the directory to:

Oracle_home/ocsb60/admin_console.
Use Keytool to Generate a public and private key for the Web Administration Console server and store them in the dedicated keystore:

keytool -genkeypair "distinguished_name" -alias keystore_entry -keypass key_password -keystore keystore -storepass keystore_password

Where:

distinguished_name is a X.500 distinguished name for the issuer of the certificate. See "About Keytool and X.500 Distinguished Names".

keystore_entry is a keystore entry for the certificate chain and the private key for the server.

key_password is a password used to protect the private key.

keystore is the name of the keystore to use for the connection between the Web Administration Console and the Web Administration Console server. Example: web_console_keystore.

keystore_password is the password that protects the server keystore.