Sun N1 Service Provisioning System 5.1 Installation Guide

Chapter 8 Configuring the N1 Service Provisioning System 5.1 for SSL

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

Overview of SSL Support in the N1 Service Provisioning System 5.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 5.1 applications can be configured to use SSL for their network communications, preventing messages from being read or tampered with. 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 takes 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:

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 as the value of 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:

When you use SSL with a Local Distributor on an AIX server, the SSL cipher suite is set to encryption with authentication. Encryption with no authentication is not available for Local Distributors that are running on AIX servers.

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 that require server authentication.


Note –

The N1 Service Provisioning System 5.1 applications allow you to configure SSL connections with encryption, no authentication or encryption with authentication. Encryption with authentication uses client and server authentication. Although the configurations described above are possible, encryption, with authentication is the most secure.


Authentication Keystores

The N1 Service Provisioning System 5.1 supports self-signed certificates and certificates signed by a Certifying Authority. Two types of keystores exist:

When enabling SSL for client-server authentication, each enabled application needs to be configured with two keystores 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 keystore and the application acting as the SSL client requires a public, or trusted, keystore. The public keystores 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 keystores. The password for both of the keystores 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 keystore, and application A must have application B's public key in its trust keystore. 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 keystore.

If application B is configured to require client authentication, application A must have a public-private key pair in its private keystore. Also, application B must have application A's public key in its trust keystore. 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 keystore.

When you generate a keystore using the crkeys command, you use the -mode upstream|downstream option to specify the location of the machine that is being authenticated in relationship to the machine that is performing the authentication. When attempting an SSL connection, the server that is validating the connection verifies that the certificate it received contains a mode that matches the relative location of the server that transmitted the certificate. For example, a Local Distributor receives an SSL connection request from a Master Server. The Local Distributor verifies that the Master Server certificate does not have a downstream annotation.


Note –

The server does not verify that a certificate contains an upstream annotation. The server only verifies that the certificate does not have a downstream annotation. Consequently, any servers that were originally configured to use SSL without an upstream annotation will continue to connect using SSL.


A CLI client cannot validate a connection with a server that transmits a certificate with an upstream annotation because no server can be upstream from a CLI client. A Remote Agent cannot validate a connection with a server that transmits a certificate with a downstream annotation because no server can be downstream from a Remote Agent.

Using Passwords With SSL

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

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

The crkeys command validates that you specified the same password for both the keystores. 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.

The crkeys command enables you to create an encoded version of the keystore password. You can use the encoded version of the password in any properties files in which you intend to save the keystore password. Saving an encoded version of the password in a properties file is more secure than saving the plaintext version of a password in a properties file.

Limitations of SSL on the N1 Service Provisioning System 5.1

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

Configuring SSL – Process Overview

The following process overview describes the tasks necessary to configure the N1 Service Provisioning System 5.1 to use SSL.

  1. Determine the SSL connectivity that you want to use.

    For more information, see Overview of SSL Support in the N1 Service Provisioning System 5.1.

  2. Use the crkeys command to create keystores.

    See How to Create Keystores.

  3. Edit the config.properties file to configure SSL.

    See How to Edit the config.properties File to Configure SSL.

ProcedureHow to Create Keystores

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

When you create a keystore, 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
Step

    Generate the keys.


    % crkeys -options
    

    Use the following options to create keystores 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 host name of the application as the alias. The alias names must be unique within a keystore.

    -mode upstream|downstream

    Specifies the location of the machine that is being authenticated in relationship to the machine that is performing the authentication. For example, you are generating certificates for a Remote Agent that is downstream form a Local Distributor. Specify downstream as the mode for the Remote Agent. Specify upstream as the mode for the Local Distributor.

    -cpass

    Changes the password of the keystore and all the keys within the keystore.

    -delete

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

    -epass

    Converts and prints the encoded version of the plaintext password. Create an encoded version of a password if you plan to store the password in a file. For example, if you choose to store the keystore password in the config.properties file, you must supply an encoded version of the password.

    -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 host name 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 keystore.

    -new newpassword

    Specifies the new password for the keystore and all the keys in the keystore. The password must contain at least six characters.

    -password password

    Specifies the password for the keystore. If a password is not specified, the user is prompted for a password. The password must contain at least six characters.

    -private

    Specifies the private keystore as the target of the operation.

    -validity days_valid

    Number of days the self-signed certificate is valid.

    -trust

    Specifies the trust keystore as the target of the operation.


