Chapter 7 Configuring the N1 Service Provisioning System 4.1 for SSL

This chapter contains instructions for configuring the N1 Service Provisioning System 4.1 to communicate using Secure Socket Layer (SSL). This chapter discusses the following topics:

• Overview of SSL Support in the N1 Service Provisioning System 4.1

• Task Map for Configuring SSL

• Enabling SSL in Tomcat

• Creating Key Stores

• Configuring SSL

• Sample Configuration Scenarios

• SSL Cipher Suites

Overview of SSL Support in the N1 Service Provisioning System 4.1

SSL is a protocol for securing communication over IP networks. SSL uses TCP/IP sockets technology to exchange messages between a client and a server, while protecting the message with a public and private key encryption system developed by RSA. Support for SSL is included in most web server products, as well as in the Netscape Navigator and Microsoft web browsers.

N1 Service Provisioning System 4.1 applications can be configured to use SSL for their network communications, preventing messages from being read or tampered. Optionally, applications can be configured to use SSL to authenticate before communicating, further increasing network security.

Cipher Suites: Encryption and Authentication Overview

The SSL protocol supports a variety of different cryptographic algorithms, or ciphers, for use in operations such as authenticating the server and client to each other, transmitting certificates, and establishing session keys. The cipher suite that SSL uses to connect determines whether any authentication will take place.

Exercise caution when selecting cipher suites. Each application must enable only those cipher suites that provide the minimum security needed by the node. SSL uses the most secure cipher suites supported by both the client and server. If low security cipher suites are enabled, a third party client can force the server to use the less secure cipher suites by publishing support for only the least secure cipher suite during cipher suite negotiation.

SSL can be operated in the following modes.

• Encryption only, no authentication – Connections are encrypted. However, SSL does not authenticate the applications that are connecting.

• Server Authentication – Clients authenticate the server to which they are connecting.

• Server and Client Authentication – Both the client and server authenticate each other.

During the installation, when you select to use SSL to secure communications between applications, you are prompted to select the cipher suite to use. The cipher suite value is stored in net.ssl.cipher.suites in the config.properties file. The cipher suite value is set to the following value based on the selection you make.

• If you select encryption, no authentication, the cipher suite is set to SSL_DH_anon_WITH_3DES_EDE_CBC_SHA.

• If you select authentication with encryption, the cipher suite is set to SSL_RSA_WITH_3DES_EDE_CBC_SHA.

For lists of SSL cipher suites that do and do not require server authentication, see SSL Cipher Suites. You can configure client authentication only for cipher suites requiring server authentication.

Authentication Key Stores

The N1 Service Provisioning System 4.1 supports self-signed certificates. Two types of key stores exist:

• Private Key Store – The private key store contains the public-private key pairs that the application uses to authenticate itself when connecting to other applications.

• Trust Key Store – The trust key store contains the public key, in self-signed certificates, of other applications that the key store trusts and allows them to connect to the application.

When enabling SSL for client-server authentication, each enabled application needs to be configured with two key stores that SSL will use to authenticate itself to other applications and to authenticate other applications.

When enabling SSL for server-only authentication, the application acting as the SSL server requires a private key store and the application acting as the SSL client requires a public, or trusted, key store. The public key stores are in the proprietary JKS format provided by the Java Secure Sockets Extension (JSSE) v1.0.3.

You must specify a password for both of the key stores. The password for both of the key stores must be the same.

For example, application A, an SSL client, and application B, an SSL server, want to connect with each other using SSL. Both are configured to use a cipher suite that requires server authentication. Application B must have a public-private key pair in its private key store, and application A must have application B's public key in its trust key store. When application A attempts to connect to application B, application B sends its public key down to application A. Application A is able to verify the public key by finding it in its trust key store.

If application B is configured to require client authentication, application A must have a public-private key pair in its private key store, and application B must have application A's public key in its trust key store. After application A has authenticated application B, application B is able to verify application A's public key, as it finds the public key in its trust key store.

Using Passwords With SSL

If you supply a password for trust key store operations, the password is only used to verify the integrity of the key store. The password does not prevent access to the contents of the trust key store, but it does protect updates to the key store. Users are not able to change the contents of the key store without supplying the password.

If you supply a password for private key store operations, the password is used to verify the integrity of the key store, protect against modifications of the key store contents, and to encrypt and protect access to the private key.

The crkeys script validates that you specified the same password for both the key stores. When creating a trust store for the first time by importing certificates, the crkeys script ensures that the trust store has the same password as the private store, if one exists. Similarly, when creating a private store for the first time, the crkeys script ensures that the private store has the same password as the trust store, if one exists.

