Lead from the front Texas Nodal 1 Technical Communications Workshop September 03, 2008.

http://nodal.ercot.com 1Lead from the front

Texas Nodal

Technical Communications Workshop

September 03, 2008


Texas Nodal

Antitrust Admonition

ANTITRUST ADMONITION

ERCOT strictly prohibits Market Participants and their employees who are participating in ERCOT activities from using their participation in ERCOT activities as a forum for engaging in practices or communications that violate the antitrust laws. The ERCOT Board has approved guidelines for members of ERCOT Committees, Subcommittees and Working Groups to be reviewed and followed by each Market Participant attending ERCOT meetings. If you have not received a copy of these Guidelines, copies are available at the Client Relations desk. Please remember your ongoing obligation to comply with all applicable laws, including the antitrust laws.


Texas Nodal

Workshop Agenda

• Antitrust Admonition 0900 – 0910• API Sub Group Topics 0910 – 0930

– Introduction – Overview of Agenda– API Sub Group Topics

• WSDL / XSD Overview 0930 - 1015– WSDL / XSD Overview– Basic Message Structures– EIS Specification– ERCOT WSS Security

• <break> 1015 – 1030 • Setting Up a client 1030 – 1145

– Java Example– .NET Example


Texas Nodal

Workshop Agenda

• Break for Lunch (on site) 1145 – 1230 • Setting up a Listener 1230 – 1300 • Maintenance 1300 – 1320

– Management of Certificates• Participant Requested Topics 1320 - 1400

– Trades Workflow (high level)– Alerts and Notifications– Data Review– ERCOT WAN (high level)

• Follow-up items From Original Workshop Held on 9/3/08


Texas Nodal

API Sub Group Topics

• To better serve the needs of the market, we are implementing several changes:– Focus the API Subgroup on technical, developer-to-developer issues– Direct discussions about data, report and extracts, and releases to the EDS team– Track communications at the program level

• Rationale for these changes:– The EDS team is the source of truth for Nodal schedules and is equipped to manage

market questions and responses– The old process was blurring the line between functional and technical

• Functional is the “what” and includes data elements, rules, structures, and formats• Technical is the “how” and includes delivery mechanisms, authentication/authorization, and performance

• What next:– The Friday EDS calls will include the EIP update – We will maintain the Google Group until a better solution is available– We are working with ERCOT to develop a long term process and site to better

communicate this information to the market


Texas Nodal

WSDL / XSD Overview


Texas Nodal

WSDL / XSD Overview – Supporting Documentation

• Enterprise Interface Specification Document– http://nodal.ercot.com/readiness/sandbox/websvc/index.html

• WSDL & XSD Package– http://nodal.ercot.com/readiness/sandbox/documents/index.html– Nodal.wsdl

• Describes external web services. Specifies location of service and the operations exposed by the service.

– XSDs• Defines the structure of the messages


Texas Nodal

WSDL / XSD Overview – Implementation Approach

• Define Web services needed for Market Participants to request market information and initiate transactions– Leverage IEC 61968 for definition of message– Use the IEC Common Information Model (CIM) where appropriate– Loosely coupled flexible design

• Provide the means for Market Participant Systems to receive notification messages from ERCOT systems– Leverage OASIS WS-Notifications specification– Participants will have notifications pushed to their listener


Texas Nodal

WSDL / XSD Overview – Application of IEC 61968 to Web Services

• Message structures based upon IEC 61968-1 defined for the input and output of operations (i.e. request and response)

• Header used for information needed for all messages, includes key control information such as verb, noun and source

• Request structure has parameters (some required, some optional) that are appropriate for the specific operation

• Reply structure indicates success, failure and errors as appropriate

• Payloads can be strongly typed or loosely coupled from message structures, where payloads can be compressed and encoded if needed

• Messages form the body of the underlying SOAP message


Texas Nodal

WSDL / XSD Overview – Web Service Message Payloads

• Message payloads carry the data that is needed for a specific request or reply

• The noun in the message header identifies the type of the payload

• Payloads can be supplied in one of the following forms:– Any type of XML element of any

namespace (with structure typically defined by an XSD)

– An XML document that is encoded as a string, compressed and base64 encoded

– Other base64 encoded content


Texas Nodal

Nodal.wsdl (WSDL Design View in XMLSpy)

WSDL / XSD Overview – WSDL Overview


Texas Nodal

WSDL / XSD Overview – WSDL Overview – Verbs/Nouns

Nodal.wsdl – Web Services


Texas Nodal

WSDL / XSD Overview – ERCOT XML Schema files

Message.xsd Underlying Messaging XML Schema

Notification.xsd Underlying Notification XML Schema

ErcotCommonTypes.xsd All common simple and complex types used throughout

ErcotTransactions.xsd

ErcotTransactionTypes.xsd

MarketTransaction Web Services – EIS Section 3.3.1 through 3.3.15 and its supporting types

ErcotInformation.xsd

ErcotInformationTypes.xsd

MarketInfo Web Services – EIS Section 4.3.1 through 4.3.30 and its supporting types

ErcotInformation2.xsd

ErcotInformation2Types.xsd

MarketInfo Web Services – EIS Section 4.3.31 through 4.3.45 and its supporting types

ErcotOutages.xsd

ErcotOutageTypes.xsd

Outage Scheduler Schema and its supporting types

ErcotAwards.xsd

ErcotAwardTypes.xsd

MMS Awards and Obligations structure and its supporting types – both Sync and Async

ErcotForecast.xsd Wind Forecast structure

WSS200401wssecurity-secext-10.xsd

WSS200401wssecurity-utility-10.xsd

xmldsig-core-schema.xsd

WSS Security Schema supporting files

ErcotNotifications.xsd

ErcotNotificationTypes.xsd

Asynchronous Notification Structure

ErcotDisputes.xsd

ErcotDisputeTypes.xsd

Registration Disputes XML schema and its supporting types

ErcotMiscTypes.xsd

ErcotUtilities.xsd

Reports Schema and its supporting types.

ErcotModelTypes.xsd NMMS Intended – Discontinued for now – will be deleted

MMSAwardSetSchema.xsd Interim Awards retrieval technique – Discontinued – will be deleted


Texas Nodal

WSDL / XSD Overview – XSD Overview

Nodal.wsdl

Message.xsd

ErcotCommonTypes.xsd

ErcotTransactionTypes.xsd

ErcotInformationTypes.xsd

ErcotAwardTypes.xsd

ErcotDisputesTypes.xsd

ErcotOutageTypes.xsd

ErcotMiscTypes.xsd

ErcotNotificationTypes.xsd

Defined in ERCOT CIM UML Model

Loose coupling

ErcotTransactions.xsd

ErcotInformation.xsd

ErcotNotifications.xsd

ErcotOutages.xsd

ErcotUtilities.xsd

Element Definitions for Message Payloads Type Definitions used by

Element Definitions

ErcotInformation2Types.xsdErcotInformation2.xsd

ErcotAwards.xsd

ErcotDisputes.xsd


Texas Nodal

– All messages exchanged between MP and ERCOT webservices use pre-defined structure for requests and responses.

