Getting Started with Secure Connections

Introduction
Authentication basics
Keystore Configuration Properties
Configurations for client connections
"No authentication" configuration
"CIMOM authentication" configuration
"Client authentication " configuration
"Mutual authentication" configuration
Creation of a keystore
Export of a certificate
Creation of a truststore
Import of a certificate
Configuration parameters for secure connections
Custom socket factories

Introduction

The following text will explain how to get secure connections from the SBLIM CIM Client for Java to the CIM Object Manager working.

SSL/TLS may provide

  • confidentiality - no third party can read the content of the communication.
  • integrity - no third party can alter the content of the communication unnoticed.
  • authentication - the identity of one or both partners is confirmed.
Confidentiality is ensured by encryption of any data sent over the network. Integrity is ensured by hashes of the data that can be used by the receiver to detect any changes. Authentication is implemented by exchanging X509 certificates between client and CIMOM. Note that SSL/TLS authentication is on a communication endpoint scope and not on a user scope. It ensures that two systems talking to each other really have the identities they proclaim. User authentication is usually done on an application level (here CIMOM) in addition to SSL/TLS.

The more complex part of SSL/TLS setups is the authentication. If you can live without it, things get much easier. Below you'll find a table with the possible configurations. The higher the number the more complex and secure it becomes. Keep in mind that you cannot choose the security configuration independently of your counterpart (the CIMOM), e.g. if the CIMOM defines client authentication as mandatory you cannot get around it. Vice-versa if the CIMOM doesn't care about client authentication you might send as many certificates you want - it will never ever evaluate them.

Authentication basics

SSL/TLS authentication is X509 certificate-based. Each side provides a X509 certificate that confirms its identity. The certificates are exchanged and each side validates the received certificate against a local copy.

To store the certificates two files are used. The first is the so-called keystore and contains your own certificate with all private and public key information. The second is the so-called truststore and contains local copies of certificates from other systems you trust. These copies contain only the public key information.

How to create a keystore for Java is explained here.

The described mechanism would enforce every receiver to have the certificate of every trusted sender stored in its truststore. Certificate chains were invented to get around this. In a certificate chain an organization certifies the authenticity of an entity's certificate and the receiver just validates the authenticity of the organization's certificate. Therefore with just the certificate of the organization in the truststore the receiver can validate all entities that have certificates based on the organization's certificate.

Keystore Configuration Properties

The following properties allow you to configure the client keystore and truststore:

  • javax.net.ssl.keyStore: The file path of the SSL keystore.
  • javax.net.ssl.keyStoreType: The type of the SSL keystore repository. Typically this is JKS or Java KeyStore type, which is the default.
  • javax.net.ssl.keyStorePassword: The password of the keystore.
  • javax.net.ssl.trustStore: The file path of the SSL truststore.
  • javax.net.ssl.trustStoreType: The type of the SSL truststore repository. Typically this is JKS, which is the default.
  • javax.net.ssl.trustStorePassword: The password of the truststore.

Whenever the keystore properties are defined for the client -- either by global configuration via the properties file or via a call to System.setProperty(), or set for the client directly via a call to setProperty() on an instance of a client -- the keystore will be activated automatically and no further configuration is required.

For the truststore however, an additional property is provided to control activation; setting the above truststore properties alone is not sufficient to enable the truststore. (The reason for this difference is explained in more detail in Getting Started with Secure Indications). To enable the truststore you must set the following property to true (the default is false):

  • sblim.wbem.sslClientPeerVerification: Determines if a HTTPS client will attempt to authenticate the server (i.e. CIMOM) by verifying the server certificate. If true, the client will attempt to verify the server certificate against the contents of the truststore defined in "javax.net.ssl.trustStore". If false, no verification is attempted.

If the truststore properties are set but sslClientPeerVerification is false, the truststore is not activated and all connections will be allowed (i.e. every CIMOM is trusted). The only real use of this configuration is to temporarily disable the truststore for testing. Conversely, if sslClientPeerVerification is true but the truststore properties are not set (or the truststore file is missing or otherwise unreadable), no connections will be allowed (i.e. no CIMOM is trusted), as this is considered to be a misconfiguration. In both cases, a WARNING message is sent to the logger.

