test

Sun Java System Message Queue 4.3 Developer's Guide for C Clients

Working With Secure Connections

Establishing a secure connection between the client and the broker requires both the administrator and the developer to do some additional work. The administrator’s work is described in the Message Encryption in Sun Java System Message Queue 4.3 Administration Guide. In brief, it requires that the administrator do the following:

The developer must also do some work to configure the client for secure messaging. The work required depends on whether the broker is trusted (the default setting) and on whether the developer wants to provide an additional means of verification if the broker is not trusted and the initial attempt to create a secure connection fails.

The MessageQueue C-API library uses NSS to support the SSL transport protocol between the Message Queue C client and the Message Queue broker. The developer must take care if the client application using secure Message Queue connections uses NSS (for other purposes) directly as well and does NSS initialization. For additional information, see Coordinating NSS Initialization.

Configuring the Client for Secure Communication

By default the MQ_SSL_BROKER_IS_TRUSTED property is set to true, and this means that the Message Queue client runtime will accept any certificate that is presented to it. The following procedure explains what you must do to establish a secure connection.

ProcedureTo Establish a Secure Connection

  1. Set the MQ_CONNECTION_TYPE_PROPERTY to SSL .

  2. If you want the runtime to check the broker’s certificate, set the MQ_SSL_BROKER_IS_TRUSTED property to false. Otherwise, you can leave it to its default (true) value.

  3. Generate the NSS files CertN .db, keyN.db, and secmod.db using the certificate database tool certutil . You can find this tool at the following locations:

  4. Note the path name of the directory that contains the NSS files you generated in Configuring the Client for Secure Communication.

  5. If you have set the MQ_SSL_BROKER_IS_TRUSTED property to false, use the certutil tool to import the root certificate of the authority certifying the broker into the database files you generated in Configuring the Client for Secure Communication .

    Make sure that the MQ_BROKER_HOST_PROPERTY value is set to the same value as the (CN) common name in the broker’s certificate.

  6. If you have set the MQ_SSL_BROKER_IS_TRUSTED property to false, you have the option of enabling broker fingerprint-based verification in case authorization fails. For details, see Verification Using Fingerprints.

  7. Call the function MQInitializeSSL once (and only once) before creating the connection, and pass the name of the directory that contains the NSS files you generated in Configuring the Client for Secure Communication. If the broker is trusted, these files can be empty.

    You must call this function before you create any connection to the broker, including connections that do not use SSL.

Verification Using Fingerprints

If certificate authorization fails when the broker is using a certificate authority, it is possible to give the client runtime another means of establishing a secure connection by comparing broker certificate fingerprints. If the fingerprints match, the connection is granted; if they do not match, the attempt to create the connection will fail.

ProcedureTo Set Up Fingerprint Certification

  1. Set the broker connection property MQ_SSL_CHECK_BROKER_FINGERPRINT to true.

  2. Retrieve the broker’s certificate fingerprint by using the java keytool -list option on the broker’s keystore file:

    You will use the output of this command as the value for the connection property MQ_SSL_BROKER_CERT_FINGERPRINT in Verification Using Fingerprints. For example, if the output contains a value like the following:


    Certificate fingerprint (MD5): F6:A5:C1:F2:E6:63:40:73:97:64:39:6C:1B:35:0F:8E

    You would specify this value for MQ_SSL_BROKER_CERT_FINGEPRINT.

  3. Set the connection property MQ_SSL_BROKER_CERT_FINGEPRINT to the value obtained in Verification Using Fingerprints.

Coordinating NSS Initialization

If your application uses NSS directly, other than to support Message Queue secure communication, you need to coordinate NSS initialization with the Message Queue C-API library. There are two cases to consider:

ProcedureTo Coordinate NSS Initialization

  1. Call the function MQInitializeSSL. (You must specify the path to the directory containing the NSS files as the certdbpath parameter to this function.)

    Your application’s use of NSS must specify the same certdbpath value for the location of its NSS files. (That is, the certificates needed by your application must be located in the same directory as the certificates needed by Message Queue.)

    Internally, the function MQInitializeSSL does the following:

    • Calls the function NSS_Init(certdbpath).

    • Sets DOMESTIC cipher policy using the function NSS_SetDomesticPolicy().

    • Enables all cipher suites, including RSA_NULL_MD5 by calling the function SSL_CipherPrefSetDefault(SSL_RSA_WITH_NULL_MD5, PR_TRUE) .

    • Calls the function SSL_ClearSessionCache().

  2. If your application needs different cipher suite settings, after you call the MQInitializeSSL() function, you can modify the cipher suites by calling the function SSL_CipherPrefSetDefault. However, note that these changes will affect your secure connection to the Message Queue broker as well.