– Messages are constructed with several sections• Header• Request (Valid for RequestMessage)• Reply (Valid for ResponseMessage)• Payload

Basic Message Structure – message.xsd


Texas Nodal

– Header is required in all messages exchanged between MP and ERCOT Web Services.

Basic Message Structure – Message Header Structure


Texas Nodal

– ‘Request’ is required to be populated in the Request Xml, depending on the type of transaction submitted

(Example: Queries [Verb: get Noun: BidSet]).

Basic Message Structure – Message Request Structure


Texas Nodal

– Used in Response to indicate success, failure and error details.

Basic Message Structure – Message Reply Structure


Texas Nodal

– Payload is required depending on the type of transaction that’s being submitted.

– Payload XML needs to conform to the ERCOT XSDs

Basic Message Structure – Message Payload Structure


Texas Nodal

Basic Message Structure – Example BidSet Sequence Diagram


Texas Nodal

EIS Specification - Role of EIS Specification

• You’ll need, the WS Contract + EIS to interact with ERCOT Web Services:

Element Req?

Datatype

Description Values

startTime N datetime

Start time for schedule

Valid 5 minute interval boundary for trade date

endTime N datetime

End time for schedule

Valid 5 minute interval boundary for trade date

externalId N string External ID QSE supplied

resource K string Resource Valid resource name

combinedCycle N string Combined cycle Valid combined cycle ID

deleteTPOs N Boolean

true if 3PO for resource are to be deleted

1 or 0 (default=0)

EnergySchedule/startTime N datetime

Not Used Not Used

EnergySchedule/endTime N datetime

Not Used Not Used

EnergySchedule/TmPoint/time

Y datetime

Absolute time for start of interval

Valid time between startTime & endTime for schedule

EnergySchedule/TmPoint/ending

N datetime

Absolute time for end of interval

Valid time between startTime & endTime for schedule

EnergySchedule/TmPoint/value1

Y float Megawatts >= 0

+


Texas Nodal

EIS Specification - Role of EIS Specification – Cont.

Yields:

<BidSet xmlns="http://www.ercot.com/schema/2007-06/nodal/ews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ercot.com/schema/2007-06/nodal/ews ErcotTransactions.xsd"><tradingDate>2008-01-01</tradingDate><OutputSchedule>

<startTime>2008-01-01T00:00:00-05:00</startTime><endTime>2008-01-02T00:00:00-05:00</endTime><marketType>DAM</marketType><resource>SANDHSYD_SH2</resource><deleteTPOs>true</deleteTPOs><EnergySchedule>

<startTime>2008-01-01T00:00:00-05:00</startTime><endTime>2008-01-02T00:00:00-05:00</endTime><TmPoint>

<time>2008-01-01T00:00:00-05:00</time><ending>2008-01-02T00:00:00-05:00</ending><value1>20</value1><value2>20</value2><value3>20</value3>

</TmPoint></EnergySchedule>

</OutputSchedule></BidSet>


Texas Nodal

Input Request Message

<?xml version = "1.0" encoding = "UTF-8"?><inputMessage>

<ns0:RequestMessage xmlns:ns0 = "http://www.ercot.com/schema/2007-06/nodal/ews/message"><ns0:Header>

<ns0:Verb>create</ns0:Verb><ns0:Noun>BidSet</ns0:Noun><ns0:ReplayDetection>

<ns0:Nonce>39b2fa420b9766e06a302ccef0531e7e</ns0:Nonce><ns0:Created>2008-08-27T17:20:51.65-05:00</ns0:Created>

</ns0:ReplayDetection><ns0:Revision>1.0</ns0:Revision><ns0:Source>TEST_LOOPBACK_MBALUSA</ns0:Source><ns0:UserID>NODALTEST</ns0:UserID><ns0:MessageID>MBALUSA_TEST</ns0:MessageID>

</ns0:Header><ns0:Payload>

<BidSet xmlns = "http://www.ercot.com/schema/2007-06/nodal/ews" xmlns:xsi = ErcotTransactions.xsd"><tradingDate>2007-11-30</tradingDate><status>Open</status><mode>Normal</mode><COP>

<startTime>2007-11-30T00:00:00-06:00</startTime><endTime>2007-11-30T00:00:00-06:00</endTime><resource>PBSES_UNIT5</resource><ResourceStatus>

<startTime>2007-11-30T00:00:00-06:00</startTime><endTime>2007-11-30T23:00:00-06:00</endTime><operatingMode>ON</operatingMode>

</ResourceStatus><Limits>

<startTime>2007-11-30T00:00:00-06:00</startTime><endTime>2007-11-30T23:00:00-06:00</endTime><hsl>70.25</hsl><lsl>7</lsl><hel>80</hel><lel>10</lel>

</Limits><ASCapacity>

<startTime>2007-11-30T00:00:00-06:00</startTime><endTime>2007-11-30T23:00:00-06:00</endTime><regUp>0</regUp><regDown>0</regDown><rrs>0</rrs><nonSpin>0</nonSpin>

</ASCapacity></COP>

</BidSet></ns0:Payload>

</ns0:RequestMessage></inputMessage>


Texas Nodal

Output Response Message

<?xml version = "1.0" encoding = "UTF-8"?><outputMessage>

<ns0:ResponseMessage xmlns:SOAP-ENV = "http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns0 = "http://www.ercot.com/schema/2007-06/nodal/ews/message" xmlns:wsu = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">

<ns0:Header><ns0:Verb>reply</ns0:Verb><ns0:Noun>BidSet</ns0:Noun><ns0:ReplayDetection>

<ns0:Nonce>39b2fa420b9766e06a302ccef0531e7e</ns0:Nonce><ns0:Created>2008-08-27T17:20:51.65-05:00</ns0:Created>

</ns0:ReplayDetection><ns0:Revision>1.0</ns0:Revision><ns0:Source>ERCOT</ns0:Source><ns0:UserID>NODALTEST</ns0:UserID><ns0:MessageID>MBALUSA_TEST</ns0:MessageID>

</ns0:Header><ns0:Reply>

<ns0:ReplyCode>OK</ns0:ReplyCode><ns0:Timestamp>2008-08-27T17:21:27.78-05:00</ns0:Timestamp>

</ns0:Reply><ns0:Payload>

<ns1:BidSet xmlns:ns1 = "http://www.ercot.com/schema/2007-06/nodal/ews"><ns1:tradingDate>2007-11-30</ns1:tradingDate><ns1:status>Open</ns1:status><ns1:mode>Normal</ns1:mode><ns1:COP>

<ns1:mRID>TEST_LOOPBACK_MBALUSA.20071130.COP.PBSES_UNIT5</ns1:mRID><ns1:status>SUBMITTED</ns1:status>

</ns1:COP></ns1:BidSet>

</ns0:Payload></ns0:ResponseMessage>

</outputMessage>


Texas Nodal

EIS Specification - EIS Specification Content

2. Services Organization • 2.1. Common Message Structure• 2.2. Common Security Implementation• 2.3. Modeling and Conventions• 2.4. Delivery Approach• 2.5. Technical Interoperability• 2.6. Service Level Agreements • …

