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
Note: There is no interface Client interfaces between version 1.1 and 2.0
|
Java
Client APIs in SDK 2.0 |
|
|
CIMClient(CIMNameSpace
name )
throws CIMException |
Creates connection the CIMServer
running on the local system for the specified namespace. |
|
CIMClient( CIMNameSpace
name, String userName, String password) throws CIMException CIMClient( CIMNameSpace
name, String userName, String password, int
protocol) throws CIMException |
Creates a new HTTP/S client connection to the CIMServer on the host and namespace specified in the CIMNamespace object, using the specified username and
password to authenticate the client user identity to the CIM Object Manager. |
|
void close() throws CIMException |
Closes the client connection to the CIM Object
Manager. |
|
void createNameSpace( CIMNameSpace
name) throws CIMException |
Creates a CIM namespace, a directory containing CIM
classes and CIM instances. |
|
void deleteNameSpace( CIMNameSpace
name) throws CIMException |
Deletes the specified namespace on the specified host. |
|
Enumeration enumNameSpace( CIMObjectPath
path, boolean deepInheritance) throws CIMException Enumeration enumerateNameSpaces( CIMObjectPath
path, boolean deepInheritance) throws CIMException |
Enumerates the namespaces within the specified path. |
|
CIMClass getClass( CIMObjectPath
path, boolean localOnly) throws CIMException CIMClass getClass( CIMObjectPath path, boolean localOnly, boolean includeQualifiers, boolean includeClassOrigin, String propertyList[
] ) throws CIMException |
Gets a single CIM Class from the target Namespace where
the CIMObjectPath input parameter defines the name
of the class to be retrieved. |
|
CIMInstance getInstance( CIMObjectPath
path, boolean localOnly) throws CIMException CIMInstance getInstance( CIMObjectPath
path, boolean localOnly, boolean includeQualifiers, boolean includeClassOrigin, String propertyList[
] ) throws CIMException |
Gets the CIM instance for the specified CIM object path. |
|
void deleteClass( CIMObjectPath
path) throws CIMException |
Deletes a single CIM Class from the target Namespace for
the object specified by the CIMobjectpath. |
|
void deleteInstance( CIMObjectPath
path) throws CIMException |
Deletes the CIM instance specified by the CIM object path
from the target Namespace. |
|
void createClass( CIMObjectPath
path, CIMClass newClass) throws CIMException |
Creates a single CIM class in the target namespace. |
|
CIMObjectPath createInstance( CIMObjectPath
path, CIMInstance newInstance) throws CIMException |
Creates the specified CIM Instance in the specified
namespace. |
|
void setClass( CIMObjectPath
path, CIMClass cimClass) throws CIMException void modifyClass( CIMObjectPath
path, CIMClass modifiedClass) throws CIMException |
Modifies an existing CIM Class in the target
Namespace. |
|
Enumeration enumClass( CIMObjectPath
path, boolean deepInheritance, boolean localOnly) throws CIMException Enumeration enumerateClasses( CIMObjectPath
path, boolean deepInheritance, boolean localOnly, boolean includeQualifiers, boolean includeClassOrigin) throws CIMException |
Enumerates the subclasses (with all properties) of the CIM
Class specified in the path in the target Namespace. |
|
Enumeration enumClass( CIMObjectPath
path, boolean deepInheritance) throws CIMException Enumeration enumerateClassNames( CIMObjectPath
path, boolean deepInheritance) throws CIMException |
Enumerates the names of subclasses of the CIM Class specified
in the path in the target Namespace. |
|
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 |
Enumerates instances of the specified CIM Class in the target
Namespace. |
|
Enumeration enumInstances( CIMObjectPath
path, boolean deepInheritance) throws CIMException Enumeration enumerateInstanceNames( CIMObjectPath
path) throws CIMException |
Enumerates the names (object paths) of the instances of
the specified CIM Class in the target Namespace. |
|
Enumeration execQuery( CIMObjectPath
path, String query, int queryLanguage) throws
CIMException |
Executes a query against the target Namespace to
retrieve the objects. |
|
Enumeration associators( CIMObjectPath
path, String assocClass, String resultClass, String role, String resultRole, boolean includeQualifiers, boolean includeClassOrigin, String propertyList[
] ) throws CIMException |
Enumerate CIM Objects that are associated to a particular
source CIM Object. |
|
Enumeration associatorNames( CIMObjectPath
path,
String assocClass, String resultClass, String role, String resultRole)
throws CIMException |
Enumerate the object paths to CIM Objects that are
associated to a particular source CIM Object. |
|
Enumeration references( CIMObjectPath
path, String resultClass, String role, boolean includeQualifiers, boolean includeClassOrigin, String propertyList[
] ) throws CIMException |
Enumerates the association objects that refer to a
particular target CIM Object. |
|
Enumeration referenceNames( CIMObjectPath
path, String resultClass, String role) throws CIMException |
Enumerates the object paths to association objects that refer
to a particular target CIM Object. |
|
CIMValue getProperty( CIMObjectPath
path, String propertyName)
throws CIMException |
Gets the value of the specified property for the
instance specified in the CIM object path. |
|
void setProperty( CIMObjectPath
path, String propertyName, CIMValue newValue) throws CIMException |
Modifies the value of the specified property by setting it
to the specified value for the instance specified in the object path. |
|
CIMQualifierType getQualifierType( CIMObjectPath
path) throws CIMException CIMQualifierType getQualifier( CIMObjectPath
path) throws CIMException |
Gets the CIM qualifier type specified in the CIM object
path from the traget Namespace. |
|
Void setQualifierType( CIMObjectPath
path, CIMQualifierType
qualifierType) throws CIMException void setQualifier( CIMObjectPath
path, CIMQualifierType
qualifierType) throws CIMException |
Creates or updates the specified CIM qualifier type in the
traget namespace. |
|
void deleteQualifierType( CIMObjectPath
path) throws CIMException void deleteQualifier( CIMObjectPath
path) throws CIMException |
Deletes the CIM Qualfier
declaration from the target Namespace. |
|
Enumeration enumQualifierTypes( CIMObjectPath
path) throws CIMException Enumeration enumerateQualifiers( CIMObjectPath
path) throws CIMException |
Enumerates the Qualifier declarations from the target
Namespace. |
|
void createQualifierType( CIMObjectPath
path, CIMQualifierType
qt) throws CIMException void setQualifier( CIMObjectPath
path, CIMQualifierType
qualifierType) throws CIMException |
Creates or updates the specified CIM qualifier type in the
traget namespace. |
|
CIMValue invokeMethod( CIMObjectPath
path, String methodName, Vector inParams, Vector outParams)
throws CIMException |
Executes a specified method on the specified object. |
Note that CIM HTTP Listener interfaces are not supported in WBEM Java SDK 1.1 and pre-releases. They are supported in 2.0 onwards
|
CIMHTTPListener APIs in SDK 2.0 |
|
|
|
Constructor for CIMHTTPListener with port number, by default SSL is not enabled |
|
|
Constructor takes a port number
and ssl option. |
|
start() |
Start the CIM HTTP Listener |
|
stop() |
Stop CIM HTTP Listener |
|
addConsumer (
|
Adds a CIMIndicationConsumer to the listener |
|
CIMIndicationConsumer interface |
|
|
|
Constructor for CIMHTTPListener with port number, by default SSL is not enabled |
Importing Certificates into
Java Trust Store
1. Export the server certificate from the .pem file.
Use openssl command to export Pegasus
CIMServer certificate file. Assumes that openssl
is part of /opt/wbem/sbin/.
# /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.
For more information about writing trust managers, refer to JSSE reference guide (http://java.sun.com/j2se/1.4/docs/guide/security/jsse/JSSERefGuide.html
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”);