#

# WBEM Java Client SDK

## Overview

The WBEM Java Client SDK is a set of APIs that contain the components necessary to write management applications that communicate with WBEM-enabled management devices using XML and HTTP communication standards.

WBEM applications request information or services from the Common Information Model (CIM) Object Manager through the WBEM APIs. These APIs represent CIM objects as Java classes. These APIs can be used to describe managed objects and retrieve information about managed objects on a system.

WBEM client applications use the `org.snia.wbem.client` APIs to manipulate CIM objects. A client application uses the CIM API to construct an object (for example, a class, instance, or namespace) and then initializes, or instantiates that object. The application uses the client APIs to pass the object to the CIM Object Manager and request an operation, such as creating a CIM class, instance, or deleting an instance.

The following sections show the API comparison between SDK 1.0 and 1.1 onward releases, SSL certificate management changes and configuration changes.

The Java SDK 2.0 documentation includes the following packages that the client applications can use to make CIM operation requests to talk to a CIM Object Manager.

org.snia.wbem.client

org.snia.wbem.cim

org.snia.wbemcfg

org.snia.wbem.listner

The java doc documentation for these packages can be found at

http://haweb.cup.hp.com/wbem/javadocs/sniaclient/.

## API Changes

### Java Client APIs in SDK 1.0

Java Client APIs in SDK 2.0

CIMClient() throws CIMException

CIMClient(

CIMNameSpace name)

throws CIMException

CIMClient(

CIMNameSpace name,

String userName,

String pword) throws CIMException

CIMClient(

CIMNameSpace name,

String userName,

String pword,

int type) throws CIMException

CIMClient(

CIMNameSpace name,

String userName,

String pword,

String roleName,

String rolePwd) throws CIMException

CIMClient(

CIMNameSpace name,

String userName,

String pword,

String roleName,

String rolePwd,

int type) throws CIMException

CIMClient(

CIMNameSpace name,

String userName,

String password) throws CIMException

CIMClient(

CIMNameSpace name,

String userName,

String password,

int protocol) throws CIMException

void close() throws CIMException | void close() throws CIMException
void createNameSpace( CIMNameSpace ins) throws CIMException | void createNameSpace( CIMNameSpace name) throws CIMException
void deleteNameSpace( CIMNameSpace cns) throws CIMException | void deleteNameSpace( CIMNameSpace name) throws CIMException
Enumeration enumNameSpace( CIMObjectPath path, boolean deep) throws CIMException | Enumeration enumNameSpace( CIMObjectPath path, boolean deepInheritance) throws CIMException Enumeration enumerateNameSpaces( CIMObjectPath path, boolean deepInheritance) throws CIMException
CIMClass getClass( CIMObjectPath path, boolean localOnly) throws CIMException | CIMClass getClass( CIMObjectPath path, boolean localOnly) throws CIMException CIMClass getClass( CIMObjectPath path, boolean localOnly, boolean includeQualifiers, boolean includeClassOrigin, String propertyList[ ] ) throws CIMException

CIMInstance getInstance( CIMObjectPath path, boolean localOnly) throws CIMException | CIMInstance getInstance( CIMObjectPath path, boolean localOnly) throws CIMException CIMInstance getInstance( CIMObjectPath path, boolean localOnly, boolean includeQualifiers, boolean includeClassOrigin, String propertyList[ ] ) throws CIMException
void deleteClass( CIMObjectPath path) throws CIMException | void deleteClass( CIMObjectPath path) throws CIMException
void deleteInstance( CIMObjectPath path) throws CIMException | void deleteInstance( CIMObjectPath path) throws CIMException
void createClass( CIMObjectPath path, CIMClass cc) throws CIMException | void createClass( CIMObjectPath path, CIMClass newClass) throws CIMException
CIMObjectPath createInstance( CIMObjectPath path, CIMInstance ci) throws CIMException | CIMObjectPath createInstance( CIMObjectPath path, CIMInstance newInstance) throws CIMException
void setClass( CIMObjectPath path, CIMClass cc) throws CIMException | void setClass( CIMObjectPath path, CIMClass cimClass) throws CIMException void modifyClass( CIMObjectPath path, CIMClass modifiedClass) throws CIMException
void setInstance( CIMObjectPath path, CIMInstance ci) throws CIMException | void setInstance( CIMObjectPath path, CIMInstance cimInstance) throws CIMException void modifyInstance( CIMObjectPath path, CIMInstance modifiedInstance, boolean includeQualifiers, String propertyList[ ] ) throws CIMException
Enumeration enumClass( CIMObjectPath path, boolean deep, boolean local) throws CIMException | Enumeration enumClass( CIMObjectPath path, boolean deepInheritance, boolean localOnly) throws CIMException Enumeration enumerateClasses( CIMObjectPath path, boolean deepInheritance, boolean localOnly, boolean includeQualifiers, boolean includeClassOrigin) throws CIMException
Enumeration enumClass( CIMObjectPath path, boolean deep) throws CIMException | Enumeration enumClass( CIMObjectPath path, boolean deepInheritance) throws CIMException Enumeration enumerateClassNames( CIMObjectPath path, boolean deepInheritance) throws CIMException