3. Market Transaction Service • 3.3.1. Three-Part Supply Offer• 3.3.2. Self-Arranged Ancillary Service Quantities• 3.3.3. Incremental and Decremental Energy Offer • 3.3.4. Ancillary Service Offer• 3.3.5. Ancillary Service Trade• 3.3.6. Capacity Trade• 3.3.7. Congestion Revenue Rights (CRR) Offer• …

4. Market Information • 4.3.1. AwardSet• 4.3.2. AwardedAS• 4.3.3. AwardedCRR• 4.3.4. AwardedEnergyBid• 4.3.8. Forecasted Load …• 4.3.9. Real-Time System Load• 4.3.10. Market Totals • 4.3.11. Market LMPs and SPPs• 4.3.12. Market MCPCs• 4.3.13. Binding Constraints• 4.3.14. SCED Violated Constraints• 4.3.15. Ancillary Service Obligation• ….

5. Notifications • 5.3.1. Notices and Alerts ***• 5.3.2. Offer and Bid Set Acceptance• 5.3.3. Offer and Bid Set Errors• 5.3.4. Confirmed and Unconfirmed Trades• 5.3.5. Energy Offer Awards ...• ….

6. Acknowledgement of Alerts• 7.2.1. Close Alert

7. Outage Scheduling Interfaces • 7.2.1. Outage Creation• 7.2.2. Outage Query• 7.2.3. Outage Update• 7.2.4. Outage Cancellation

8. Utility Interfaces • 8.2.1. Get mRID• 8.2.2. System Status• 8.2.3. Request Test Notification• 8.2.4. Change Active Notification URL

9. Reports • get Reports

10. Resource Par Transactions• 10.3.1. Generator Resource Parameters• 10.3.2. Controllable Load Resource• 10.3.3. Non Controllable Load Resource• 10.3.4. Verbal Dispatch Instruction• 10.3.5. Resource Parameters

11. Registration Interfaces • Dispute Creation


Texas Nodal

EIS Specification - EIS Specification Review Upcoming Changes

• EIS 1.15 – MMS MarketTransaction Interface Updates

• Market Types to ASObligations (DAM or SASM) • SubmitTime to the BidSet header holding Bid request receipt timestamp by ERCOT • Added Market type to the startup/shutdown instructions with possible values of HRUC, DRUC, and DAM • Added MarketType to the get AwardSet = DAM/ADJ/RTM/SASM/RUC/SCED • Update 3PO with SuMeFipFop and EocFipFop introduced in MMS4 • Added MultiHourBlock to CRR, PTP Oblig, Energy bid and Energy only Offer input tables • Added RRS_ NCLR as a new ASType for SelfArrangedAS • Modified CompetitiveConstraints structure to hold new elements CompetitivenessStatus, deleted OperatorOverwrite – consistent

with CDR Interface • Corrected the possible values for MarketType for various Award Sets. • Updated ASOffer with nonControllableLoadFlag flag • Corrected PTP Obl. MaximumPrice/price • 3.3.2 Added RRS_NCLR to the list of ASType for SelfArrangedAS • 3.3.11 - Corrected figure 47 for EnergyOfferCurve/multiHourBlock (instead of under PriceCurve) and updated the example

– MMS MarketInfo Interface Updates • BindingConstraints - Schema • LoadDistributionFactors to have name and factor only – consistent with CDR interfaces • Merged in MIS Int Specification version .37 - Market Info Nouns into the section 4 of this spec – 4.3.31 thru 4.3.45 • 4.3.26 Unit Availability: Tagged BlackStart and Available megawatts as a place holder for future use. • Added equipmentType to Dynamic Ratings and Dynamic Ratings Deviations

– OS Interface Update • DisclaimerAck & Disclaimer as required fields for OS • Enumeration to equipment Outage, Outage states. • 3 more cancellation reasons (EXP, ERR, and ROM) • Transmission Opportunity Outage, designatedResource - station and HSL as required per OS.xsd • Added notes about OS query StartTime and endTime are optional but they should not be present when an mRID is sent. • ResourceType choices: UL or LR • Updated Outage opportunity outages with opportunity duration – consistent with OS application

– Reports • Reverted back to the original external reporting interface in section 9 – adjusted with supporting MID/MIR interface

– General • Updates/added examples for all interfaces • Updated the xsd files in the appendix C


Texas Nodal

EIS Specification - EIS Specification Review Upcoming Changes (continued…)

• EIS 1.16 (Sandbox Release only)– 10.0 - Added Resource Parameter Transaction Service Section – 11.0 – Added Disputes Interfaces section

• EIS 1.17 on MMS 4 Patch 3– OS Expanded Query– AS Insufficiency Report– Alerts R1 (framework only)– 1.16 Bug Fixes

• EIS 1.18 on MMS5– Policy Mgr + New WSRB– MarketInfo Services– getReports– LTLF– Alerts R2– 1.17 Bug Fixes

• EIS 1.18 on MMS5/OS Final– Chunking– Performance tuning– Bug Fixes– MMS5 Final– Alerts R3– 1.18 Bug Fixes


Texas Nodal

ERCOT WSS Security


Texas Nodal

ERCOT WSS Security - Security Requirements

• Industry good practices– Authentication – Confidentiality-protection– Integrity-protection– Prevent Replay Attacks– Access control– Auditing and logging– Consistent availability and performance

• Business requirements with security implications – Design a solution that is simple and readily implementable– Use industry standards– Enable leveraging of existing security infrastructure– Provide origin authentication at the transaction level


Texas Nodal

ERCOT WSS Security - Security Standards

• Transport level security via

– SSL (Secure Socket Layer) / TLS (Transport Layer Security)

• Message level security via signed SOAP messages according to the Web Services Security (WSS) standards

Authentication, confidentiality and integrityprotection (transport Level)

Origin authentication and integrityprotection (message level)

SOAP Message

Signed Message

Mutually authenticatedSSL/TLS session


Texas Nodal

ERCOT WSS Security - Trust Model

• Use Verisign Trust Network (VTN) Class 3 certificates• Provide two levels of authentication

– Transport– Message

• Implementations must ensure that :– Only ERCOT brand of certificate is used– Certificate has not been revoked

Market Participant

ERCOTMarket

Participant

End Users and/or Processes



VTN Public Key Infrastructure (PKI)

Signed Message

SignedMessage

MP

-Sp

ecific

Au

the

ntic

atio

n

ER

CO

T-S

pe

cific

Au

the

ntic

atio

n

MP

-Sp

ecific

Au

the

ntic

atio

n


Texas Nodal

ERCOT WSS Security - Authentication

• Transport-level– SSL/TLS is required while data travels on the Internet– Implement mutual authentication via SSL/TLS

• SSL/TLS version MUST be at least 3.0 • The SSL/TLS cipher suite MUST include AES 128 bit for encryption• The SSL/TLS cipher suite MUST include SHA-1 for integrity protection

• Message-level– Use OASIS Web Services Security (WSS) standards

• SOAP Message Security• X.509 Token Profile• http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.

