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/program/earlyadopters_files/protected/javadocs/SDK2.0RC2/doc/index.html
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.
# /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”);