To use the crkeys script to prompt for and verify the key store password when starting applications, use the -vpass option. The crkeys script prompts the user for the key store password if any of the key stores exist, and verifies the password against the key store. If the verification succeeds, it prints the password on the standard output so that it can be fed into the application.

Limitations of SSL on the N1 Service Provisioning System 4.1

The SSL implementation on the N1 Service Provisioning System 4.1 has the following limitations:

• Only self-signed certificates are supported. The trust key store contains self-signed certificates only. You cannot use CA-signed certificates.

• Both the trust and the private key stores must be configured with the same password. Also, within the private key store, the key password for each key in the store must be the same as the store password. The crkeys script used to create keys enforces this limitation.

• Passwords echo to the terminal. To overcome this limitation on POSIX platforms, you may have the startup script disable terminal echo and then prompt the user for a password.

• Although enabling client authentication for CLI Client applications is possible, this setup is not supported due to security limitations. The CLI Client applications do not prompt the user for key store passwords. If the key stores have been created, the key stores must be provided in the CLI Client properties file.

  The N1 Service Provisioning System 4.1 uses single trust key store for both incoming and outgoing connections. Hence, if a Master Server connects to a Remote Agent and trusts its public key and if that Remote Agent becomes compromised, that Remote Agent's keys could be used to authenticate the CLI Client to the Master Server, if the CLI Client were to use client authentication.

  Client authentication is not supported for CLI Client, therefore, the CLI Client only has a trust store. The benefit of supplying a password is that you can verify that the trust store has not been tampered with. You can specify the password in the properties file, but prompting the user for the password each time the CLI Client is run is more secure.

• For SSH connections, the remote application, the Local Distributor or Remote Agent, is automatically started. The system does not prompt you for the key store passwords to start these applications. If the applications are initialized with key stores, the passwords to their key stores must be specified in their properties file.

• When you configure the CLI Client to connect to the Master Server using SSH, the CLI Client connects to the Master Server using an SshProxy application that connects to the Master Server through sockets. The SshProxy can connect to the Master Server through SSL, but this configuration is not supported.

Task Map for Configuring SSL

The following table describes the tasks necessary to configure the N1 Service Provisioning System 4.1 to use SSL.

Enabling SSL in Tomcat

By default, the N1 Service Provisioning System 4.1 Web Interface does not use SSL. Requests are performed over HTTP rather than HTTPS. You can enable HTTPS with an SSL Certificate. SSL Certificates are issued by Certifying Authorities (CA). Certificates are usually specific to individual machines.

An SSL Certificate is enclosed within the following delimiters:

-----BEGIN CERTIFICATE-----  

and

-----END CERTIFICATE----- 

How to Generate SSL Certificates for Tomcat

Steps

1. Change to the directory in which you installed the JRE.

   % cd JAVA-HOME/bin

   JAVA-HOME is the directory where you installed the JRE. If you installed the JRE with the N1 Service Provisioning System 4.1, the JRE is installed in the N1SPS4.1-home/common/JRE/bin directory.

2. Generate the certificate.

   % keytool -genkey -alias tomcat -keyalg RSA -keystore /keystore-location -storepass password

   Set /keystore-location to the location where you want to store the generated keys. /etc/keystore is commonly used.

   Set password to whatever password you choose.

3. Follow the prompts to complete.

How to Enable SSL in Tomcat

Steps

1. Import the SSL Certificate

   % keytool -import -alias tomcat -keystore keystore-location/ -trustcacerts

   keystore-location is the path to and the name of the file in which you saved your certificate text. The output of this command shows the name of the file in which the imported certificate is stored. This file is usually saved in the home directory of the user who ran the command.

2. In the server.xml file, uncomment the following lines. XML comments begin with <!-- and end with -->.

   <Connector className="org.apache.catalina.connector.http.HttpConnector" port="8443" minProcessors="5" maxProcessors="75" enableLookups="true" acceptCount="10" debug="0" scheme="https" secure="true"> <Factory className="org.apache.catalina.net.SSLServerSocketFactory" clientAuth="false" protocol="TLS"/> </Connector>

3. Edit the Factory element as follows.

   <Factory className="org.apache.catalina.net.SSLServerSocketFactory" clientAuth="false" protocol="TLS" keystoreFile=path-to-tomcat-keystore-file/ keystorePass="password"/>

   path-tomcat-keystore-file is the path to the Tomcat keystore file and password is the password that you used to create the original keypass.

Requiring Users to Connect to the Web Interface Using SSL

After you have configured the N1 Service Provisioning System 4.1 to use SSL, you can configure it further so that users must use SSL to connect to the server.