0.pdf

– Signing entities are expected to be applications/systems with appropriate certificates


Texas Nodal

ERCOT WSS Security - Preventing Replay Attacks

• Each message must include:– A timestamp as specified by WSS <wsu:timestamp>– A random number as specified by WSS <wsu:nonce>

• Clocks need not be synchronized• Typical implementation

– Reject expired messages– Cache the nonce for the expected amount of clock skew and reject

messages whose nonce is in the cache (currently set to 5 Minutes)


Texas Nodal

ERCOT WSS Security - Implementation-Specific Security Functions

• Access Control– Use authenticated identity of message producer, as determined by

the signing certificate of the SOAP message• Auditing

– At the SOAP message level– At the Front Gateway (Policy Manager)


Texas Nodal

ERCOT WSS Security - What does this mean to Market Participants?

• Market Participants MUST– Deploy SSL/TLS

• Obtain client side certificate – Certificate is issued by Verisign under the ERCOT brand

• Implement mutual authentication• Ensure minimum SSL/TLS security settings

– Secure SOAP messages• Obtain application/system signing certificate

– Certificate is issued by Verisign under the ERCOT brand• Sign all SOAP messages• Use Web Services Security Standards and its X.509 Certificate Token Profile• Message headers MUST include a timestamp and a nonce• Validate all SOAP messages

– Signature– Certificates– Revocation status of certificates– Timestamp and nonce (to prevent replay attacks)


Texas Nodal

ERCOT WSS Security - Security Summary

• Web Services Client will need at most two certificates– SSL/TLS– SOAP Message Signing

• Security rules are equally applicable to request, reply.• Some security functions are deployment specific and each MP

must determine the best method of implementation• Implementation of industry standards promotes interoperability

and flexibility


Texas Nodal

Setting Up a Client(Java)


Texas Nodal

• Software used to build example java client to invoke ERCOT external web services– Java 1.5

• http://java.sun.com/javase/downloads/index_jdk5.jsp

– Apache Axis 1.4

• http://ws.apache.org/axis/

– Apache WSS4J 1.5

• http://ws.apache.org/wss4j/

– Apache XML Security 1.4.1

• http://xml.apache.org/security/index.html

– Apache ANT 1.7.1

• http://ant.apache.org/

– KeyTool GUI 1.7

• http://www.gria.org/downloads

Disclaimer: There can be different ways to implement the client to interact with ERCOT web services using different variety of software. Associated sample java client shows one way to implement the client to interact with ERCOT’s external web services using above mentioned software. Example java client not intended for production purposes.

Setting Up a Client (Java) - Supporting Software


Texas Nodal

Setting Up a Client (Java) – Client Overview

WSDL2JAVA client.wsdd

Request XML

Nodal.wsdl

SOAP Request SOAP Response

Client Implementation

Stubs

AXISWSS4J

XML Security

client.properties

crypto.properties

keystores

KeyTool GUI


Texas Nodal

Setting Up a Client (Java) - WSDL2Java

• Apache Axis Wsdl2Java tool is used to generate stubs from Nodal.wsdl. The generated stubs will be used to invoke web services.

• Command to invoke wsdl2java is– java org.apache.axis.wsdl.WSDL2Java (WSDL_FILE_PATH)

• Above command generates the stubs in below packages. namespace defined in wsdl maps to java packages.

– com\ercot\www\schema\_2007_06\nodal\ews\message– com\ercot\www\wsdl\_2007_06\nodal\ewsConcrete– org\w3\www\_2000\_09\xmldsig– org\oasis_open\docs\www\wss\_2004\_01\oasis_200401_wss_wssecurity_utility_1_0_xsd– org\oasis_open\docs\www\wss\_2004\_01\oasis_200401_wss_wssecurity_secext_1_0_xsd

• Demo


Texas Nodal

• Sample java client uses below configuration files• client.properties

– Contains security information used for transport level security such as keystores, truststores, passwords and type information for the keystores, truststores. It also contains location of the wsdd file.

• client.wsdd

– Contains properties needed by Axis when invoking web services.

• crypto.properties– Contains properties for the certificate used for request

signatures.

Setting Up a Client (Java) - Sample Java Client


Texas Nodal

• Code snippet from sample java client

#Construct the EngineConfiguration object based on the wsdd (Web service deployment definition) file.

EngineConfiguration config = new FileProvider("WSDDFILE");

#It is this object that provides the configuration for the Web service locator.

#Construct the Web service implementation object.

NodalServiceLocator locator = new NodalServiceLocator(config);

#Set the endpoint address (default endpointURL will be the one specified in wsdl file used in wsdl2java).

#default endpoint url will be the one specified in wsdl file.

locator.setHttpEndPointEndpointAddress("END_POINT_URL");

#Get the Binding Stub from the webservice implementation object

Operations stub = locator.getHttpEndPoint();

#Construct the request object that will be used during the execution of the service.

RequestMessage request = new RequestMessage();

request = parseRequestXML("INPUT FILE");

#Invoke the service method on the binding stub

#Response object will be returned upon invoking the service method on the binding stub that was created from the locator.

ResponseMessage response;

response = stub.marketTransactions(request);

Setting Up a Client (Java) - Example


Texas Nodal

• Java Client Demo (without security configuration)

– Sample Request Message <COP>

– XSD Request XML

– Execute Java Client

– Error Message• ERCOT Requires Authentication and Authorization• Client’s (even in sandbox) must use SSL and a valid digital certificate

Setting Up a Client (Java) - Client Demo w/o Security


Texas Nodal

• Security– Keystore & Truststore

• Storage file containing keys, certificates, trusted roots.

– KeyTool GUI is used to generate keystores and truststores.– KeyTool GUI Demo

• transport keystore entries– Client Certificate

• truststore entries– Verisign Root & Intermediate Certificates

• message keystore entries– Client Certificate– ERCOT Public Key

• Sample java client uses below configuration files• client.properties


• client.wsdd– Contains properties needed by Axis when invoking web services.

• crypto.properties– Contains properties for the certificate used for request signatures.

Setting Up a Client (Java) – Implementing Security


Texas Nodal

• (Review) Sample java client uses below configuration files

• client.properties


• client.wsdd

– Contains properties needed by Axis when invoking web services.

• crypto.properties– Contains properties for the certificate used for request

signatures.

Setting Up a Client (Java) - Implementing Security


Texas Nodal

• client.properties#The location of the client keystore used for the transport level security

javax.net.ssl.keyStore=transport_keystore.jks

#The type of keystore being used.

javax.net.ssl.keyStoreType=jks

#The keystore's password

javax.net.ssl.keyStorePassword=changeit

#Location of the truststore file

javax.net.ssl.trustStore=client_truststore.jks

#truststore’s password

javax.net.ssl.trustStorePassword=changeit

#The type of truststore being used

javax.net.ssl.trustStoreType=jks

#This is the location of the Web service deployment definition file.

webservice.deployment.definition.file=client.wsdd

Setting Up a Client (Java) - Implementing Security (client.properties)

Texas Nodal