Enumeration enumInstances(

CIMObjectPath path,

boolean deep,

boolean localOnly) throws CIMException

Enumeration enumInstances(

CIMObjectPath path,

boolean deepInheritance,

boolean localOnly) throws CIMException

Enumeration enumerateInstances(

CIMObjectPath path,

boolean deepInheritance,

boolean localOnly,

boolean includeQualifiers,

boolean includeClassOrigin,

String propertyList[ ] ) throws CIMException

Enumeration enumInstances( CIMObjectPath path, boolean deep) throws CIMException | Enumeration enumInstances( CIMObjectPath path, boolean deepInheritance) throws CIMException Enumeration enumerateInstanceNames( CIMObjectPath path) throws CIMException
Enumeration execQuery( CIMObjectPath path, String query, int ql) throws CIMException | Enumeration execQuery( CIMObjectPath path, String query, int queryLanguage) throws CIMException

Enumeration associators(

CIMObjectPath path,

String assocClass,

String resultClass,

String role,

String resultRole,

boolean includeQualifiers,

boolean includeClassOrigin,

String propertyList[]) throws CIMException

Enumeration associators(

CIMObjectPath path,

String assocClass,

String resultClass,

String role,

String resultRole,

boolean includeQualifiers,

boolean includeClassOrigin,

String propertyList[ ] )throws CIMException

Enumeration associatorNames( CIMObjectPath path, String assocClass, String resultClass, String role, String resultRole) throws CIMException | Enumeration associatorNames( CIMObjectPath path, String assocClass, String resultClass, String role, String resultRole) throws CIMException
Enumeration references( CIMObjectPath path, String resultClass, String role, boolean includeQualifiers, boolean includeClassOrigin, String propertyList[]) throws CIMException | Enumeration references( CIMObjectPath path, String resultClass, String role, boolean includeQualifiers, boolean includeClassOrigin, String propertyList[ ] ) throws CIMException
Enumeration referenceNames( CIMObjectPath path, String resultClass, String role) throws CIMException | Enumeration referenceNames( CIMObjectPath path, String resultClass, String role) throws CIMException
CIMValue getProperty( CIMObjectPath path, String propertyName) throws CIMException | CIMValue getProperty( CIMObjectPath path, String propertyName) throws CIMException
void setProperty( CIMObjectPath path, String propertyName, CIMValue newValue) throws CIMException | void setProperty( CIMObjectPath path, String propertyName, CIMValue newValue) throws CIMException
CIMQualifierType getQualifierType( CIMObjectPath path) throws CIMException | CIMQualifierType getQualifierType( CIMObjectPath path) throws CIMException CIMQualifierType getQualifier( CIMObjectPath path) throws CIMException
void setQualifierType( CIMObjectPath path, CIMQualifierType qt) throws CIMException | Void setQualifierType( CIMObjectPath path, CIMQualifierType qualifierType) throws CIMException void setQualifier( CIMObjectPath path, CIMQualifierType qualifierType) throws CIMException
void deleteQualifierType( CIMObjectPath path) throws CIMException | void deleteQualifierType( CIMObjectPath path) throws CIMException void deleteQualifier( CIMObjectPath path) throws CIMException
Enumeration enumQualifierTypes( CIMObjectPath path) throws CIMException | Enumeration enumQualifierTypes( CIMObjectPath path) throws CIMException Enumeration enumerateQualifiers( CIMObjectPath path) throws CIMException
void createQualifierType( CIMObjectPath path, CIMQualifierType qt) throws CIMException | void createQualifierType( CIMObjectPath path, CIMQualifierType qt) throws CIMException void setQualifier( CIMObjectPath path, CIMQualifierType qualifierType) throws CIMException
CIMValue invokeMethod( CIMObjectPath path, String methodName, Vector inParams, Vector outParams) throws CIMException | CIMValue invokeMethod( CIMObjectPath path, String methodName, Vector inParams, Vector outParams) throws CIMException
void addCIMListener( CIMListener l) throws CIMException void addCIMListener( int port, CIMListener l) throws CIMException | <<Not in SDK 2.0, planned for future release>>
void removeCIMListener( CIMListener l) throws CIMException | <<Not in SDK 2.0, planned for future release>>

## SSL Certificate Management

Importing Certificates into Java Trust Store

1. Export the server certificate from the .pem file.

Use openssl command to export Pegasus CIMServer certificate file.

# /opt/wbem/sbin/openssl x509 -in /var/opt/wbem/server.pem -out server.cer

2. Import the server certificate in to the client trust store.

- Copy the server certificate on to the client system.

- Use Java keytool to import the certificate into the client trust store.

# keytool -import -alias sequoia1 -file server.cer -keystore mytruststore

You will be asked to enter a password. The password is required only for modifying mytruststore in the future. The keytool creates the trust store if it is not already exists and then import the specified certificate. (For example we entered the password as “wbem01”)