Configurations for client connections

The table below shows the possible configurations.

ConfigurationEncryption/HashingCIMOM authenticatedClient authenticatedSecure indication
listeners supported
No authenticationyesnonono
CIMOM authenticationyesyesnono
Client authenticationyesnoyesyes
Mutual authenticationyesyesyesyes

"No authentication" configuration

  • Confidentiality: given
  • Integrity: given
  • Authentication: no
  • Keystore: No
  • Truststore: No

To open an SSL/TLS-secured client connection to a CIMOM just make your client call as usual, but replace "http" by "https" as well as the non-secure port (usually 5988) by the secure port (usually 5989) in the CIMOM URL. That's all!

Note: In this scenario we decided not to evaluate the CIMOM's X509 certificate. The client is free to do that.

Note: We also decided not to send any X509 certificate to the CIMOM to authenticate ourselves. This will work only if the CIMOM is configured to ignore client certificates. If the CIMOM's configuration is to check certificates the connection will be refused by the CIMOM. Today the vast majority of CIMOMs are configured to not check client certificates.

"CIMOM authentication" configuration

  • Confidentiality: given
  • Integrity: given
  • Authentication: server only
  • Keystore: No
  • Truststore: Required

In this scenario we configure the client to check the identity of the CIMOM. To do this we need to create a truststore and set the appropriate configuration properties described above. When sslClientPeerVerification is set to true, the keystore will be activated and the client will automatically check the CIMOM certificate against the truststore. Everything else is equal to the "no authorization" configuration

Note: In this scenario we decided to evaluate the CIMOM's X509 certificate. In order to do that we have to import the CIMOM's certificate into our truststore. See importing a certificate for details.

Note: In this scenario we decided not to send any X509 certificate to the CIMOM to authenticate ourselves. This will work only if the CIMOM is configured to ignore client certificates. If the CIMOM's configuration is to check certificates the connection will be refused by the CIMOM. Today the vast majority of CIMOMs are configured to not check client certificates.

"Client authentication" configuration

  • Confidentiality: given
  • Integrity: given
  • Authentication: client only
  • Keystore: Required
  • Truststore: No

In this scenario we configure the CIMOM to check the identity of the client. We want our client to send a certificate to the CIMOM and for that we need to create a keystore and set the appropriate configuration properties. Once this is done the keystore will be activated and the client will automatically send our certificate on request by the CIMOM. Everything else is equal to the "no authorization" configuration.

Note: In this scenario we decided not to evaluate the CIMOM's X509 certificate. The client can be configured to do that as described above.

Note: The CIMOM has to be enabled to validate our certificate. To do this we must import into the CIMOM's truststore either a copy of our client cert or an appropriate "Certificate Authority" (CA) cert that is a signer for our client cert. (Really , the most general case is that the CA cert is the signer of one or more certs in a trust chain leading to our client cert.) The simplest case is where the CIMOM has a copy of our client cert. See exporting a certificate for a description on how to export a certificate from your client keystore so that you can import it into the CIMOM's truststore or other central certificate store (e.g. LDAP).

Finally, note that most CIMOMs have three configurable settings governing authentication of the client: SFCB has ignore, accept, require. OpenPegasus has disabled, optional, required. In the case of ignore (disabled), the CIMOM will not check the client certificate. In the case of require (required) it will. The often confusing case is accept (optional); here the CIMOM will enforce the certificate check only if the client provides one. If your CIMOM is so configured you may find that it happily accepts the connection without the client sending any X509 certificate. But once the client keystore is configured and the client does send a certificate, the CIMOM will suddenly behave as if require (required) is configured, and will refuse the connection if it is unable to verify the client cert.

"Mutual authentication" configuration

  • Confidentiality: given
  • Integrity: given
  • Authentication: client and CIMOM
  • Keystore: Required
  • Truststore: Required

In this scenario we configure certificate validation in both directions simultaneously.

In short, this configuration comprises the "CIMOM authentication" and "Client authentication" together.

Creation of a Keystore

Keystores hold public/private key pairs that are used to authenticate ourselves with others and as asymmetric key to encrypt the handshake for the symmetric session key. The JVM provides a tool that creates a keystore and generates keys: keytool