• client.wsdd<deployment xmlns="http://xml.apache.org/axis/wsdd/" xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"><transport name="http" pivot="java:org.apache.axis.transport.http.HTTPSender"/> <globalConfiguration > <requestFlow >  <handler type= "java:org.apache.ws.axis.security.WSDoAllSender" >

 <parameter name="action" value="Signature"/>  <parameter name="user" value=“<CERT_ALIAS_NAME>" />  <parameter name="passwordCallbackClass" value=“<PasswordCallBackClassName>"/> <!– keystore is defined in crypto.properties file. --> <parameter name="signaturePropFile" value="crypto.properties" /> <!– Specifies the format used by handler to insert signature into request. DirectReference causes the handler to convert the signing certificate to BinarySecurityToken element that is pit in security header --> <parameter name="signatureKeyIdentifier" value="DirectReference" />

</handler> </requestFlow> <responseFlow> <handler type= "java:org.apache.ws.axis.security.WSDoAllReceiver" > <parameter name="action" value="Signature"/> <parameter name="passwordCallbackClass" value="PWCallback"/> <parameter name="signaturePropFile" value="crypto.properties" />

<parameter name="enableSignatureConfirmation" value="false"/> </handler> </responseFlow>

</globalConfiguration ></deployment>

Setting Up a Client (Java) - Implementing Security (client.wsdd)


Texas Nodal

• crypto.properties

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin

#Type of the keystore

org.apache.ws.security.crypto.merlin.keystore.type=<KEYSTORE_TYPE>

#Client keystores password

org.apache.ws.security.crypto.merlin.keystore.password=<KEYSTORE_PASSWORD>

#Alias name of the client cert in the keystore

org.apache.ws.security.crypto.merlin.keystore.alias=<CERT_ALIAS_NAME>

#Password of the client cert in the keystore

org.apache.ws.security.crypto.merlin.alias.password=<CERT_ALIAS_PASSWORD>

#The location of the client keystore used for the signing the message

org.apache.ws.security.crypto.merlin.file=<KEYSTORE_LOCATION>

Setting Up a Client (Java) - Implementing Security (crypto.properties)


Texas Nodal

• Java Client Demo– Sample Request Message

– Execute Java Client (with security)

– Sample Response Message

Setting Up a Client (Java) - Implementing Security (client demo)


Texas Nodal

Setting Up a Client(.NET)


Texas Nodalhttp://nodal.ercot.com 51

• .Net Development Tools– Visual Studio 2005 Express

• http://www.microsoft.com/express/2005/download/default.aspx

– Web Services Enhancements (WSE) 2.0 for Microsoft .NET

• http://www.microsoft.com/downloads/details.aspx?familyid=fc5f06c5-821f-41d3-a4fe-6c7b56423841&displaylang=en

• Post Installation– Add C:\Program Files\Microsoft Visual Studio 2005\SDK\v2.0\bin to PATH

• Pre Coding– Obtain certificate from ERCOT

– Download wsdl from http://nodal.ercot.com/readiness/sandbox/websvc/index.html

– Extract to local drive

Setting Up a Client (.NET) - Supporting Software


Texas Nodal

Setting Up a Client (.NET) - Supporting Software

WSDL.exe

Request XML

Nodal.wsdl

SOAP Request SOAP Response

Client Implementation

Stubs

Visual Studio

policyCachel.config WSE

Keystore



Setting Up a Client (.NET) - Process Steps

Once you have installed the tools and downloaded the wsdl and xsds you will develop your client code by following these steps:

• Run wsdl Nodal.wsdl WSS200401wssecurity-secext-10.xsd WSS200401wssecurity-utility-10.xsd

• Open Visual Studio 2005

• Create a new console project

• Copy NodalService.cs to project folder

• Add Reference to Microsoft.Web.Services2

• Add Reference to System.Web.Services

• Edit Program.cs to make web service call.

• In NodalService.cs change System.Web.Services.Protocols.SoapHttpClientProtocol to Microsoft.Web.Services2.WebServicesClientProtocol

• Configure policy using WSE 2.0 Configurator tool



Setting Up a Client (.NET) - Demo



Setting Up a Client (.NET) - wsdl.exe

wsdl.exe• Installed as part of Visual Studio 2005

• Generates .NET client code using Nodal.wsdl

• Command to invoke wsdl.exe is

– wsdl.exe <options> <url or path> <url or path> <url or path> …

– Sample Command: wsdl Nodal.wsdl WSS200402wssecurity-secext-10.xsd WSS200401wssecurity-utility-10.xsd

– Creates: NodalService.cs

• Gotcha’s

– wsdl.exe does not resolve import so you have to specify the imported xsd using the command line parameters



• Generated code does not contain everything you need

• You will need to write code to:– Create an instance of the NodalService– Set the certificate to use digital signature– Set the message information

• Noun

• Verb

• Payload

• Etc..

– Check the response message

Setting Up a Client (.NET) - Client Code



Setting Up a Client (.NET) - Sample Code

NodalService nodalService = new NodalService();

RequestMessage requestMessage = new RequestMessage();

HeaderType header = new HeaderType();

header.Verb = HeaderTypeVerb.create;

header.Noun = "BidSet";

requestMessage.Header = header;

…

requestMessage.Payload = new PayloadType();

…

responseMsg = nodalService.MarketTransactions(requestMessage);

……



• .Net Client Demo– Sample Request Message– Run NodalWSClient.exe

• Error Message

• What Happened?– No code for digital signature….

Setting Up a Client (.NET) - .Net Demo



Setting Up a Client (.NET) - Managing Certificate

• Installing Certificate

– Save certificate file to disk

– Double click on file

– Follow prompts to add

• Windows Viewing Tools:

– Microsoft Management Console• Launch Microsoft Management Console by typing mmc from a command prompt• Select File => Add/Remove Snap In• Click on the “Add” button• Select “Certificates”• Navigate to Certificate• Double click to view certificate details• Check Valid From ….



Setting Up a Client (.NET) - WSS Configuration

• Obtain Certificate from ERCOT

• Run Configuration Tool

• Enable this project for Web Services Enhancements

• Enable Policy

• Create Security Policy

• Add Policy file to project

• Add security code …



Setting Up a Client (.NET) – Policy Cache Config

• policyCache config contains information on signing outbound message and accepting signed inbound message

• Defines which parts of the message to sign and certificate to use

• Need to modify policyCache.config file:

– Request message should only sign the body• Change

– wsp:Body() wsp:Header(wsa:To) wsp:Header(wsa:Action) wsp:Header(wsa:MessageID) wse:Timestamp()

– wsp:Body()

– Response message• Change

– wsp:Body() wsp:Header(wsa:Action) wsp:Header(wsa:FaultTo) wsp:Header(wsa:From) wsp:Header(wsa:MessageID) wsp:Header(wsa:RelatesTo) wsp:Header(wsa:ReplyTo) wsp:Header(wsa:To) wse:Timestamp()

– wsp:Body() wsp:Header(wsa:FaultTo) wsp:Header(wsa:From) wsp:Header(wsa:RelatesTo) wsp:Header(wsa:ReplyTo) wsp:Header(wsa:To)