3. Specify the truststore in the command line of the client application using “-Djavax.net.ssl.trustStore”.

For Example,

# java -Djavax.net.ssl.trustStore=mytruststore <MyClient> <system> root/cimv2 5989 ssl

4. If your client application is written to update the truststore file programmatically then you must also specify the password that was used to create the truststore using “-Djavax.net.ssl.trustStorePassword”.

For Example,

# java -Djavax.net.ssl.trustStore=mytruststore -Djavax.net.ssl.trustStorePassword=wbem01 \

<MyClient> <system> root/cimv2 5989 ssl

Viewing Certificates and Trust Store files

1. You view certificates in a certificate file using keytool command.

keytool -printcert -file server.cer

2. You can view all the certificates in a truststore using the keytool command.

keytool -list -v -keystore mytruststore

Writing A Trust Manager

The primary responsibility of the TrustManager is to determine whether the presented authentication credentials should be trusted or not. If the credentials are not trusted, the connection will be terminated. If no trust manager is specified by the client application then JSSE will use its own trust manager that supports authentication based on X.509 public key certificates.

If the default X509TrustManager behavior isn't suitable for your situation, you can implement your own X509TrustManager. JSSE interface allows you to override certification validation and continue the SSL handshake. You can also use the interface to discontinue an SSL handshake by performing additional validation on a server's digital certificate chain.

When an SSL client connects to an SSL server, the SSL server presents its digital certificate chain to the client for authentication. This certificate chain can contain invalid digital certificates. As per the SSL specification, the client should drop the SSL connection once it discovers an invalid certificate. However, some applications such as Web Browsers ask the user whether to accept the invalid certificate. The Trust Manager eliminates this inconsistent practice by enabling you to control when to continue or discontinue an SSL connection. Using a Trust Manager you can perform custom checks before continuing an SSL connection. For example, you can use the Trust Manager to specify that only users from specific localities, such as towns, states, or countries, or users with other special attributes, to gain access via the SSL connection.

Here is an example of a Trust Manager that basically ignores the server certificates chain by not validating the certificate chain. It accepts any certificates from any server and goes ahead with SSL handshake.

import java.security.cert.*;

import java.security.KeyStore;

import javax.net.*;

import javax.net.ssl.*;

/**

* This class implements the X509TrustManager interface. It does not validate the certificate chain

* sent by the server, it basically ignores the certificate chain and goes ahead with the SSL hand shake.

*/

public class DontValidateCertificate implements X509TrustManager

{

X509TrustManager myX509TrustManager;

/**

* CertficateManager constructor

*/

public DontValidateCertificate()

{

}

/**

* checkClientTrusted checks to see if the chain is in the keyStore object.

*/

public void checkClientTrusted(X509Certificate[] chain, String authType) throws CertificateException

{

}

/**

* checkServerTrusted verifies to see if the chain is in the keyStore object.

*/

public void checkServerTrusted(X509Certificate[] chain, String authType) throws CertificateException

{

}

/**

* This method retrieves all of the certificates in the keyStore and returns them in

* an X509Certificate array. We return null as we are accepting any certificates.

*/

public X509Certificate[] getAcceptedIssuers()

{

return null;

}

}

The Client SDK contains the following two sample trust managers.

org.snia.wbemcmd.xml.CertificateManager

org.snia.wbemcmd.xml.DontValidateCertificate

Client API uses JSSE trust manager by default. If you want the API to use your own trust manager then you need to explicitly specify.

Refer to JSSE reference guide (http://java.sun.com/j2se/1.4/docs/guide/security/jsse/JSSERefGuide.html) for more information about writing trust managers.

## Configuration

The Client SDK allows the client applications to specify the following configuration properties in a property file. If no property file is specified then the SDK will use default values for all the properties. If the property file is specified but one or more properties are not set in the property file, then SDK will use the default values for those properties.

Property Name | Default Value
DEBUG_XML DEBUG_XMLDECODE clientLogFilePath TrustManager | False False "clientout.txt" null [ uses JSSE default Trust Manager ]

The DEBUG_XML, DEBUG_XMLDECODE, and clientLogFilePath properties are only for developmental debug purposes and they should not be set in the release product and should not be exposed to the client application users.

Note: The debug trace or logging in the client API is not thread safe, it is recommended that clients do not use debug logging in a multi-threaded application.

The client applications can only use the set methods in “GlobalConfig” class to set the following configuration properties if needed. The above four properties can also be set using the set methods.

Property Name | Default Value
httpSocketProvider httpsSocketProvider | org.snia.wbemcmd.xml.PlainSocketProvider org.snia.wbemcmd.xml.JSSESocketProvider

The client applications can specify the properties file in the following ways:

1. Specify the property file on the command line by setting “–D org.snia.wbem.cimom.properties”

For example,

# java -Dorg.snia.wbem.cimom.properties=./cim.properties <myAapp>

2. Specify the property file programmatically using the System.setProperty() before creating the CIMClient object.

For example,

System.setProperty("org.snia.wbem.cimom.properties", “./cim.properties”);