Example 8–1 crkeys Command Syntax

The following examples show how to use the crkeys command.

To generate a public-private key pair:


crkeys -private –generate -mode {upstream|downstream} –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 keystore, both the trust and the private store, password:


crkeys –cpass -password oldpassword 
-new newpassword

To convert and print the encoded version of the plaintext pasword:


crkeys -epass -password password

To print instructions for using the crkeys command:


crkeys -help

ProcedureHow to Edit the config.properties File to Configure SSL

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

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


Note –

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


Step

    (Optional) 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 that are connecting to it. 

    net.ssl.key.store.pass

     

    The keystore password. Required in some instances. See the following for more information. 


    Note –

    The net.ssl.key.store.pass parameter specifies the SSL keystore password for an N1 Service Provisioning System 5.1 application. Use this parameter when you configure an application with SSL keystores and you do not want to be prompted for the passwords to the keystore when you start the application. You must specify this parameter in the following instances:

    • When you setup the N1 Service Provisioning System applications to start automatically when the system boots

    • On Windows servers, N1 Service Provisioning System applications do not prompt for keystore passwords, so this parameter must be specified for any applications configured to use SSL on Windows servers.

    • The CLI application does not prompt for keystore passwords, so this parameter must be specified for any CLI Clients that you configure to use SSL.

    • If a Local Distributor is connected to its parent through an SSH connection, the Local Distributor cannot prompt for passwords.


Sample Configuration Scenarios


Example 8–2 How to Configure SSL Without Authentication Between the Master Server, Local Distributor, and Remote Agent

  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 browser 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.



Example 8–3 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.

  1. Generate a key pair for the Local Distributor and store it in the private keystore for the Local Distributor. Specify -mode downstream.


    % ld/bin/crkeys –private –generate -mode downstream –alias ldhostname-downstream.cr.com –validity 365
    
  2. Export the self-signed certificate from the private keystore on the Local Distributor into a file.


    % ld/bin/crkeys –private –export –file ld-downstream.cert –alias ldhostname-downstream.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 keystore.


    % server/bin/crkeys –trust –import –file ld-downstream.cert –alias ldhostname-downstream.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 keystore 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. Specify -mode downstream.


    % agent/bin/crkeys –private –generate -mode downstream –alias rahostname-downstream.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-downstream.cert –alias rahostname-downstream.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-downstream.cert –alias rahostname-downstream.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 keystore password for the Local Distributor and Remote Agent.

  24. Test the connection to the Remote Agent.