Setting Up a Client (.NET) - Sample Code

NodalService nodalService = new NodalService();

X509Store store = new X509Store(StoreName.My, StoreLocation.CurrentUser);

store.Open(OpenFlags.ReadOnly | OpenFlags.OpenExistingOnly);

X509Certificate2Collection col = store.Certificates.Find(X509FindType.FindBySerialNumber, certSubjectString, true);

X509Certificate certificate = null;

foreach (X509Certificate cert in store.Certificates) {

if (cert.Subject.Contains(certSubjectString)) {

certificate = cert;

break;}

}

nodalService.ClientCertificates.Add(certificate);

ServicePointManager.ServerCertificateValidationCallback = TrustAllCertificateCallback;

RequestMessage requestMessage = new RequestMessage();

HeaderType header = new HeaderType();

header.Verb = HeaderTypeVerb.create;

header.Noun = "BidSet";

……



• Let’s try it again…– Sample Request Message– Run NodalWSClient.exe

Setting Up a Client (.NET) - .Net Demo


Texas Nodal

Setting Up a Listener


Texas Nodal

Setting Up a Listener - Notification Component

• Notification messages are asynchronously sent to the Market Participant listener systems, using a variation of WS-Notifications implementation, where Market Participants expose a notification web service that is invoked by ERCOT to send a notification.

• ERCOT provides the Notification message schema and abstract WSDL that MPs can use in building notification listener web service.

• MPs can setup primary & secondary Notification listener services to receive notifications from ERCOT.

• Notification component delivery mechanism– Attempts to deliver notification message to the primary listener address first – Retries to deliver to the secondary listener incase of unsuccessful delivery to

primary listener. – Sends an E-mail incase of unsuccessful delivery to both primary & secondary

notification listeners


Texas Nodal

Setting Up a Listener - Overview

Proxy Server

Notification Service

Event Source

HTTPS – Notify

(SOAP signed)

HTTPS – Acknowledge

(Unsigned)

MP Service

Event

HTTPS – Notify

(SOAP signed)

HTTPS – Acknowledge

(Unsigned)

1. ERCOT Notification Service establishes an HTTPS connection to target MP system at pre-specified URL (listen port 443) by MP

2. Notification message is signed by ERCOT using the ERCOT server certificate.

3. MP web service is invoked by ERCOT Notification service, sending the Notify message.

4. MP system validates the signature, using the ERCOT public key.

5. Notify message is consumed by the MP system

6. MP system replies with a simple, unsigned acknowledge message using the same HTTPS connection

7. ERCOT Notification service receives acknowledge message and marks the transmission as complete


Texas Nodal

Setting Up a Listener - Notification Service Security

• Notification security scheme is similar to the scheme used for other external web services

• SSL for transport layer security (server authentication)• WS Security (only SOAP signing) for message level security

(request only)

• MP’s server certificate, for transport layer security (SSL), must be issued by one of the following CAs

• Verisign• Thawte• Entrust• Equifax• Digital Signature Trust Co (DST)


Texas Nodal 68

Setting Up a Listener - Notification Listener Setup - How-To

• MP’s must get ERCOT’s public certificate in order to read & validate signature in notification request

• MP’s must get the abstract WSDL & XSD from ERCOT