keytool creates a file named keystore, generates a private/public key pair and stores it in the file. Such a file that stores private/public key pairs for authentication ourselves with others is called "keystore". Open a shell, change to your JVMs bin directory and enter:

keytool -genkey -alias mykey -keyalg RSA -validity 7 -keystore keystore

keytool will ask you a lot of questions and finally request a password for the keystore. This password is essential for later access to the keystore.

Now that we have created a key and a keystore we have to tell the SBLIM CIM Client for Java where to find it. There are three possibilities:

  • Starting the JVM with -Djavax.net.ssl.keyStore=<path> -Djavax.net.ssl.keyStorePassword=<password>
  • Setting the JVM system properties javax.net.ssl.keyStore and javax.net.ssl.keyStorePassword to the keystore path/password using System.setProperty() at runtime.
  • Setting javax.net.ssl.keyStore and javax.net.ssl.keyStorePassword to the keystore path/password in the sblim-cim-client2.properties file.

Creation of a Truststore

Truststores hold public certificates that are used to authenticate others with ourselves. The JVM provides a tool that creates a truststore: keytool A truststore file is automatically created when you import a certificate with keytool, see import of a certificate for details.

Once we have created a truststore we have to tell the SBLIM CIM Client for Java where to find it. There are three possibilities:

  • Starting the JVM with -Djavax.net.ssl.trustStore=<path> -Djavax.net.ssl.trustStorePassword=<password>
  • Setting the JVM system properties javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword to the truststore path/password using System.setProperty() at runtime.
  • Setting javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword to the truststore path/password in the sblim-cim-client2.properties file.

Import of a Certificate

If you want to import the public part of a CIMOM's certificate in your truststore you can do that with keytool:

keytool -import -alias mycimom -file mycimom.cer -keystore truststore
Please refer to the CIMOM's documentation regarding the export of the CIMOM's certificate.

A note on terminology: we use the terms keystore and truststore to refer to the certificate stores that perform the roles described above. Be aware that the term keystore is also used in the general sense to describe any certificate store, regardless of role. This latter definition is used by keytool, and for that reason you will use the -keystore option to point to either your keystore or truststore.

Also note: Your JVM might ship with a default truststore (containing common CA certificates issued by well-known certificate authorities). If so, the above command would import the cert into the existing truststore. If not, a new truststore will be created. In either case keytool will prompt you for a password. For an exisitng truststore the password will be the one already set for the truststore (commonly this is "changeit" for the default JVM truststore). For a new truststore, the password you provide will be the one set going forward. In either case you can optionally specify the password on the command line using the -password option.

Export of a certificate

If you want to export the public part of your certificate to a file (e.g. for import into to a CIMOM's truststore) you can do that with keytool:

keytool -export -alias mykey -keystore keystore -rfc -file mykey.cer

The -rfc option ensures the cert is exported in PEM format, the format commonly required by the CIMOM.

Please refer to the CIMOM's documentation regarding the import of the certificate into the CIMOM's truststore.

Configuration parameters for secure connections

The configuration parameters can be found here. The properties beginning with KEYSTORE_, TRUSTSTORE_ or SSL_ control the SSL configuration.

Note: The SSL system properties globally configure the JREs SSL support. If you want to use settings different from the global JRE configuration, you'll have to use WBEMClientSBLIM.setProperty() to override the global setting. Keep in mind that this applies only to the specific WBEMClient instance. There is no way to set a global SSL configuration for the CIM client independent from the JRE configuration.

Custom socket factories

You can pass your own SocketFactory to the SBLIM CIM Client for Java by casting the WBEMClient returned from WBEMClientFactory.getClient() to WBEMClientSBLIM and calling the setCustomSocketFactory(). This setting applies only to this specific WBEMClient instance.

By setting your own SocketFactory you're bypassing the SSL configuration of the SBLIM CIM Client for Java. When creating the SocketFactory you set up your own SSLContext that defines things like keystores, truststores, algorithms, etc. Using your own SocketFactory you may be able to get around any limitations of the SBLIM CIM Client for Java's SSL/TLS support.