Example 8–4 How to Configure SSL Server and Client Authentication

  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. Edit the config.properties file to include the cipher suite you want to use and the encoded keystore password.

    You must use the same keystore password for all of the hosts.

  3. Generate a key pair for the Local Distributor and store it in the private store for the Local Distributor. Specify -mode downstream.


    % ld/bin/crkeys –private –generate -mode downstream –alias ldhostname-downstream.cr.com –validity 365
    
  4. Generate a key pair for the Master Server and store it in the private store for the Master Server. Specify -mode upstream.


    % server/bin/crkeys –private –generate -mode upstream –alias mshostname-upstream.cr.com –validity 365
    
  5. Export the self-signed certificate from the private store for the Local Distributor into a file.


    % ld/bin/crkeys –private –export –file ld-downstream.cert –alias ldhostname-downstream.cr.com
    
  6. Copy the self-signed certificate for the Local Distributor to the Master Server.

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


    % server/bin/crkeys –trust –import –file ld-downstream.cert –alias ldhostname-downstream.cr.com
    
  8. Export the self-signed certificate from the private store for the Master Server into a file.


    % server/bin/crkeys –private –export –file ms-upstream.cert –alias mshostname-upstream.cr.com
    
  9. Copy the self-signed certificate for the Master Server to the Local Distributor.

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


    % ld/bin/crkeys –trust –import –file ms.cert –alias mshostname.cr.com
    
  11. If already running, stop the Master Server and the Local Distributor.

  12. Start the Master Server and the Local Distributor.

  13. Provide the keystore password for the Master Server and Local Distributor.

  14. Create a new host.

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

  16. Test the connection to the Local Distributor.

  17. Generate a key pair for the Remote Agent and store it in the private store for the Remote Agent. Specify -mode downstream.


    % agent/bin/crkeys –private –generate -mode downstream –alias rahostname-downstream.cr.com –validity 365 
    
  18. Export the self-signed certificate from private store for the Remote Agent into a file.


    % agent/bin/crkeys –private –export –file ra-downstream.cert –alias rahostname-downstream.cr.com
    
  19. Copy the self-signed certificate for the Remote Agent to the Local Distributor.

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


    % ld/bin/crkeys –trust –import –file ra-downstream.cert –alias rahostname-downstream.cr.com
    
  21. Generate a key pair for the Local Distributor and store it in the private store for the Local Distributor. Specify -mode upstream.


    % ls/bin/crkeys -private -generate -mode upstream - alias ldhostname-upstream.cr.com -validity 365
    
  22. Export the self-signed certificate from the private store for the Local Distributor into a file.


    % ld/bin/crkeys -private -export -file ld-upstream.cert -alias ldhostname-upstream.cr.com
    
  23. Copy the self-signed certificate for the Local Distributor, that you exported in Step 21, to the Remote Agent machine.

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


    % agent/bin/crkeys –trust –import –file ld-upstream.cert –alias ldhostname-upstream.cr.com 
    
  25. If already running, stop the Local Distributor and Remote Agent.

  26. Start the Local Distributor and the Remote Agent.

  27. Provide the keystore password for the Local Distributor and Remote Agent.

  28. Create a new host.

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

  30. Test the connection to the Remote Agent.



Example 8–5 How to Configure SSL Authentication Between a CLI Client and Master Server

  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 keystore 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

Cipher Suites

The following lists describe the supported SSL cipher suites for all supported operating systems except IBM AIX.

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 
TLS_RSA_WITH_AES_128_CBC_SHA
TLS_DHE_RSA_WITH_AES_128_CBC_SHA
TLS_DHE_DSS_WITH_AES_128_CBC_SHA

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 
TLS_DH_anon_WITH_AES_128_CBC_SHA

The following suites require server authentication with no encryption:


SSL_RSA_WITH_NULL_MD5 
SSL_RSA_WITH_NULL_SHA 

Cipher Suites for IBM AIX

The following lists describe the supported SSL cipher suites for IBM AIX servers.

All of the following cipher suites are available for use with Remote Agents. Cipher suites that do not require server authentication cannot be used for Local Distributors.

The following suites require server authentication:


SSL_RSA_WITH_RC4_128_MD5
SSL_RSA_WITH_RC4_128_SHA
SSL_RSA_WITH_DES_CBC_SHA
SSL_RSA_FIPS_WITH_DES_CBC_SHA
SSL_RSA_WITH_3DES_EDE_CBC_SHA
SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA
SSL_DHE_RSA_WITH_DES_CBC_SHA
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
SSL_DHE_DSS_WITH_DES_CBC_SHA
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
SSL_RSA_EXPORT_WITH_RC4_40_MD5
SSL_RSA_EXPORT_WITH_DES40_CBC_SHA
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5
SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA

The following suites do not require server authentication:


Note –

Cipher suites that do not require server authentication cannot be used for Local Distributors.



SSL_DH_anon_WITH_RC4_128_MD5
SSL_DH_anon_WITH_DES_CBC_SHA
SSL_DH_anon_WITH_3DES_EDE_CBC_SHA
SSL_DH_anon_EXPORT_WITH_RC4_40_MD5
SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA

The following suites require server authentication with no encryption:


SSL_RSA_WITH_NULL_MD5
SSL_RSA_WITH_NULL_SHA