(http://nodal.ercot.com/readiness/sandbox/websvc/index.html)

• MP’s are responsible for constructing the Notification listener web service, using any technologies

• MP’s must notify ERCOT of the Notification service listener addresses (primary & secondary), concrete WSDL and email address

• MP’s must set up their infrastructure to accept an https connection on port 443 from ERCOT


Texas Nodal

Setting Up a Listener - Notification Service Details

• WSDL & Schemas– Notification.xsd & Notification.wsdl


Texas Nodal


• Message Structure– Notification Request Message (Notification.xsd) structure is loosely

coupled. • Message element contains the Response Message (Message.xsd) which

contains notification message


Texas Nodal


• Response Message (Message.xsd) Structure– Response message is same as External Webservice Service

(EWS) response message schema– Noun and Verb combination are

used to identify the Notification type– Payload contains actual schema

element (ex. BidSet)


Texas Nodal

Setting Up a Listener - Example Notification Listener Setup-1

• Technology Used– Java 1.5

• http://java.sun.com/javase/downloads/index_jdk5.jsp

– Apache Axis 1.4• http://ws.apache.org/axis/

– Apache WSS4J 1.5• http://ws.apache.org/wss4j/

– Apache XML Security 1.4.1• http://xml.apache.org/security/index.html

– KeyTool GUI 1.7• http://www.gria.org/downloads


Texas Nodal


• Axis setup– Copy Axis project to webserver (Ex. tomcat’s) webapps folder

– Start web server & invoke happyaxis.jsp to validate the deployment (Ex. http://localhost:8080/axis/happyaxis.jsp for tomcat)

• WSDL2Java– To construct stub classes from WSDL

• java org.apache.axis.wsdl.WSDL2Java (WSDL_FILE_PATH)

– Copy compiled stub classes into Axis project

– Deploy service into Axis• Example

– java org.apache.axis.client.AdminClient -l http://localhost:8080/axis/services/AdminService deploy.wsdd

• <Demo to consume sample Notification Message>


Texas Nodal


• Security Setup– Enable SSL in webserver(ex. Tomcat)

• Configuration parameters– Sample security service params in deploy.wsdd

<requestFlow >

<handler type= "java:org.apache.ws.axis.security.WSDoAllReceiver" >

<parameter name="action" value="Signature"/>

<parameter name="passwordCallbackClass" value="PWCallback"/>

<parameter name="signaturePropFile" value="crypto.properties" />

<parameter name="enableSignatureConfirmation" value="false"/>

</handler>

</requestFlow>

– Crypto properties for messaging signature validation• org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin• org.apache.ws.security.crypto.merlin.keystore.type=<Type of key store> <Ex. JKS>• org.apache.ws.security.crypto.merlin.keystore.password=<Keystore password>• org.apache.ws.security.crypto.merlin.keystore.alias=<certificate alias in keystore>• org.apache.ws.security.crypto.merlin.alias.password=<certificate alias password in keystore>• org.apache.ws.security.crypto.merlin.file=<Keystore>


Texas Nodal

Maintenance


Texas Nodal

Maintenance (MPIM) – Requirements Overview

• MPIM – Market Participant Identity Management• Texas Nodal requires a level of sophistication in how it manages

the identities of external users that goes beyond the current Zonal solution. Managing user identities involves:

– Creating identities for each Market Participant’s users – Defining policies that govern how for Market Participant users access ERCOT

content– Guarding ERCOT’s content according to the access policies– Providing identity information to the component Nodal applications

• A further enhancement is to control web service access that will be provided to Market participants. This introduces further features necessary for the solution:

– Communications are Market Participant Machine to ERCOT, not Market Participant user to ERCOT, although Market Participant Machine can be made to be analogous to a user

– Requests are made based on a different messaging protocol – Frequency of requests can be much higher, implying that the certificate verification

should be done internally to maintain performance


Texas NodalAPI Subgroup04/19/23

Maintenance (MPIM) – User Access – High level


Texas Nodal

Maintenance (MPIM) – Application Access – High level


Texas Nodal

Maintenance (MPIM) – Digital Certificates

• Certificates are now administered via a self service model• API certificates are generally handled the same as user

certificates• The USA will issue and manage API certificates via the same

interface used for managing user certificates (IdM)• USA can run reports in IdM to view certificate status and

information, including the expiration date• During the certificate provisioning process in IdM the USA

selects an option which denotes the certificate as a API certificate

– The employee Id field is prefixed with ‘API_’– This prefix assists in routing the requests to the API access management tool

• Certificates are valid for only 1 year; they expire on their anniversary


Texas Nodal

Maintenance (MPIM) – API certificate re/issuance


Texas Nodal

Market ParticipantRequested Topics


Texas Nodal

Requested Topics – Trades Workflow / Market Timeline

Preparation forReal-Time Ops

Adj Period

18:00(D – 1)

60 MinutesPrior toOp Hour

QSE Deadline:Update Energy OffersSubmit HRUC Offers

Update Output SchedulesUpdate Inc/Dec Offers for DSRs

ERCOT Activity:LFC Process every 4 secs

Execute SCED every 5 minsCommunicate Instructions

& Prices

ERCOT Activity:Snapshot Inputs &

Execute HRUC

Operating Period

Operating Hour

ClockHour

T

Adjustment Period & Real-Time Operations

Real-Time Operations

QSE Deadline:Update Output Schedules for DSRs

Provide SCADA Telemetry

ERCOT Activity:Communicate

HRUC Commitments

Adjustment Period


Texas Nodal

Additional Requested Topics - Trades Workflow / Market Timeline

9/5/2008 12:00 AM 9/7/2008 12:00 AM

00:00 - 18:00Day Ahead

18:00 - 00:00Adjustment

Period

18:00 - 11:00

Each Party Must Enter Identical Trades For HE 13

11:00 - 12:00

Snapshot InputsHRUC Commitments

12:00 - 13:00Operating Hour

9/5/2008 6:00 PMAdjustment Period Opens for 9/6/08

Trade Example• PARTY A and PARTY B wish to enter an AS or Capacity trade for HE 1300 on 9/6

– Trade can be entered up to 7 days in advance

– Deadline for Trade is 1100 on 9/6/08

– Both parties must enter identical trades for trade to be confirmed

– Either Party may reject the trade before or after confirmation prior to the deadline of 1100.

– Note: For Energy Trades Only – these may be submitted up to 1430 of the following day


Texas Nodal

Additional Requested Topics - Trades Workflow / Market Timeline

• Confirmation of trades– Once a trade is submitted, a notification is sent to the counterparty

(Unconfirmed Trade notification)– Example/

• Party A Submits a trade with Party B• Party B will receive an unconfirmed trade notification• Party B Submits an identical trade• Trade is now confirmed

• Wildcard Query of Trades– Wildcard feature will allow QSE’s to query trades only supplying

one of the parties– QSE’s may query trades they submitted OR trades submitted by

another party that has them as either buyer or seller


Texas Nodal

Additional Requested Topics - Alerts and Messages

• QUESTION: Detail the difference between an ALERT and NOTIFICATION. What is ERCOT expecting from market participants regarding an ALERT that is different than a NOTIFICATION?

• “In practice” definitions:– Alerts: are higher priority (e.g. emergency conditions), but

from a technical stance are no different– Messages (aka “notifications”): Are informational or validation

communications issues from ERCOT.

• Note that these definitions are “in practice” as they apply to transactions sent from ERCOT to MP’s.


Texas Nodal

Additional Requested Topics - Alerts and Messages

• High Level Architectural Diagram of Alerts and Messages

MIS

Listener

Market Participants

Listener

MMS / Outage Scheduler

Publish

Manual Entry

Publish

Notification Service

EMS

Publish

Outage Scheduler

Market Manager

CRR


Texas Nodal

Additional Requested Topics – Market Interfaces to Obtain Data

• Interfaces Available to Market Participants for Retrieving Data– EIS (External Web Services)

• MarketInformation (direct query of data)• getReports (query to obtain list of reports types and related URLs)

– MP must use returned URL to download report via http

– MIS (Market Information System) – direct manual download– TML (Texas Market Link)– Report Explorer / piApp

• What is / will be Available on What Interfaces?– ERCOT will be working to provide a comprehensive approach to providing these

details– First Step: In 1 month ERCOT will provide a complete list of all market facing

reports.– Each month thereafter, ERCOT will either use an existing EDS Market call or

schedule special workshops to review a subset of these reports, covering,• Content of the report• How to retrieve the report and what interface will be leveraged• Samples and definitions of the structure and data (where applicable)


Texas Nodal

Additional Requested Topics – ERCOT WAN

Participant

CSU/DSU

CS

U/D

SU

CSU/DSU

CS

U/D

SU

CSU/DSU

Router

Router

Router

Router

DACSNetwork

MPLSNetwork

ERCOT Taylor

ERCOT Austin

Firewall

Firewall

3 connections to ERCOT MP Taylor (T1 connection) MP MPLS Network Taylor MP MPLS Network Austin

MPLS (Multiprotocol Label Switching) Network serve as the primary for http traffic T1 connection is primary for RTU and Voice data (back-up for all else)


Texas Nodal

Additional Requested Topics – ERCOT WAN

• 2 Methods for Resolving ERCOT addresses over the WAN1. Utilize the ERCOT DNS server by setting up all ercot.com addresses with

a forwarder to the ERCOT DNS2. Set up Zone Transfer which pushes the ERCOT updated zone file to a

local DNS server

• Managing MP Fail-Over– Local node to node node failover can use a network appliance

to provide a VIP for ERCOT to use (i.e. failovers would be invisible to ERCOT)

– Remote site site failover is still manual and requires a call over the hotline

• Refer to the Nodal Operating Guides Section 7: Telemetry and Communication for full details on the ERCOT WANURL: http://nodal.ercot.com/mktrules/noperating/cur.html


Texas Nodal

Action Items from Original Workshop on 9/3/08

• Message.xsd Compressed Element – Investigate why AXIS codegen does not produce relevant stubs for it.– Under investigation

• Nodal.wsdl - Non-compliancy – unique soap action – causes codegen errors in Apache CFX– Defined at: http://www.ws-i.org/Profiles/BasicProfile-1.1-2004-08-24.html– Investigation resulted in confirmation of this issue– The suggested change is kind of like this change:

• operation1....Name="element1" type="EWSRequest"> operaton1...Name ="element2" type="EWSResponse"> ...• operation2....Name="element1" type="EWSRequest"> operaton2...Name ="element2" type="EWSResponse"> ...

– Under investigation

• Provide documentation on certificate management– Explanation of each certificate to be used (e.g. root, intermediate, client, etc)– Direction on where / how to obtain each– Reviewing whether this will be an appendix to EIS or separate, referenced document

• Replay detection – better description of Nonce and concept– Reviewing ERCOT WSS Document and whether this can be distributed

• Post example for listener like “who am I” and “Boomerang” examples– Under investigation

• Accepting changes in EIS specification (remove tracking)– ERCOT will accept all change prior to current revision– This will be posted by 9/19/2008 to the readiness center sandbox location:

http://nodal.ercot.com/readiness/sandbox/documents/index.html – The version with full revision history will also remain available


Texas Nodal

Jar Files

• Apache Axis 1.4http://ws.apache.org/axis/

– axis.jar– commons-logging-1.0.4.jar– commons-discovery-0.2.jar– jaxrpc.jar– saaj.jar– wsdl4j-1.5.1.jar– axis-ant.jar

• Apache WSS4J 1.5http://ws.apache.org/wss4j/

– wss4j-1.5.1.jar

• Apache XML Security 1.4.1http://xml.apache.org/security/index.html

– xmlsec-1.4.1.jar– xercesImpl.jar– xalan.jar

• Javahttp://java.sun.com/javase/downloads/index_jdk5.jsp

– activation.jar– mail.jar


Texas Nodal

Certificates – Keystores – Properties : Overview

client.properties

client.wsdd

crypto.properties

KEYSTORES

Truststore

Transport Level Keystore

Message Level Keystore

CERTIFICATES

Verisign Class3 Root Certificate

Verisign Class3 Intermediate Certificate

Client Certificate

ERCOT Public Key


Texas Nodal

Certificates

• Certificates required to interact with ERCOT Web Services1. Verisign Class3 Root Certificate

(obtained from www.verisign.com)

2. Verisign Class3 Intermediate Certificate(obtained from www.verisign.com) Verisign Class3 Root and Intermediate Certificate are used to configure Transport Level Security.They are used by client program to trust the ERCOT server its interacting with.

3. Client CertificateClient Certificate is used to configure Transport Level Security and Message Level Security.At the Transport Level, it is used by client program to authenticate itself to the ERCOT server.At the Message Level, it is to digitally sign the request message sent to ERCOT Web Services.(obtained from each MP’s USA)

4. ERCOT Public KeyERCOT Public Key is used to configure Message Level Security.It is used by client program to verify the digital signature in the response message returned by ERCOT Web Services.(obtained from ERCOT Account Manager)


Texas Nodal

Certificates - Keystores

• Keystores– truststore.jks

• Verisign Class3 Root Certificate• Verisign Class3 Intermediate Certificate

– transport_keystore.jks• Client Certificate

– message_keystore.jks• Client Certificate• ERCOT Public Key


Texas Nodal

Certificates – Security Configuration

• System Properties– javax.net.ssl.keyStore = <LOCATION OF TRANSPORT LEVEL KEYSTORE>– javax.net.ssl.keyStorePassword = <PASSWORD TO ACCESS THE TRANSPORT LEVEL KEYSTORE>– javax.net.ssl.keyStoreType = <TYPE OF THE TRANSPORT LEVEL KEYSTORE>– javax.net.ssl.trustStore = <LOCATION OF THE TRUSTSTORE>– javax.net.ssl.trustStorePassword = <PASSWORD TO ACCESS THE TRUSTSTORE>– javax.net.ssl.trustStoreType = <TYPE OF THE TRUSTSTORE>

• Client WSDD Configuration Properties– <parameter name="user" value="<ALIAS OF CLIENT CERT STORED IN MESSAGE LEVEL KEYSTORE>" />– <parameter name="passwordCallbackClass" value="<PASSWORD CALL BACK CLASS>"/>

• Crypto Configuration Properties– org.apache.ws.security.crypto.merlin.keystore.type=<TYPE OF MESSAGE LEVEL KEYSTORE>– org.apache.ws.security.crypto.merlin.keystore.password=<PASSWORD TO ACCESS THE MESSAGE LEVEL

KEYSTORE>– org.apache.ws.security.crypto.merlin.keystore.alias=<ALIAS OF CLIENT CERT STORED IN MESSAGE LEVEL

KEYSTORE>– org.apache.ws.security.crypto.merlin.alias.password=<PASSWORD TO ACCESS THE CLIENT CERT STORED

IN MESSAGE LEVEL KEYSTORE>– org.apache.ws.security.crypto.merlin.file=<LOCATION OF THE MESSAGE LEVEL KEYSTORE>


Texas Nodal

• client.properties#The location of the client keystore used for the transport level security

javax.net.ssl.keyStore=transport_keystore.jks

#The type of keystore being used.

javax.net.ssl.keyStoreType=jks

#The keystore's password

javax.net.ssl.keyStorePassword=changeit

#Location of the truststore file

javax.net.ssl.trustStore=client_truststore.jks

#truststore’s password

javax.net.ssl.trustStorePassword=changeit

#The type of truststore being used

javax.net.ssl.trustStoreType=jks

#This is the location of the Web service deployment definition file.

webservice.deployment.definition.file=client.wsdd

Transport Level Security - Configuration

Texas Nodal

• client.wsdd<deployment xmlns="http://xml.apache.org/axis/wsdd/" xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"><transport name="http" pivot="java:org.apache.axis.transport.http.HTTPSender"/> <globalConfiguration > <requestFlow >  <handler type= "java:org.apache.ws.axis.security.WSDoAllSender" >

 <parameter name="action" value="Signature"/>  <parameter name="user" value=“<CERT_ALIAS_NAME>" />  <parameter name="passwordCallbackClass" value=“<PasswordCallBackClassName>"/> <!– keystore is defined in crypto.properties file. --> <parameter name="signaturePropFile" value="crypto.properties" /> <!– Specifies the format used by handler to insert signature into request. DirectReference causes the handler to convert the signing certificate to BinarySecurityToken element that is pit in security header --> <parameter name="signatureKeyIdentifier" value="DirectReference" />

</handler> </requestFlow> <responseFlow> <handler type= "java:org.apache.ws.axis.security.WSDoAllReceiver" > <parameter name="action" value="Signature"/> <parameter name="passwordCallbackClass" value="PWCallback"/> <parameter name="signaturePropFile" value="crypto.properties" />

<parameter name="enableSignatureConfirmation" value="false"/> </handler> </responseFlow>

</globalConfiguration ></deployment>

Message Level Security - Configuration


Texas Nodal

• crypto.properties

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin

#Type of the keystore

org.apache.ws.security.crypto.merlin.keystore.type=<KEYSTORE_TYPE>

#Client keystores password

org.apache.ws.security.crypto.merlin.keystore.password=<KEYSTORE_PASSWORD>

#Alias name of the client cert in the keystore

org.apache.ws.security.crypto.merlin.keystore.alias=<CERT_ALIAS_NAME>

#Password of the client cert in the keystore

org.apache.ws.security.crypto.merlin.alias.password=<CERT_ALIAS_PASSWORD>

#The location of the client keystore used for the signing the message

org.apache.ws.security.crypto.merlin.file=<KEYSTORE_LOCATION>

Message Level Security – Configuration (Continued)

Lead from the front Texas Nodal 1 Technical Communications Workshop September 03, 2008.

Documents

Transcript of Lead from the front Texas Nodal 1 Technical Communications Workshop September 03, 2008.