How to Require Users to Connect Using SSL

Step

1. Replace the current web.xml file with the Tomcat /webapp/WEB-INF/web.xml.secure file.

   % cd /N1SPS4.1-home/webapp/WEB-INF % cp web.xml.secure web.xml

   N1SPS4.1-home is the home directory of the application.

How to Revert to the Original Configuration

Step

1. To return to the original configuration, replace the web.xml file with the /webapp/WEB-INF/web.xml.default file.

   % cd /N1SPS4.1-home/webapp/WEB-INF % cp web.xml.default web.xml

   N1SPS4.1-home is the home directory of the application.

Creating Key Stores

The N1 Service Provisioning System 4.1 uses the keytool utility provided with the JRE. The keytool utility is wrapped in a shell script, crkeys, to enable you to create key stores. The script ensures that the correct parameters are supplied to the `keytool' utility.

When you create a key store, the X.509 Distinguished Name in the self-signed certificate is set to the following.

CN=application_name OU=Engineering O=Sun Microsystems Inc L=Menlo Park ST=CA C=US

How to Create Key Stores

Step

1. Generate the keys.

   % crkeys -options

   Use the following options to create key stores based on the type of SSL connectivity you want to use.

   -alias application_hostname

   Specifies an alias for the certificate or the key pair. Use the hostname of the application as the alias. The alias names must be unique within a key store.

   -cpass

   Changes the password of the key store and all the keys within the key store.

   -delete

   Specifies that the key pair or certificate for the specified entity should be deleted from key store.

   -export

   Exports a self-signed certificate of the specified entity to the specified file.

   -file cert_file

   Specifies the name of the file that the certificate is to be imported from or exported to.

   -generate

   Generates a new key pair for the specified alias.

   -help

   Lists all the options.

   -import

   Imports a self-signed certificate of an entity that is allowed to connect to this node. When importing the certificate the hostname of the node that this certificate represents should be used as the alias.

   -keyalg keyalg

   The key generation algorithm. Defaults to `RSA'. Can be either `RSA' or `DSA'.

   -keysize keysize

   The key size. Defaults to 1024, Can be any multiple of 64 in the range 512-1024 for DSA keys and range 512-2048 for RSA keys.

   -list

   Lists all the entities contained in the key store.

   -new newpassword

   Specifies the new password for the key store and all the keys in the key store.

   -password password

   Specifies the password for the key store. If a password is not specified, the user is prompted for one.

   -private

   Specifies the private key store as the target of the operation.

   -validity days_valid

   Number of days the self-signed certificate is valid.

   -trust

   Specifies the trust key store as the target of the operation.

Example 7–1 crkeys Command Examples

The following examples show how to use the crkeys command.

To generate a public-private key pair:

crkeys -private –generate|-delete
    –alias application_hostname [-keyalg keyalg] 
[-keysize keysize] [-validity days_valid] 
[–password password]

To export the self signed public key for a key pair to a file:

crkeys -private –export –file cert_file
 –alias application_hostname [–password password]

To import an exported, as shown in the previous example, self signed public key into the trust store:

crkeys –trust –import –file cert_file
 –alias application_hostname [-password password] 

To delete a key or key pair:

crkeys {-private|–trust} -delete
 –alias application_hostname [-password password] 

To list all of the public keys:

crkeys {-private|–trust} –list [-password password]

To change the SSL key store, both the trust and the private store, password:

crkeys –cpass -password oldpassword 
-new newpassword

To print instructions for using the crkeys command:

crkeys -help

Configuring SSL

During the installation, each application is configured to do the following:

• Support cipher suites that require server authentication.

• Do not require client authentication.

• Find the private key store in the N1SPS4.1-home/app/data/private.store file.

• Find the trust key store in the N1SPS4.1-home/app/data/trust.store file.

• Supply empty passwords for each key store.

You can change the SSL configuration of each application to perform the following security checks:

• Selectively enable cipher suites on each application.

  You can explicitly specify which cipher suites to enable. If unspecified, the reference implementation uses the cipher suites that are enabled by default. The default cipher suites enabled by the reference implementation require server authentication. For the list of supported cipher suites, see SSL Cipher Suites.

• Specify that the application authenticate the SSL clients connecting to it.

• Specify the location and password of the private key and trust stores.

To enable authentication, you must initialize the key stores after installation of the application.

How to Configure SSL

Step

1. Manually edit the config.properties file to change the SSL configuration.

   The following table lists the settings in the config.properties file that are related to SSL configurations. Change the parameters based on the type of SSL connectivity you want to use.

   Parameter	Default Value	Description
   net.ssl.cipher.suites	SSL_RSA_WITH_3DES_EDE_CBC_SHA	A comma separated list of SSL cipher suites to enable. For a list of supported SSL Cipher suite, see SSL Cipher Suites.
   net.ssl.client.auth	false	Specifies whether the SSL server should authenticate clients connecting to it.
   net.ssl.trust.store.path	N1SPS4.1–home/data/trust.store	The path to the trust key store. The key store that contains the public keys of the nodes that are allowed to connect to this node.
   net.ssl.private.store.path	N1SPS4.1–home/data/private.store	The path to the private key store. The key store that contains the public-private key pairs that this node uses to authenticate itself to other nodes.
   net.ssl.key.store.pass		The key store password.

Sample Configuration Scenarios

How to Configure SSL Without Authentication Between the Master Server, Local Director, and Remote Agent

Steps

1. Install the Master Server, Local Distributor and Remote Agent and select SSL when the installation program prompts you to select a connection type. When prompted to select a cipher suite, select encryption with no authentication.

2. Add the following property to the config.properties file for each application.

   net.ssl.cipher.suites=SSL_DH_anon_WITH_3DES_EDE_CBC_SHA

   More than one cipher suite or a different cipher suite can be enabled. To enable multiple cipher suites, set the parameter to a comma separated list of cipher suites.

3. From the Web Interface, create a new host.

4. On the host that you just created, add a Local Distributor with the connection type SSL.

5. Test the connection to the Local Distributor.

6. Create a new host.

7. On the host that you just created, add a Remote Agent with the connection type SSL.

8. Test the connection to the Remote Agent.

How to Configure SSL Server Authentication

By default, cipher suites requiring server authentication are enabled, so no change is required in the config.properties file to enable cipher suites.

Steps

1. Generate a key pair for the Local Distributor and store it in the private store for the Local Distributor.

   % ld/bin/crkeys –private –generate –alias ldhostname.cr.com –validity 365

2. Export the self-signed certificate from the private store on the Local Distributor into a file.

   % ld/bin/crkeys –private –export –file ld.cert –alias ldhostname.cr.com

3. Copy the self-signed certificate for Local Distributor to the Master Server.

4. Import the self-signed certificate into the Master Server trust store.

   % server/bin/crkeys –trust –import –file ld.cert –alias ldhostname.cr.com

5. Create a new host.

6. On the new host, add a Local Distributor with the connection type SSL.

7. For the Local Distributor, use the CLI net.gencfg command to manually generate the transport.config file.

8. Copy the transport.config file to the Local Distributor.

9. If already running, stop and the Master Server and the Local Distributor.

10. Start the Master Server and the Local Distributor.

11. Provide the key store password for the Master Server and Local Distributor.

12. Test the connection to the Local Distributor.

13. Generate a key pair for the Remote Agent and store it in the private store for the Remote Agent.

    % agent/bin/crkeys –private –generate –alias rahostname.cr.com –validity 365

14. Export the self-signed certificate from the private store on the Remote Agent into a file.

    % agent/bin/crkeys –private –export –file ra.cert –alias rahostname.cr.com

15. Copy the self-signed certificate for the Remote Agent to the Local Distributor.

16. Import the self-signed certificate into the Local Distributor trust store.

    % ld/bin/crkeys –trust –import –file ra.cert –alias rahostname.cr.com

17. Create a new host.

18. On the new host, add a Remote Agent with the connection type SSL.

19. For the Remote Agent, use the CLI net.gencfg command to manually generate the transport.config file.

20. Copy the transport.config file to the Remote Agent.

21. If already running, stop the Local Distributor and Remote Agent.

22. Start the Local Distributor and the Remote Agent.

23. Provide the key store password for the Local Distributor and Remote Agent.

24. Test the connection to the Remote Agent.

How to Configure SSL Server and Client Authentication

Steps

1. Install the Master Server, Local Distributor and Remote Agent and select SSL when the installation program prompts you to select a connection type. When prompted to select a cipher suite, select encryption with authentication.

2. Generate a key pair for the Local Distributor and store it in the private store for the Local Distributor.

   % ld/bin/crkeys –private –generate –alias ldhostname.cr.com –validity 365

3. Generate a key pair for the Master Server and store it in the private store for the Master Server.

   % server/bin/crkeys –private –generate –alias mshostname.cr.com –validity 365

4. Export the self-signed certificate from the private store for the Local Distributor into a file.

   % ld/bin/crkeys –private –export –file ld.cert –alias ldhostname.cr.com

5. Copy the self-signed certificate for the Local Distributor to the Master Server.

6. Import the self-signed certificate into the Master Server trust store.

   % server/bin/crkeys –trust –import –file ld.cert –alias ldhostname.cr.com

7. Export the self-signed certificate from the private store for the Master Server into a file.

   % server/bin/crkeys –private –export –file ms.cert –alias mshostname.cr.com

8. Copy the self-signed certificate for the Master Server to the Local Distributor.

9. Import the self-signed certificate into the Local Distributor trust store.

   % ld/bin/crkeys –trust –import –file ms.cert –alias mshostname.cr.com

10. Create a new host.

11. On the new host, add a Local Distributor with the connection type SSL.

12. If already running, stop the Master Server and the Local Distributor.

13. Start the Master Server and the Local Distributor.

14. Provide the key store password for the Master Server and Local Distributor.

15. Test the connection to the Local Distributor.

16. Generate a key pair for the Remote Agent and store it in the private store for the Remote Agent.

    % agent/bin/crkeys –private –generate –alias rahostname.cr.com –validity 365

17. Export the self-signed certificate from private store for the Remote Agent into a file.

    % agent/bin/crkeys –private –export –file ra.cert –alias rahostname.cr.com

18. Copy the self-signed certificate for the Remote Agent to the Local Distributor.

19. Import the self-signed certificate into the Local Distributor trust store.

    % ld/bin/crkeys –trust –import –file ra.cert –alias rahostname.cr.com

20. Copy the self-signed certificate for the Local Distributor, exported in Step 4, to the Remote Agent machine.

21. Import the self-signed certificate into the Remote Agent trust store.

    % agent/bin/crkeys –trust –import –file ld.cert –alias ldhostname.cr.com

22. Create a new host.

23. On the new host, add a Remote Agent with the connection type SSL.

24. Copy the transport.config file to the Remote Agent.

25. If already running, stop the Local Distributor and Remote Agent.

26. Start the Local Distributor and the Remote Agent.

27. Provide the key store password for the Local Distributor and Remote Agent.

28. Test the connection to the Remote Agent.

How to Configure SSL Authentication Between a CLI Client and Master Server

Steps

1. Install the Master Server and the CLI Client and select SSL when the installation program prompts you to select a connection type. When prompted to select a cipher suite, select encryption with authentication.

2. Generate a key pair for the Master Server and store it in the private store for the Master Server.

   % server/bin/crkeys –private –generate –alias mshostname.cr.com –validity 365

3. Generate a key pair for the CLI Client and store it in the private store for the CLI Client.

   % cli/bin/crkeys -private -generate -alias clihostname.cr.com.cr.com -validity 365

4. Export the self-signed certificate from the private store for Master Server private store into a file.

   % server/bin/crkeys –private –export –file ms.cert –alias mshostname.cr.com

5. Copy the Master Server self-signed certificate to the CLI Client.

6. Import the self-signed certificate into CLI Client trust store.

   % cli/bin/crkeys –trust –import –file ms.cert –alias mshostname.cr.com

7. Export the self-signed certificate from the private store for CLI Client into a file.

   % cli/bin/crkeys -private -export -file cli.cert -alias clihostname.cr.com

8. Copy the CLI Client self-signed certificate to the Master Server.

9. Import the self-signed certificate into the Master Server trust store.

   % server/bin/crkeys -trust -import -file cli.cert -alias clihostname.cr.com

10. If the Master Server is running, stop the Master Server.

11. Start the Master Server.

12. Provide the key store password for the Master Server.

13. On the CLI Client, edit the config.properties file to include the following line.

    net.ssl.key.store.pass=trust-store-password

14. Run a CLI Client command to verify the connection.

SSL Cipher Suites

The following lists describe the supported SSL cipher suites.

The following suites require server authentication.

SSL_DHE_DSS_WITH_DES_CBC_SHA 
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA 
SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA 
SSL_RSA_WITH_RC4_128_MD5 
SSL_RSA_WITH_RC4_128_SHA 
SSL_RSA_WITH_DES_CBC_SHA 
SSL_RSA_WITH_3DES_EDE_CBC_SHA 
SSL_RSA_EXPORT_WITH_RC4_40_MD5 

The following suites do not require server authentication.

SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA 
SSL_DH_anon_EXPORT_WITH_RC4_40_MD5 
SSL_DH_anon_WITH_3DES_EDE_CBC_SHA 
SSL_DH_anon_WITH_DES_CBC_SHA 
SSL_DH_anon_WITH_RC4_128_MD5 

The following suites require server authentication with no encryption.

SSL_RSA_WITH_NULL_MD5 
SSL_RSA_WITH_NULL_SHA