User's Manual

ManualsBrandsRaritan Computer ManualsSoftwareCC-WSAPI-0B-v5.1.0-E

CC-WSAPI-0B-v5.1.0-E

February 2011

255-80-0004-00

CommandCenter Secure Gateway

WS-API Programming Guide

Release 5.1

Summary of content (54 pages)

PAGE 2
This document contains proprietary information that is protected by copyright. All rights reserved. No part of this document may be photocopied, reproduced, or translated into another language without express prior written consent of Raritan, Inc. © Copyright 2011 Raritan, Inc. All third-party software and hardware mentioned in this document are registered trademarks or trademarks of and are the property of their respective holders.
PAGE 3
Contents Chapter 1 Introduction 1 Connecting to CC-SG .................................................................................................................... 1 Add Web Services API Client Configuration on CC-SG ...................................................... 2 Access Information ........................................................................................................................ 4 WSDL URLs .............................................................................
PAGE 4
Contents Appendix A Certificate Management 28 Java keytool ................................................................................................................................. 28 OpenSSL ..................................................................................................................................... 28 Saving the CCSG's Server Certificate from a Web Browser (IE6) ..............................................
PAGE 5
Chapter 1 Introduction Web Services API uses standardized Web Services technologies to allow a client machine to perform node, power, user, and logging management services. This client is independent of the CC-SG, but aims to provide the same capabilities that the CC-SG's HTML-based Access Client provides, through use of the API and a TCP/IP network.
PAGE 6
Chapter 1: Introduction 3. Download WSDL files from the CC-SG. You can use a web browser or a simple client like wget to access the WSDL URLs. See WSDL URLs (on page 4) 4. Choose a WS client library for your target language. 5. Use the tools provided with your chosen WS client library to generate stubs in your target language. Each stub should be a complete web service operation such that all that you must do is call the web service as a method/function with the appropriate parameters. 6.
PAGE 7
Chapter 1: Introduction a. Encryption Mode: If Require AES Encryption between Client and Server is selected in the Administration > Security > Encryption screen, AES-128 is the default. If AES is not required, DES 3 is the default. b. Private Key Length: 1024 is the default. c. Validity Period (days): Maximum 4 numeric characters. d. Country Code: CSR tag is Country Name. e. State or Province: Maximum 64 characters. Type in the whole state or province name. Do not abbreviate. f.
PAGE 8
Chapter 1: Introduction Access Information WSDL URLs http://CC_IP_ADDRESS:8080/CommandCenterWebServices/Au thenticationAndAuthorizationServicePort?wsdl http://CC_IP_ADDRESS:8080/CommandCenterWebServices/No deManagementServicePort?wsdl http(s)://CC_IP_ADDRESS:8080/CommandCenterWebServices /UserManagementServicePort?wsdl https://CC_IP_ADDRESS:8080/CommandCenterWebServices/L oggingManagementServicePort?wsdl Certificates The CC-SG's Web Services require mutual certificates such that both the CC-SG and the WS c
PAGE 9
Chapter 1: Introduction USER is the plain user name and MODULE is the name that the administrator gave the remote module configuration in CC-SG.
PAGE 10
Chapter 2 API Definitions In This Chapter Conventions ...............................................................................................6 Common Data Types .................................................................................6 System Management.................................................................................7 Authentication and Authorization Services ................................................8 Node Management Services .........................................
PAGE 11
Chapter 2: API Definitions System Management This set of services is for general CC-SG settings and information. http(s)://CC_IP_ADDRESS:8080/CommandCenterWebServices/System ManagementServicePort?wsdl Data Types SystemManagementException Exception returned for all errors specific to system management.  Elements  String code – Simple definition of the error.  String message – Specific error message. SystemInfo General information about the CC-SG.
PAGE 12
Chapter 2: API Definitions Services getSystemInfo Retrieve information about the CC-SG.  parameters   String sessionID return value  SystemInfo Authentication and Authorization Services This set of services is for logging into and out of CC-SG. http://CC_IP_ADDRESS:8080/CommandCenterWebServices/Au thenticationAndAuthorizationServicePort?wsdl Data Types AuthenticationAndAuthorizationException Exception returned for all errors specific to authentication and authorization.
PAGE 13
Chapter 2: API Definitions signoff() This operations signs off (log out) a particular user from CC-SG. The application can have multiple users logged in.   String username - user name that is logging out via the WS-API client  String sessionID return value void Unsupported Authentication and Authorization Services The following Authentication and Authorization services are not supported and should not be used.
PAGE 14
Chapter 2: API Definitions  String applicationId - CC-SG generated string which uniquely identifies the access application type within CC-SG for out-ofband access designated for use within CC-SG. String is null if not applicable to the interface.  boolean userAuthorizedForMethod - value of the authorization for the user to access this interface with this application. If the user has permission, the value is TRUE. AssociationData Represents a category based label placed on the node.
PAGE 15
Chapter 2: API Definitions  String deviceName i.e the name of the Raritan device. This field is filled in only for out-of-band interfaces; otherwise, it the empty string.  String name -  String id - Unique identifier referenced by AccessMethod  String description - User description of the interface  String type - Function of the interface NodeData Description of a node's configuration.
PAGE 16
Chapter 2: API Definitions URLObject Components to form a URL to access the CC-SG.  Elements  String protocol - the protocol used - either http or https  String port - the TCP port to be used for connecting to the interface: port 80 or port 443.  String path - the path to the actual webservice servlet  String tokenKey - the name of the property to be used for the token.
PAGE 17
Chapter 2: API Definitions Services getCCSGAppletURL This operation retrieves the full URL to the CC-SG Admin Client applet in order to launch the main CC-SG client. When this URL is opened in a browser it will display the main CC-SG client, if the sessionID is valid, or the login screen, if the sessionID is invalid.
PAGE 18
Chapter 2: API Definitions getAccessMethodsForNode This operation retrieves all the available access methods (applications) for a given node in the form of an array. Each element in the array has an indicator to denote whether the passed in username has access to particular applications.  parameters  String nodeName - name based on the configured name in CCSG.
PAGE 19
Chapter 2: API Definitions getNodeByInterfaceName Retrieves nodes by the name of the interface.   parameters  String sessionID  String interfaceName - Interface name to find (accepts wildcards _ and %) return value  NodeData[] getNodeByAssociation Find a node based on the category label applied to it.
PAGE 20
Chapter 2: API Definitions addAssociationToNode Associate the node with one or more category values   parameters  String sessionID  String nodeName - The unique name of the node to modify  AssociationData[]associations return value  boolean true on success deleteAssociationFromNode Disassociate the node from one or more category values   parameters  String sessionID  String nodeName - The unique name of the node to modify  AssociationData[]associations return value  boolean
PAGE 21
Chapter 2: API Definitions getNodePower Returns the power status of each interface of the node, including the status of the latest power operation. The user must have permission to access the node. In addition to the normal states, the availability state of each interface will be set to “Processing” if the state is pending a change because of a power operation.   parameters  String sessionID  String nodeName – Return the status of the interfaces of the node with this name.
PAGE 22
Chapter 2: API Definitions   power on  power off  power cycle  graceful shutdown  suspend  Integer sequenceInterval – The interval, in seconds, between successive operations of the specified power interfaces. Applicable to power on and power off only.  String reasonForAccess – Text used to track access by user, required when Node Auditing is enabled for the user's group.
PAGE 23
Chapter 2: API Definitions  Integer passwordExpirationPeriod – The user will have to reset their password after this many days (required if passwordExpirationEnabled is true). This value will always be clear if this feature is disabled.  boolean forcePasswordChange - When true, the user will have to change their password on the next login. When the user is first added with addUser(), forcePasswordChange will be forced to true. The value of forcePasswordChange can be modified with editUser().
PAGE 24
Chapter 2: API Definitions addUser Add a new user configuration to the CC-SG.   parameters  String sessionID  CCSGUser user – The new user's settings. return value  boolean true editUser Change an existing user's settings, excluding groups.   parameters  String sessionID  CCSGUser user – The new user's settings. return value  boolean true deleteUser Remove the user with the provided name from the CC-SG. Note: You cannot delete the SuperUser.
PAGE 25
Chapter 2: API Definitions  return value  boolean true deleteUserFromGroup Remove a user from a group to control their access of the CC-SG. Note: If this operation deletes all of a user's groups, then the user itself shall be deleted.   parameters  String sessionID  String userName - The name of the user to modify.  String[]groupName - An array of group names in which the user shall no longer be a member.
PAGE 26
Chapter 2: API Definitions  Access Audit  Access Connection  Authentication  Error  Power  Tasks  User Maintenance  String message – The message text describing the user activity.  String deviceName – The managed device the report entry corresponds to, provided for message type Access Connection.  String nodeName – The node the report entry corresponds to, provided for message type Access Connection.
PAGE 27
Chapter 2: API Definitions  String message – Specific error message. Services runReport Returns a log report formed using the request parameters. Reports created via the WS API will show up as scheduled reports with the name WS Report Task in the CC-SG Admin Client in the Administration > Tasks section. CC-SG Admin Client users can see and delete these reports. The WS system should handle deleting the tasks created using the WS API. The client should call deleteReport() for every call to runReport().
PAGE 28
Chapter 2: API Definitions  Access Audit  Access Connection  Authentication  Error  Power  Tasks  User Maintenance  String message – Restrict results to those containing this message. The only supported wildcard is the asterisk. Optional: may be null or empty.  Integer numberOfRecordsToGet – The maximum number of records to retrieve. If not specified, the service retrieves all available records, as reported by totalNumberOfRecords.
PAGE 29
Chapter 2: API Definitions deleteReport Delete a previously requested report; otherwise, reports are deleted after the user session is terminated.  parameters String sessionID   String reportID return value  boolean true Category Management This set of services is for getting and setting categories for CC-SG nodes. Data Types CategoryData Stores information about a category and its elements.
PAGE 30
Chapter 2: API Definitions addCategory Add a new category to CC-SG.   parameters  String sessionID  String name - Unique name to identify the category  boolean node - Applicable to nodes  boolean device - Applicable to devices  String type - Data type of elements: "String" or "Integer" return value  boolean true on success editCategory Facilitates changes to the editable components of a category.
PAGE 31
Chapter 2: API Definitions addElementToCategory Add one or more values to the specified category   parameters  String sessionID  String category - The unique name identifying the category  String[]elements - Each entry in this array is a value for the category. return value  boolean true on success renameElementInCategory Change the value of a category's element.
PAGE 32
Appendix A Certificate Management This appendix contains some tips on managing certificates. See the respective company's documentation for more details. In This Chapter Java keytool .............................................................................................28 OpenSSL .................................................................................................28 Saving the CCSG's Server Certificate from a Web Browser (IE6) ..........
PAGE 33
Appendix A: Certificate Management For example: https://10.0.0.101:9443/CommandCenterWebServices/Authentication AndAuthorizationServicePort?wsdl 2. A Security Alert appears. Click View Certificate. 3. Click Details then Copy to File. 4. Use the Certificate Export Wizard to save the certificate to a file. Installing the Client Certificate into a Key Store (Microsoft Windows XP) 1. Save the PKCS12 certificate file on your client computer. See Add Web Services API Client Configuration on CC-SG.
PAGE 34
Appendix B Web Services Development in Java This section focuses on CC-SG specific topics regarding WS client development in Java. In This Chapter Choose a WS Library ..............................................................................30 Certificates information for Java users ....................................................30 Setting the CCSG Address ......................................................................31 Calling a Web Service ................................................
PAGE 35
Appendix B: Web Services Development in Java Setting the CCSG Address Downloading the WSDL files from port 8080 of the CC-SG is the default source of the WSDL files, however, their contents will reflect port 8080 of your CC-SG. Further, you might wish to use your WS client with a different CC-SG or you might change the CC-SG's address. Each WSDL file contains an element like the following: PAGE 36
Appendix B: Web Services Development in Java Call the method from your application for each service object. This example uses AuthenticationAndAuthorizationService: CCSGAuthenticationAndAuthorizationService service = new CCSGAuthenticationAndAuthorizationService(); AuthenticationAndAuthorizationService service_port = service.
PAGE 37
Appendix B: Web Services Development in Java /* * RCSfile: ... * Revision: ... * Date: ... * * This source code is owned by Raritan Computer, Inc. and is confidential * and proprietary information distributed solely pursuant to a * confidentiality agreement or other confidentiality obligation. * It is intended for informational purposes only and is distributed * "as is" with no support and no warranty of any kind. * * Copyright (c) 2009 Raritan Computer, Inc. All rights reserved.
PAGE 38
Appendix B: Web Services Development in Java import node.service.webservice.bl.cc.raritan.com.CCSGNodeMan agementService; import node.service.webservice.bl.cc.raritan.com.types.*; // change server address import javax.xml.ws.Service; import javax.xml.ws.BindingProvider; import java.util.regex.Pattern; import java.util.regex.Matcher; // user input import java.io.*; public class SampleClient { public static String ccsg_address = "10.0.0.
PAGE 39
Appendix B: Web Services Development in Java public static void set_service_end_point( Service service, BindingProvider port ) { Pattern pattern = Pattern.compile( "CC_SG_" ); Matcher matcher = pattern.matcher( service.getServiceName().getLocalPart() ); String service_name = matcher.replaceFirst( "" ); if( ccsg_port.length() < 1 ) ccsg_port = "9443"; if( ccsg_address.length() > 0 ) { port.getRequestContext().put( BindingProvider.
PAGE 40
Appendix B: Web Services Development in Java System.err.println("Could not read input."); return null; } if( name.equals("") ) return null; return name; } public static void main (String[] args) { String user = "gregor"; String password = "pass123"; String session = ""; String current_name, new_name; CCSGAuthenticationAndAuthorizationService service = new CCSGAuthenticationAndAuthorizationService(); AuthenticationAndAuthorizationService port = service.
PAGE 41
Appendix B: Web Services Development in Java { session = port.signOn( user, password ); } catch ( security.service.webservice.bl.cc.raritan.com.Authent icationAndAuthorizationException ex ) { auth_exception_handler( ex, "signOn()" ); System.exit(1); } current_name = get_input( "Enter the name of the node to change: " ); new_name = get_input( "Enter the new name: " ); if( current_name != null && new_name != null ) { try { if( node_service_port.renameNode( session, current_name, new_name ) ) System.out.
PAGE 42
Appendix B: Web Services Development in Java } else System.err.println( "Could not change node name without the current and new names." ); try { port.signOff( user, session ); } catch ( security.service.webservice.bl.cc.raritan.com.
PAGE 43
Appendix C Web Services Development in C# The following sections describe how to create a Web Services client for the CCSG written in C#. This description is based on Microsoft Visual Studio 2008 and IE6 running on Windows XP. Other methods of Web Service creation are available in Visual Studio 2008, but this document solely covers services through Windows Communication Foundation (WCF) and .Net Framework Version 3.5. In This Chapter Using a CC-SG Web Service in a Project ..................................
PAGE 44
Appendix C: Web Services Development in C# 4. Set a call back for ServerCertificateValidationCallback so that the client will accept the CCSG's server certificate. A simple method is to trust the certificate if it matches the CCSG server certificate that you have explicitly saved from the CCSG. See Saving the CCSG's Server Certificate Using IE6. ServicePointManager.
PAGE 45
Appendix C: Web Services Development in C# using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Security.Cryptography.X509Certificates; using System.Net; using System.Net.Security; using System.ServiceModel; namespace CCWSClient_WCF { class Program { static string cc_address = "10.0.0.101"; static string user = "gregor"; static string password = "pass123"; static string session_id; static void quit(CCAuthentication.
PAGE 46
Appendix C: Web Services Development in C# Console.WriteLine("signOff Response: " + response.result); } catch (Exception exception) { Console.WriteLine(exception.ToString()); } } Console.WriteLine("Press a key to exit."); Console.ReadKey(true); Environment.Exit(0); } static void Main(string[] args) { ServicePointManager.ServerCertificateValidationCallba ck = delegate(Object obj, X509Certificate certificate, X509Chain chain, SslPolicyErrors errors) { X509Certificate server_certificate = X509Certificate.
PAGE 47
Appendix C: Web Services Development in C# new CCAuthentication.AuthenticationAndAuthorizationServic eClient(); auth_service.ClientCredentials.ClientCertificate.SetC ertificate( StoreLocation.CurrentUser, StoreName.My, X509FindType.FindBySubjectName, "10.0.0.150"); // service parameters CCAuthentication.signOn sign_on = new CCAuthentication.signOn(); sign_on.String_1 = user; sign_on.String_2 = password; // access the service Console.WriteLine("Connecting to: " + cc_address); try { auth_service.
PAGE 48
Appendix C: Web Services Development in C# // renameNode service CCNode.NodeManagementServiceClient node_service = new CCNode.NodeManagementServiceClient(); node_service.ClientCredentials.ClientCertificate.SetC ertificate( StoreLocation.CurrentUser, StoreName.My, X509FindType.FindBySubjectName, "10.0.0.150"); CCNode.renameNode rename = new CCNode.renameNode(); rename.String_1 = session_id; Console.Write("Name of node to change: "); rename.String_2 = Console.ReadLine(); Console.
PAGE 49
Appendix C: Web Services Development in C# } } } 45
PAGE 50
PAGE 51
Index A Access Information • 4 AccessMethod • 9 Add Web Services API Client Configuration on CC-SG • 1, 2, 29 addAssociationToNode • 16 addCategory • 26 addElementToCategory • 27 addUser • 20 addUserToGroup • 20 API Definitions • 6 AssociationData • 10 Authentication and Authorization Services • 8 AuthenticationAndAuthorizationException • 8 C Calling a Web Service • 32 Category Management • 25 CategoryData • 25 CCSGUser • 18 Certificate Management • 28 Certificates • 1, 4 Certificates information for Java
PAGE 52
Index S Sample Application for C# • 40 Sample Application for Java • 32 Saving the CCSG's Server Certificate from a Web Browser (IE6) • 28 Services • 8, 13, 19, 23, 25 setNodePower • 17 Setting the CCSG Address • 31 signoff() • 9 signOn() • 8 System Management • 7 SystemInfo • 7 SystemManagementException • 7 U Unsupported Authentication and Authorization Services • 9 URLObject • 12 User Management • 18 UserManagementException • 19 Using a CC-SG Web Service in a Project • 39 Using Microsoft Management Cons
PAGE 53
PAGE 54
U.S./Canada/Latin America Monday - Friday 8 a.m. - 6 p.m. ET Phone: 800-724-8090 or 732-764-8886 For CommandCenter NOC: Press 6, then Press 1 For CommandCenter Secure Gateway: Press 6, then Press 2 Fax: 732-764-8887 Email for CommandCenter NOC: tech-ccnoc@raritan.com Email for all other products: tech@raritan.com China Europe Europe Monday - Friday 8:30 a.m. - 5 p.m. GMT+1 CET Phone: +31-10-2844040 Email: tech.europe@raritan.com United Kingdom Monday - Friday 8:30 a.m. to 5 p.m.