Home

View the IAgent 2.3.2 Users Guide

Contents

1. IAgent User s Guide Administration 20000417 035850 iagent 5355 RAW Input Data 4 20000417 035850 5355 00 00 TEST ZZ2 TP 1 ZZ TP TWO 990629 1248 U 00303 000000001 0 T GS PO CLECAPP LWC 990629 1248 000001 X 003030 5T 864 000000001 BMG 28 DTM 097 990629 124849 21 19 MIT 000000001 SG This is a test message from TP ONE to TP TWO over IAgent MSG This is a test message line 2 MSG This is a test message line 3 MSG This is a test message line 4 MSG This is a test message line 5 SG This is a test message line 6 MSG This is a test message line 7 SG This is a test message line 8 MSG This is a test message line 9 MSG This is a test message line 10 SG This is a test message line 11 MSG This is a test message line 12 MSG This is a test message line 13 MSG This is a test message line 14 MSG This is a test message line 15 SG This is a test message line 16 MSG This is a test message line 17 SG This is a test message line 18 MSG This is a test message line 19 MSG This is a test message line 20 0 5E 26 000000001 GE 1 000001 IEA 1 000000001 20000417 035850 iagent 5355 End of RAW Input Data 4 Example 30 example of Debug Data Messages 20000417 035851 iagent 5355 Certificate Verification depth 1 subject C US ST Connectic
2. ee ee 91 SUGGESTED SECURITY TOOLS ee esse esse ee ee ee ee ee ee ee nnn n n n n Re ee Re Re Re Re ee nnn e n n a uu hau ee ees 91 CERTIFICATE AND KEY 55 5 0004000 ee ee ee ee ee ee Ee ee ee I ee ER ee ee ee ee ee ee 91 OPERATING SYSTEM ISSUES esse ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee E ee E ee ee ee ee Ee ee ee ee ee ee 92 OMPA CO SS S SUE S Ge tetti AE De 92 SUGGESTED FIREWALL RUEES SET wes eI EU 92 CHAPTER 30 HOW HELP 00 Maes eet 93 SCOPE OF SUPPORT SER VICES a Ee ee Eg 93 ERY THIS FIRST pia bii ene RE 93 CONTACT LYMEWARE PRODUCT SUPPORT ee ee ee ee ee ee ee ee ee nene ER RE RR EE 94 APFENDIEES omae ES Ee 95 APPENDIX A CONFIGURATION WORKSHEETS AND 5 96 August 2003 9 version 2 3 2 IAgent User s Guide Pre
3. Example 45 Sample PEM Certificate Signing Request Example 45 shows a private key for the certificate being created in newkey pem This is the key to keep locally IMPORTANT Do not lose or let an intruder copy your local key or someone may be able to successfully impersonate you FEE BEGIN RSA PRIVATE KEY jYOTuymeQBjZFYfzlLtOzlnPj8giZ2DZ284TByqe8LevjudN96sg3HLiWIBzelL LYiqFCcW6RFO57qU5rkn6jAvrD7DGeUdNmfKoie3RisXSPC hmoWE7P9xCVPvGkx gXwOv5FtC3IPBjKiNFamlHanu44yJi92yFR5BuA jJKTLK50Y12aJHuEqTLC1J4D ch4gqsNTqeLSSyxOE2gX9 w20DhnlIuKKTjcSIuK8jNKfDArVaHedlIGM1pI5JCwoD N552yNI6qjEwBgfbgWRsu8DYbMiGsSra37Jd oJpZjOKrObOTpghHTGlwClltX7u IVfEUliBfd7m2BEUc7e71ftfHgzAjvWStCFgkYly3kg7Zh6jPALu0 DFYzmPtMZ VTft d 49NoX5R ZEM eKJXSIOCUk7ZUriFPfkRsdDdcz7AfW99rHA END RSA PRIVATE KEY T Example 46 Sample Private Key The CSR file should then be sent to the appropriate Certificate Authority approved by both trading partners local and remote in their joint implementation agreement The Certificate Authority will then provide signed certificate file with themselves as the issuers August 2003 Page 111 version 2 3 2 IAgent User s Guide Appendixes APPENDIX C SAMPLE CONFIGURATION FILES The following files may be used as samples but should not be used without modification
4. IAgent User s Guide Administration 20000417 035739 iagent 5348 Trading Partner settings 20000417 035739 iagent 5348 isaid LWC TEST cn LWC TEST 20000417 035739 iagent 5348 ip 191 168 0 10 20000417 035739 iagent 5348 stdport 1111 hipriport 2222 20000417 035739 iagent 5348 session timeout 0 20000417 035739 iagent 5348 EDI message type to TP EDI with Non repudiation signature 20000417 035739 iagent 5348 EDI message type from TP EDI with Non repudiation signature 20000417 035739 iagent 5348 Receipt message type from TP Receipt with Message Integrity digest required 20000417 035739 iagent 5348 Receipt message type to TP Receipt with Message Integrity digest required 20000417 035739 iagent 5348 Trading Partner s Active server flag 1 20000417 035739 iagent 5348 IA Standard Flavor default ECIC 12 98 20000417 035739 iagent 5348 Trading Partner settings 20000417 035739 iagent 5348 isaid TP_1 cn TP 1 20000417 035739 iagent 5348 ip 127 0 0 1 20000417 035739 iagent 5348 stdport 9001 hipriport 9011 20000417 035739 iagent 5348 session timeout 30 20000417 035739 iagent 5348 EDI message type to TP EDI with Non repudiation Signature 20000417 035739 iagent 5348 EDI message type from TP EDI with Non repudiation signature 20000417 035739 iagent 5348 Receipt message type from TP No Receipt required 20000417
5. Example 11 An example of an Integrity Receipt output message A typical Signed Receipt output message is as follows line NOT wrapped IAR 1SA 00 IAGENT 00 TEST ZZ LWC TEST AZZ LWC 7 990629 1621 U 00307 000002466 0 T 199906301200002 5 542ac34623 098790 ed987698b0 743c6a06591ca410027ed7 7 Example 12 An example of a Signed Receipt output message IA Status Output message formats The IA gent server processes generate a message starting with IAS as an IA Status message There are two types of IA Status output messages Defined and Custom Defined status messages are as defined the IA Specification test stop WAN and stop OSS is how we name them The server will log and process the message but will not pass it on to the back end system BES Custom status messages are not specifically defined and will actually be treated as a pass through by the receiving IAgent server with the bit string being ignored It is expected that the back end system will handle them August 2003 Page 51 version 2 3 2 IAgent User s Guide Administration The Defined status output message format is IAS trading partner ID command with command being any one of the following TEST Special Test Message will be logged but otherwise ignored STOP WAN Problem with peer s inbound WAN local IAgent should stop transmission to peer Trading Partner STOP OSS Problem with peer
6. SIb CBN w53J 957 xMSS CIGC DOEBB vBWia e C 0 T k 3 7 pf9MI CBMeW11M UFnZW50Il SqGSIb3DQ AUAAAGBAG d3gRb3KD6 R MIGxMOswCOYDVQOG OwGwY RldmVsb3B EJARYVC2ZVj OXsOLSHrPw huY1V lrs9v7VOyeRsIp9iJRZm KAJv7RfaVkGfMyowVAlrFH22VsrVfewriAD tcEmg HSMEgdY EWJVUZzE DVOO mBvobkh Ww K KIi HyU K sxRVAKNBS13 kD8XjcM1 DVROTBAIwADAsBglg aWNhdGUwHQYDVROO gdOAFC7 bnL1DOB MBIGA1UECBMLO29u ExRMeW11d2FyZSBD ZW50MRcwFQYDVQOD dXJpdHlAbHltZXdh hnrdajBZlstUOxn t August 2003 Example 32 An example of Debug Certificate Messages Server side Page 82 version 2 3 2 IAgent User s Guide Administration subject C US ST Connecticut O Lymeware Corporation OU Iagent development CN TP 1 Email none lymeware com issuer C US ST Connecticut L Old Lyme O Lymeware Corporation OU IAgent Data Version 3 Certificate 0x2 Not Before Serial Number Signature Algorithm md5WithRSA Issuer C US OU IAgent Development Validity Not After C US Subject development CN TP 1 1 12 Development CN LymewareDemoCA 0xc ST Connecticut CN LymewareDemoCA Dec 16 02 0 Dec 15 02 0 ST Connecticut Email none lym Encryption Email security lymeware com L Old Lyme Subject Public Key Info Public Key Algorithm
7. Example 9 An example of an EDI output message August 2003 Page 50 version 2 3 2 IAgent User s Guide Administration Receipt Output message formats The receipt output message format is identical to the receipt input message format The IA gent server processes generate raw ASCII text message with the following colon delimited fields an header as the first 4 bytes of the receipt message followed by the entire ISA segment from the original EDI message 105 bytes followed by a fixed length timestamp 15 bytes in yyyymmddhhmmssz format If the receipt is of type Integrity or Signed then another field separator a colon will follow the timestamp followed by a field identifier of for integrity or message digest or S for signed or digital signature receipts A field separator will follow the field identifier then either the digest or the digital signature in hexadecimal format A typical Basic Receipt output message is as follows line NOT wrapped IAR 1SA 00 IAGENT 00 TEST ZZ LWC TEST AZ LWC 7 990629 1621 U 00307 000002466 0 T 199906301200002 Example 10 An example of a Basic Receipt output message A typical Integrity Receipt output message is as follows line NOT wrapped AR ISA 00 IAGENT 00 TEST ZZ LWC TEST AZ LWC 7 990629 1621 U 00307 000002466 0 T 2 199906301200002 1 542ac34623 098790 ed987698b0
8. DOCUMENTATION CONVENTIONS 19 PART 1 INTRODUCTION ee ee ee ee ee 1 CHAPTER 1 INTRODUCTION TO TCIF INTERACTIVE AGENT 2 CHAPTER 2 INTRODUCTION TO THE IAGENT PRODUCT eere 5 SIMPLE INTEGRATION IS THE KEY ee esse ee ee ee ee ee ee ee ee ee ee n n 6 USER DEFINED CONNECTIVITY s e DER GR Se Ee een Ee eeu Se GE Ke Ene EER ee ee GE Ee Gee ige 7 HOW DOES IT od EE ER OE EE 7 CHAPTER 3 INTRODUCTION TO 10 CRYPTOGRAPHIC TECHNIQ E ER EE RE OE EE EE OO EN 10 CRYPTOGRAPHIC ALGORITHMS 10 MESSAGE DIGESTS a Ge Ge EE Ge De Ge eee eee 11 DIGITAL SIGNATURES cole GEGEE EE plene EE oa De Ge RE Ge EG hn hir eee 11 CERTIEICATES 2 2 Ges EE ve Ge oa ve EE ga BG Ge bab ge Ue Ge EG GE nee ive um 11 CERTIFICATE CONTENTS EE tt eti vc EE Ge De Ge EE Ge ER Tm 12 CERTIFICATE AUTHORITIES eie a ive rei ive t e Ei PT EE 12 CERTIFICATE CHAINS 12 CREATING ROOT LEVEL CA CERTIFICATE ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee
9. Example 35 An example of Debug Parsed ASN1 Messages August 2003 Page 84 version 2 3 2 IAgent User s Guide Administration 1211 d 2 hl 3 1 208 cons SET 1214 d 3 1 3 l 205 cons SEQUENCE 1217 d 4 hl 2 ls 1 prim INTEGER 00 1220 d 4 1 2 1 51 cons SEOUENCE 1222 d 5 hl 2 l 13 cons SEOUENCE 1224 d 6 hl 2 1 11 cons SET 1226 d 7 hl 2 l 9 cons SEOUENCE 1228 d 8 hl 2 ls 3 prim OBJECT countryName 1233 d 8 1 2 1 2 prim PRINTABLESTRING US 1237 4 5 hl 2 1 31 cons SEQUENCE 1239 d 6 hl 2 1 29 cons SET 1241 d 7 1 2 l 27 cons SEQUENCE 1243 d 8 hl 2 1 3 prim OBJECT organizationName 1248 d 8 1 2 l 20 prim PRINTABLESTRING Lymeware Corporation 1270 d 5 hl 2 ls 1 prim INTEGER 1273 d 4 2 ls 5 prim OBJECT SHAldigestAlgorthm 1280 d 4 hl 2 l 9 prim OBJECT rsaEncryption 1291 d 4 hl 3 1 128 prim OCTET STRING Example 36 An example of Debug Parsed ASN1 Messages continued Modulus 00 2 04 99 12 56 88 2 22 7 46 2 28 STOEI 29 68 Exponent 20000417 035852 36 a9 45 72 158 49 94 75 b5 09 el 9e d6 85 65537 1 58 94 74 93 37 20000417 035852 iagent 5348 1024 bit d7 41 20 14 25 e9 d7 39 9e
10. UNKNOWN ISAID FOUND UNKNOWN ISAID FOUND IN CERT NO ISAID FOUND IN TPFILE CANNOT CONNECT TO REMOTE SERVER CANNOT START CLIENT HANDSHAKE CANNOT WRITE SSL CLIENT CANNOT READ 551 SERVER e CANNOT FIND SUBJECTNAME IN CERT CANNOT FIND ISSUERNAME IN IA ERRM CANNOT ACCEPT CLIENT HANDSHAKE m VERIFY CLIENT CERT N IA ERRM NO CLIENT CERT SENT UNKNOWN IPADDR SENT FROM CLIENT CANNOT PARSE ASNI 55 ON MESSAGE BAD SIGNITURE FOUND OO RECEIPT BAD SIGNITURE FOUND MISMATCH N INCORRECT MESSAGE TYPE SENT FROM N N N A ERRM RECEIVED MESSAGE FROM INACTIVE TP Table 14 IAgent Error Numbers continued More details of specific errors can be found in Chapter 26 August 2003 Page 74 version 2 3 2 IAgent User s Guide Administration The Web Reporter This release of the IAgent system supports dynamic monitoring via the IAgent Web Reporter An example screen is
11. 37 CHAPTER 12 MULTIPLE TRADING PARTNER 15651755 39 CHAPTER 13 MESSAGE RECEIPT ee ee ee ee ee ee ee ee 40 CHAPTER 14 MESSAGE RECEIPT 1850 5 ee ee ee ee ee ee 42 RECEIPT MODES esee leve ient ei te eie ree EN 42 Internal Receipt Mode e d tet Re lite tede tedio e ebbe tbe teer ode te de 42 External Receipt Mode 5 cade eR E er ede Breed ive dye De rs 43 PART 4 INTEGRATION 44 CHAPTER 15 INTEGRATION API OVERVIEW 45 MODE RESTRICTIONS oasele ee dece tenete tees tes ide hoes eet eeu 46 BACK END SYSTEM BES LOCATIONS BY INTERFACE 0 8 ee ee 46 CHAPTER 16 OUTBOUND CLIENT FORMATS 47 INPUT EDI MESSAGE FORMAT ees ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee Eden e ee ee ee ee 47 RECEIPT INPUT MESSAGE FORMAT ees ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ne ee ee ee 48 IA STATUS INPUT MESSAGE FORMAT ee ese ee ee ee ee ee ee ee ee ee
12. 98 006 Issue 2 Interactive Agent Users Guide Version 2 3 2 Lymeware Corporation www lymeware com 98 006 Issue 2 Interactive Agent User s Guide Version 2 3 2 Lymeware Corporation 19 Halls Road Suite 216 Old Lyme Connecticut USA 2003 IAUG232 0011 IAgent is trademark of Lymeware Corporation ATIS and TCIF are trademarks of the Alliance for Telecommunications Industry Solutions Netscape is a registered trademark of Netscape Communications Corporation OpenSSL is copyright of the OpenSSL Organization www openssl org RSA Security 9 is a trademark of RSA Security Inc SSLeay is copyright of Eric A Young and Tim J Hudson Tibco and Rendezvous are trademarks of TIBCO Software Inc products and services mentioned in this Document are identified by trademarks or service marks of their respective companies or organizations and Lymeware Corporation disclaims any responsibility for specifying which marks are owned by which companies or organizations IAgent software is Copyright 1999 2003 Lymeware Corporation Old Lyme Connecticut USA IAgent software is a compilation of software of which Lymeware Corporation is either the copyright holder or licensee Acquisition and use of this software and related materials for any purpose requires a written license agreement from Lymeware Corporation or a written license from an organization licensed by Lymeware Corporati
13. EE ee ee ener en ee 12 CERTIFICATE MANAGEMENT Pe De deb eg ee Ped De Ee ee gee See 12 SECURE SOCKETS LAYER 5915 ans EE ES DE EE B A 13 SESSION ESTABLISHMENT ASE dente Bete Be Ge ER ER EE deb E Eg Ge eo eo ge dea de E Ge ER ee E SE Eg Ge tod cute 13 KEY EXCHANGEMETHOD sees coe ee GR eek SE Se ee SE i i ei 14 CIPHER FOR DATA TRANSFER 4 Se et eee eG a Ge ee Ge Se Ee gee Ee eta De Se EG Ee ee ge see 14 DIGESTEUNETION SE Deo Ee RS RA Re ee GR Ge SE Tee Me Re ER ade Re t 14 HANDSHAKE SEQUENCE PROTOCO a a ese 15 DATA TRANSFER eere I ee de ge Eg SS Ge Ge De ge TE Ee GR DE 15 PART 2 IAGENT INSTALLATION 16 CHAPTER 4 INSTALLATION 222 00000 17 REQUIRED DOCUMENTATION 41 166 ee ee ee ee ee ene e ene Ene nnn 17 CHAPTER 5 PRE INSTALLATION 5 5 2 004 000200000000 18 August 2003 version 2 3 2 IAgent User s Guide Preface PRE INSTALLATION TASK NSTRUCTIONS e throne ore P or oe Ve Re REEDE Ke 18 1 Completing the pre install worksheet eee eese
14. iaRVMessageType RV int length RV int priority RV string data The priority element has only two valid values 0 for standard priority and 1 for high priority delivery On input the standard client will subscribe to the Agent RV message subject name iagent tibco client message versionl 1 and process valid IAgent RV messages from any publisher If a message is found to contain the correct subject name but does not conform to the IAgent RV message layout then the message will be dropped and the message data will be lost On output the server s will attempt to publish valid IAgent RV messages to any subscribers to the Agent RV message subject name iagent tibco server message versionl 1 If any error is encountered during publication then the message will be stored as a file see Directory Interface Mode for file details in the directory tmp by default Warning If there are no active subscribers present when the message is published then the message will be lost The input outbound RV message subject name may be set with the j SUBJECTNAME or intibco SUBJECTNAME options The output inbound RV message subject name may be set with the T SUBJECTNAME or outtibco SUBJECTNAME options trading partner messages will be fed to the same input tibco subject name currently a single subscriber and will be published to the same output tibco subject name which may be one or more subscribers
15. operational alerts events and errors the IAgent processes wish to report to the operator are logged to the iagent alert log file This log should be inspected on a regular basis for any entries Debug Messages The debug level option see Chapter 9 allows multiple levels of display messages depending on the value provided The debug level value is processed as a series of masks added together For example to display parsed ASNI messages on input and output and display the Basic Debug messages the value would be 32 1 33 It is suggested that the smallest number of mask values be used to minimize the size and complexity of the output Note Use of debug messages will adversely impact IAgent system performance and is not recommended for standard production use defined Debug level masks are listed in the following table Debug Level Mask Description 1 Display Basic Debug messages 2 Display Debug SSL Handshake State messages 4 Display Debug Transaction Data messages 8 Display Debug Certificate messages 16 Display Debug ASNI messages 32 Display Parsed ASNI messages 64 Display Debug RSA Key messages 128 Display Debug Receipt messages 256 Display IA Timer messages 512 Display Internal Debug messages Table 15 Debug Level Masks Examples of all of the debug level logging display screens follow below August 2003 Page 78 version 2 3 2
16. 18 2 Acquiring root access on the target machine 18 3 Acquiring the correct software for your machine eese eese eene neret Ge 18 4 Requesting the license file isi EK ON RE Va Pee don OE EE aede WE 19 SD Hardware connectivity ISSUCS T EE 19 CHAPTER 6 PRODUCT INSTALLATION 2424222 4 20 CHAPTER 7 POST INSTALLATION TASKS 22 42 42 1 21 POST INSTALLATION TASK INSTRUCTIONS SEE perte edere ides veeg Ek ee gese eee ene 21 IL Installing the license fue teet e EE eter ento OR OR reete HE N 21 2 Installing local certificates keys see se ee ee ee Se SR SR RA Ge e 21 3 Creating the lAgent configuration file Se ee ee ee 21 4 Verifying PRNGD installation and configuration Sun Solaris versions only 2l 5 Creating the Trading Partners configuration 22 Testing Integration Connectivity esses epre nnne Se Ge GR RA etre 22 7 Testing Trading Partner Connectivity eese eene teens 22 Si Post Instalb Security Tasks s ect ee re hp NT RE RE e i det pde s 22 PART 3 IAGENT CONFIGURATION es 23 CHAPTER 8 CERTIFICATE AND KEY GENERATION AND INSTALLATION 24 CERTIFICATE AND KEY GENERATION AND ee ke Ge ee See e nennen innen inni 24 1 Sele
17. 59 ad 67 fbi 7e db 89 0x10001 iagent 5348 Pe 8f 2b 64 ads 7 5 81 9 0a 43 74 45 67 be RSA Public Key 72 50 ibus 81 86 98 ace37 41 6f 0a 34 10 4 86 41 28 12 bl 14 88 f9 40 tof 34 b5 209 9 61 8 ed 32 DEK 6f 5e 15 END of Peer RSA Public Key Example 37 An example of Debug RSA Key Messages 20000 20000 20000 20000 20000 20000 417 417 417 417 417 417 035852 035852 035852 035852 035852 035852 iage iage iage iage iagen iagen ct ct ct c Digest receipt requ No receipt required for TP 1 Basic receipt required for TP 1 ired for TP 1 Signed receipt requ ired for TP 1 Digest verified RSA digital signatu re verified August 2003 Example 38 An example of Debug Receipt Messages Page 85 version 2 3 2 IAgent User s Guide Administration 20000417 035852 iagent 5348 SSL Handshake start time 035852 20000417 035854 iagent 5348 SSL Handshake end time 035854 20000417 035855 iagent 5348 Total Handshake time 02 5 Seconds 20000417 040012 iagent 5348 Message Transport start time 040012 20000417 040013 iagent 5348 Message Transport e
18. AE AE AE E AE AE AE E AE AE AE AE AE AE FE AE AE AE AE AE FE AE AE AE AE AE FE F H EM format FE AE RR FE AE HEE RR RR H H EM format AE FE AE FE AE FE AE FE AE FE E EM format A second example of the IAgent configuration file demonstrating the Directory Interface August 2003 Page 113 version 2 3 2 IAgent User s Guide Appendixes iagent conf Copyright 5 91 xampl 5 A11 C 1999 2001 Lymeware Corporation ntri IAgent process configuration file all rights reserved S IAgent configuration file default settings anything in this file default section standard client St receipt client 54 standard server St 54 highpri server except configfile This is an example of a Directory Interface configuration file trading partner 1 iagent home opt iagent define sections for each process to use REOUIRED trading partner std client trading partner rec client trading partner std server trading partner hipri server system wide settings interface dir indir opt iagent indir outdir opt iagent outdir flag to force A LOT of logging verbose yes HEHEHE HE EEE HE EE EE EE EEE EE EE EE HH EH HH TP1 std client own private key file in pem forma key client keys privkey pem own
19. August 2003 Page 71 version 2 3 2 IAgent User s Guide Administration CHAPTER 26 IAGENT MAINTENANCE ISSUES Log Rolling The output log files iagent log iagent err and iagent alert and transaction log files trans log can be safely rolled by performing the following actions 1 Move all the log files to a new location name with the mv command 2 Send a SIGHUP to Agent process or process group identified by the iagent pia file This last step will signal all IAgent processes to close then re open all the log files and will in effect complete the prior move command It is recommended that a cron job performing the above steps be scheduled on a daily basis to insure minimal log size and allow log archiving Log File Details The IAgent system generates a single transaction log file per major process These process specific transaction logs one per major process log the final status of a transaction either inbound to the server s or outbound from client s These logs are called client 1 receipt trans log server trans log and hipri trans log The log files consist of a transaction per line in the following format date time message type ISA segment of the message source or destination IP address and port message priority and numeric transaction status The date time is the time the entry was logged in local time The message type may be any of the following Message Type
20. 61 Named Pipe API TERS IE RE EO Ie Se ebbe See tus 61 Named Pipe API Writer Example bist eerte te Ee Ce Reb e EE OE EE 61 SOCKET API CODE SAMPLES eie Iudae P p ee Ge dav descend IERI 62 Socket API Reader Example oth eet ER N OE EE EE AE EE OE 62 Socket APL Writer Examples cit e OE N OE N OR EE OE OO RE EE 63 TIBCO API CODE S AMPEES EE OE OE OE EE QM NIRE 64 Tibco API Reader Example anie KERE OR N RE EE ER gd 64 Tibco API Writer IR ine EEN EO EE ORR EE EE 65 CHAPTER 24 TESTING INTEGRATION WITH BACKEND SYSTEMS 66 PART 5 IAGENT ADMINISTRATION 67 CHAPTER 25 IAGENT OPERATIONS 5817 85 220000 0 0 0 0 68 PRODUCT STARTUP SSUES ee ee ee ee ee ee ee eene eee ee ee ee ee ee ene ee ee 68 STARTING THE IAGENT SYSTEM se ee hh hn n n 68 Starting the system in Combined Mode iiio 68 Starting the system in Standalone 69 IAGENT DEBUG STARTUDP cs0sssesesesesesesesesevecevevevesesevesesevevevevevevevevevevevevevevesevevesesevesesevevevecevesevevereveveseseveverevevenenenenens 69 LOG A
21. Agent Client Server Connect gt Hello handshake start Client Hello gt sends own certificate Client validates Server certificate with correct CA certificate if local copy exists If valid then Client sends own certificate gt Server validates Client certificate with correct certificate if local copy exists If valid then handshake completes and secures connection created Client sends IA message gt Server reads IA message Client send ends successfully gt Client closes socket connection Server detects client socket close and closes secure connection Table 3 IAgent Handshake Sequence Each Trading Partner s IA consists of two components an outbound client and an inbound server Figure 4 Real and Virtual Messaging Connections The IA Client reads an input message from a backend EDI system This message is in a raw ASC X 12 EDI format The Client processes the message reading the header also called the ISA header then the body of the EDI message Depending on the destination trading partner read in the ISA header the Client will format the correct IA message with a specific level of detail and security The Client will then connect to the destinati
22. Sample code to support the Tibco Interface is supplied in Chapter 23 Additional tibco rv examples are provided with the TIB Rendezvous product August 2003 Page 56 version 2 3 2 IAgent User s Guide Administration Tibco Installation Issues After following all Tibco supplied installation directions the following local installation tasks may be required I Acquire and install the rvd tix license file 2 Set Agent user s PATH environmental variable to include the rvd executable path 3 Set the IAgent user s LD LIBRARY PATH to include the 1ibrvd so location Note This IAgent implementation does not support either the certified messaging or fault tolerant options available in some versions of Rendezvous This implementation supports Rendezvous version 5 3 and 6 6 For more information on TIB Rendezvous concepts installation instructions and the TIB Rendezvous APIs and products available please reference the TIB Rendezvous listed in Appendix H Information on TIB Rendezvous availability and licensing may be found at www rv tibco com August 2003 Page 57 version 2 3 2 IAgent User s Guide Administration CHAPTER 22 TESTING INTEGRATION API CONFIGURATIONS Because of the IAgent input and output messages symmetric nature any BES should be able to test support for any of the Integration APIs by feeding its output data back to its own input interface as shown below Integration support testing Figure 12 Integrat
23. 81 86 59 2 9 O Lymewar Corporation Email security lymeware com Corporation OU Iagent ea 41 5b 3e ed fe 96 Be 63 2208 b6 86 56 98 41 28 12 bl 88 Ose 40 sets 37 6f fc 1b 86 34 I 0 555 82 54 86 TE 6f 52 03 0 fos 61 8 32 ZC 6f 5e 1 5 7 41 7 66 97 keyid 2E FF 6E 72 F5 0F 40 7E 3B 80 01 BA 5 65 50 7 08 nnecticut L Old Lyme O Lymeware Corporation OU IAgent Development CN LymewareDemoCA Email security lymeware com 43 08 sdo ed Taz August 2003 Example 33 example of Debug Certificate Messages Server side continued Page 83 version 2 3 2 IAgent User s Guide Administration 20000417 035850 iagent 5355 Adding IA specific ASN 1 Object Identifiers TH 20000417 035850 iagent 5355 1 3 26 01 4 1 3576 7 IA X12 eciaAscX12Edi 1 3576 8 EDIFACT eciaEdifact los3256 2Lo4 T23570 9 IA NON EDI eciaNonEdi 1 3 6 1 4 1 35706 7 1 IA EDI 1 plainEDImessage Ti DO de As 1203576 7 2 TA EDI 2 signedEDImessage 1 3 6 bea EA EDI 3 integrityEDImessage 3 6 LEAST OS 71 65 TA R 1 iaReceiptMessag 74597 5 1 iaStatusMessage 20000417 035850 iagent 53
24. 21 1998 12 3 ANSI ANSI X 12 3 1977 Data Element Dictionary January 21 1998 Table 21 National International Internet and Industry Standards used by this product concluded TIBCO Software Inc Rendezvous Installation Guide Release 5 0 September 1998 TIBCO Software TIB Rendezvous Concepts Release 5 0 September 1998 TIBCO Software Inc Rendezvous Administrator s Guide Release 5 0 September 1998 TIBCO Software Inc TIB Rendezvous C Programmer s Guide Release 5 0 September 1998 Table 22 Commercial or third party documentation used by this product or manual August 2003 Page 128 version 2 3 2 IAgent User s Guide Appendixes August 2003 Page 129 version 2 3 2
25. 98 016 These may be acquired via the Alliance for Telecommunications Industry Solutions www atis org August 2003 Page 4 version 2 3 2 IAgent User s Guide Introduction CHAPTER 2 INTRODUCTION TO THE IAGENT PRODUCT The IAgent product is Lymeware Corporation s commercial class secure messaging solution for the Telecommunications Industry The IAgent product is a conformal implementation of the TCIF ECIC Interactive Agent IA v2 which allows secure EDI transactions over relatively insecure networks via TCP IP and SSLv3 Trading Partner 1 Trading Partner 2 Secure encrypted connections EDI EDI Trane lator Trane lator Figure 2 Using an Agent system for IA trading partner communications The lAgent product supports Secured data transactions over unsecured networks including Internet using Secure Socket Layer SSLv3 protocol a de facto Internet standard developed by Netscape Sender and Receiver Trading Partner authentication identification and validation via Industry standard 509 certificates issued by a valid third party Certificate Authority Digital by both sending and receiving Trading Partners Supports current and emerging Public Key Infrastructure PKI security standards including RSA PKCS and IETF TLS and PKIX standards support Supports transaction receipts with multiple levels of validation customized by trading partner Su
26. RSA Public Key Modulus 2 007 PDC 222 46 28 ROCs 00 04 12 a2 7d 2c 37 29 68 Exponent X509v3 extensions 72 36 Wier Toz 49 d4 rsal war 1024 bit b5 85 65537 09 a9 Yes 6 LCS EG 9 9 94 93 1024 bit 97 9 41 58 74 37 X509v3 Basic Constraints 5 Netscap X509v3 Authority Key Identifier gt omment Tp 220 67 7e db 89 99 0a HEY ad 0 10001 8f 2b 64 7 50 81 Encryption 43 74 Of 67 5d OpenSSL Generated Certificate X509v3 Subject Key Identifier DE 78 62 02 49 B0 0A BC D3 5A 42 C0 81 17 ec ds Signature 6d 19 13 le 17 0 DirNam C US ST Co serial 00 Algorithm soas fe af 2b e2 bc f6 56 88 42 b6 fb 41 00 d2 Tz c8 gf fe 14 69 33 le 6a 2a MOBO md5WithRSA 2a ses idos 303 dd 1 13 0 0 86 99 45 90 54 tea T 32 0 17 1 6b 4 Of 14 f6 Encryption 9d BOS 27 as 9d S 9 50 1999 GMT 9 50 2000 GMT O Lymeware com 72 3a bd b7
27. RV_OK Enter the event loop rv_MainLoop session Example 21 Tibco API Reader Example August 2003 Page 64 version 2 3 2 IAgent User s Guide Administration Tibco API Writer Example use Rv subjectname iagent tibco client message versionl 1 IAmessage spaces 1024 for test only IAlength message IApriority 1 rvMessage spaces IAlength 4 Initialize the rv session ret rv_InitSync session die rv_InitSync ret n unless ret RV_OK load up the rvMessage ret rvmsg_Init session rvMessage strlen rvMessage die rvmsg_Init ret n unless ret RVMSG_OK Build the message to be sent using rymsg Append Add IA message length as RVMSG_INT ret rvmsg_Append session rvMessage strlen rvMessage length RVMSG_INT 2 SIAlength die rvmsg_Append ret n unless ret RVMSG_OK Add IA message priority as RVMSG_INT ret rvmsg_Append session rvMessage strlen rvMessage priority RVMSG_INT 2 SIApriority die rvmsg_Append ret n unless ret RVMSG_OK Add IA message data as RVMSG_STRING ret rvmsg_Append session rvMessage strlen rvMessage data RVMSG_STRING IAlength Amessage die rvmsg_Append ret n unless ret RVMSG_OK now send it ret rv_Send session subjectname RVMSG_RVMSG 0 rvMessage die rv_Send ret n unless ret RV_OK rv_Term session Example 22 Tib
28. US US State or Province Name full name Connecticut Locality Name eg city 1 014 Lyme Organization Name eg company Lymeware Corporation Organizational Unit Name eg section Common Name eg YOUR FODN or CN www lymeware com Email Address iagent lymeware com Pleas nter the following extra attributes to be sent with your certificate request A challenge password none Writing RSA private Key and X509 certificate request Example 43 Using gen to create a PEM Certificate Signing Request August 2003 Page 109 version 2 3 2 IAgent User s Guide Appendixes tools gen csr keyout newkey pem reqout newreq pem reqform DER nodes gen csr v1 4 generates X 509v3 certificate signing requests CSRs and RSA key pairs Copyright c 2001 Lymeware Corporation All rights reserved using OpenSSL 0 9 6b This program includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit http www OpenSSL org This program includes cryptographic software written by Eric Young eay cryptsoft com Using configuration from opt iagent request cnf Generating a 768 bit RSA private key ess PEFFE FEFFE writing new private key to newkey pem You are about to be asked to enter information that will be incorporated into your certificate request What you are about to enter is what is called a Distinguished Name or a DN There are quite a few fields
29. in IAgent IAR format see Chapter 16 and have the IAgent system deliver it to the correct trading partner This could be thought of as manual mode The IAgent system will send the input receipt to the correct trading partner The external program or process can find any response receipts from remote trading partners in the output sever API location using the same interface as the standard server No receipt generation or receipt timeout support is provided in this mode August 2003 Page 43 version 2 3 2 IAgent User s Guide Integration Part 4 Integration API Reference Part 4 of this manual contains an overview of the integration APIs and then specific details for each API s use and message format This section also includes sample code fragments and a outline for testing integration with back end systems August 2003 Page 44 version 2 3 2 IAgent User s Guide Administration CHAPTER 15 INTEGRATION OVERVIEW The IAgent system supports several different possible interface modes via the Integration APIs for both input and output The four supported integration APIs for internal message input and output transfer include the File Directory interface the Named Pipe interface the IP Socket interface and the Tibco TIB Rendezvous message bus interface These interfaces are read from and written to by a third party program or system which we call the Back end system BES BES be anything from a
30. self signed so the issuer of the certificate is the same as the subject As a result one must exercise extra care in trusting a self signed certificate The wide publication of a public key by the root authority reduces the risk in trusting this key it would be obvious if someone else publicized a key claiming to be the authority Certificate Management Establishing a Certificate Authority is a responsibility that requires a solid administrative technical and management framework Certificate Authorities not only issue certificates they also manage them that is they determine how long certificates are valid they renew them and they keep lists of certificates that have already been issued but are no longer valid Certificate Revocation Lists or CRLs Say Alice is entitled to a certificate as an employee of a company Say too that the certificate needs to be revoked when Alice leaves the company Since certificates are objects that get passed around it is impossible to tell from the certificate alone that it has been revoked When examining certificates for validity therefore it is necessary to contact the issuing Certificate Authority to check CRLs although this is not usually an automated part of the process August 2003 Page 12 version 2 3 2 IAgent User s Guide Introduction Secure Sockets Layer SSL The Secure Sockets Layer SSL protocol is a protocol layer that may be placed between a reliable connection oriented networ
31. 035739 iagent 5348 Receipt message type to TP No Receipt required 20000417 035739 iagent 5348 Trading Partner s Active server flag 1 20000417 035739 iagent 5348 IA Standard Flavor default ECIC 12 98 20000417 035740 iagent 5348 Generating temp 512 bit RSA key 20000417 035852 iagent 5348 i 3 partner i cname TP 1 strp 1 1 items in the session cache 0 client connects SSL_connect 0 client connects that finished 1 server connects SSL_accept 1 server connects that finished 0 session cache hits 0 session cache misses 0 session cache timeouts 20000417 035852 iagent 5348 ASN1_parse returned a 1 20000417 035852 iagent 5348 mk_ASN1_parse FOUND object of signedEDImessage type 20000417 035852 iagent 5348 RSA digital signature verified 20000417 035852 iagent 5348 1 3 partner il isaid TP 1 strp 1 20000417 035852 iagent 5348 receipt required for 1 20000417 035850 iagent 5355 i 4 partner il isaid TWO strp TP TWO 20000417 035850 iagent 5355 AF2ENR i2d IA EDI MSG signed returned a 1422 August 2003 Example 27 An example of Basic Debug Messages Page 79 version 2 3 2 IAgent User s Guide Administration 20000417 035850 iagent 5355 CTX is NULL
32. 5 55 CHAPTER 21 TIBCO MESSAGE API INTEGRATION eene 56 TIBCOINTEREACE MODE esee re eene its ee Ie te oem 56 TIBCOINSTAELATION ISSUES 57 CHAPTER 22 TESTING INTEGRATION API CONFIGURATIONS 58 INTEGRATION API SPECIFIC TESTING ISSUES ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee 58 Directory Interface 18565 ER en e Da e OU EFE OE Ge RE EE Ge Ge Ee EER ee ee Ra BU 58 ER TR EE EE OE EY ERR P Lee 58 Socket Int rf c iiio i teli ERO RE EE EO I ER Urat ist pns 59 Tibco Interface i creer ea i erii e E ve be e E e ERES 59 CHAPTER 23 EXAMPLE INTEGRATION API CODE 60 DIRECTORY API CODE SAMPLES ORAE dr eI EH ee ahs ee 60 Directory API Reader SE N ORE EA ORE EO ER qp Use e Dd Enna e To Ede ere EG 60 August 2003 8 version 2 3 2 IAgent User s Guide Preface Directory APL Writer Example sisisi EE ER ER p ere e E UE Le De ERR E EP RI ERREUR OE 60 NAMED PIPE CODE SAMPLES ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee nennen enn enne
33. A digital soft copy of these files may be found under opt iagent examples after installation System or lAgent configuration file A simple example of the IAgent configuration file iagent conf IAgent local process configuration file Copyright C 1999 Lymeware Corporation all rights reserved SHeader export home kobar iagent RCS iagent conf v 1 2 2000 01 24 05 47 15 kobar Exp IAgent configuration file All entries except configfile override all default settings Any arguments set on the command line will overwrite anything in this file default section this machine is the main test machine frodo trading partner LWC TEST iagent home opt iagent Define sections for each process to use REQUIRED standard client trading partner std client receipt client trading partner rec client standard server 5 1 partner std server highpri server 5 1 partner hipri server system wide settings LWC TEST std client Own private key file in PEM format key client keys LWCTkey pem Own certificate file in PEM format cert client certs LWCTce
34. Directory Interface ODIHOHNS es Vie dene RR D d PE RERO RE RU d RIO 27 Named Pipe Options s AE RE RERO dO dad OR aue 28 Socket Interface ODIO e URS Sep er a ER E EIU dn Od iudei 28 Optional Tibco Interface Options t ae eae OE a 28 ADVANCED AND SPECIAL OPTIONS SEE ENERO ir eee ero eee ern 28 TAGENT COMMAND LINE ARGUMENTS eise dees iere tort gee ese e escort repe ee se Sepie 30 DEFAULT IAGENT CONFIGURATION VALUES AND 6 5 33 CHAPTER 10 TRADING PARTNER ADMINISTRATION esse ees se se ee ee se ee ee se ee se see 34 TRADING PARTNER MAINTENANCE sies is gerek ie seges ee t ek ok de Reg eb RR RENDERE eks an3 34 ADDITION OF ANEWTRADING PARTNER 4 es se skree ese Re ie Se Ee ee th de see Ge ET EHE N 34 REMOVAL CURRENT TRADING 35 MODIFICATION OF A CURRENT TRADING 0 Ee ee Ke Ge ee See ee ee ge ee Re 35 THE TRADING PARTNER CONFIGURATION FILE ese see se ees se ee ke be ee ge see ee ede Se eke be ee See ee EEEE sene See ee ee enint Ge ee ee 35 August 2003 7 version 2 3 2 IAgent User s Guide Preface CHAPTER 11 TRADING PARTNER CONNECTIVITY eee eee nnne 37 SIMPLE T ESTING Atene ie ete rete
35. EEN EEN OE ER ON GEE KOR GE N 121 APPENDIX F PRODUCT ee ee ee nnn nnne n ee de de de ee ee ee ee 122 ASNIDUMP ESE SEE SG EG EE GE ES ued EG Ee Ge EG AS MN 122 PM UM NOU EO EE DUM GEB EE EE IE 122 ON EE EE OE EE EE RE N EE EE NE EE 122 MONITOR i Ee NE RE N EO AN 122 TEST PLu cutee ee sb Et RE 122 122 EH P 122 RR EE N OR TEER IE ER ON RO EE EE 123 APPENDIX G GLOSSARY AND ACRONYMS ke ke ee ke nnn nnn nnn nnn ee 124 APPENDIX H REFERENGCES 127 INDEX ote ient i ne Metu Ee Re ee 129 August 2003 10 version 2 3 2 List of Examples Example 1 Example 2 Example 3 Example 4 Example 5 Example 6 Example 7 Example 8 Example 9 Example 10 Example 11 Example 12 Example 13 Example 14 Example 15 Example 16 Example 17 Example 18 Example 19 Example 20 Example 21 Example 22 Example 23 Example 24 Example 25 Example 26 Example 27 Example 28 Example 29 Example 30 Example 31 Example 32 Example 33 Example 34 Example 35 Examp
36. Name eg YOUR ISA ID commonName Common Name eg Your Fully qualified domain name commonName_max 15 commonName_max 64 emailAddress Email Address emailAddress_max 40 req_attributes challengePassword A challenge password challengePassword_min 4 challengePassword_max 20 EOF August 2003 Page 119 version 2 3 2 IAgent User s Guide Appendixes APPENDIX D CONNECTIVITY TESTING Simple Trading Partner Connectivity Test Plan A simple trading partner connectivity test plan may be found on out web site at http www lymeware com download html Simple Backend Integration API Test Plan A simple backend integration API test plan may be found on out web site at http www lymeware com download html August 2003 Page 120 version 2 3 2 IAgent User s Guide Appendixes APPENDIX E EXTENDED FEATURES The following features are available as Lymeware Extensions to the TCIF 98 006 v2 Interactive Agent specification Some of these Extensions are proposed future standards and some were added just for our convenience These features will continue to be supported in future releases as much as is possible for backward compatibility Lymeware Specific Extensions Defined status input message See Chapter 16 for more information on the defined status input message format Proposed Future Standard Extensions Ping Status Messages This feature has been added to the current proposed next version of
37. RSA DES SHAI Authentication with DES encryption and RSA 3DES EDE SHAI Authentication with triple DES encryption More information on supported cipher suites can be found TCIF 98 009 of the following message types are internally sent and received in ASN 1 DER format Specific details of the DER representation may be found in the TCIF standard The following are fully supported Message types Basic EDI with Security SSL encryption only Enhanced EDI Security with message integrity support SSL encryption and digest Enhanced EDI Security with Non Repudiation includes SSL encryption and signed message integrity Receipt types receipt Basic Receipt with Security SSL encryption only Enhanced Receipt Security with message integrity support SSL encryption and digest Enhanced Receipt Security with Non Repudiation includes SSL encryption and signed message integrity Status messages e A defined TEST IA status message A defined STOP WAN IA status message A defined STOP OSS IA status message custom 32 status message Additional protocol details including required operational details and ASN 1 messages specific components of the TCIF Interactive Agent can be found in the Telecommunications Industry Forum August 2003 Page 3 version 2 3 2 IAgent User s Guide Introduction standards documents including the TCIF 98 006 and
38. a Joint Implementation Agreement JIA a sample of which is available from TCIF through the ATIS web site www atis org August 2003 Page 39 version 2 3 2 IAgent User s Guide Configuration CHAPTER 13 MESSAGE RECEIPT OVERVIEW Message receipts allow trading partners to receive positive acknowledgements of receipt of a specific message Trading partners must agree both to support receipts this is optional and not required and the version of receipt supported basic digest or signed This information should then be stored in the trading partner record in the trading partner configuration file The basic data flow of a message with receipt acknowledgement is as follows Trading Partner 1 sends a basic digest signed IA EDI message to Trading Partner 2 Trading Partner 2 receives the IA EDI message Trading Partner 2 sends a basic digest signed IA Receipt message to Trading Partner 1 Trading Partner 1 receives the IA Receipt message Message Recelpt Data Flow IARecept Message Figure 6 Message Receipt Data Flow There are currently four versions of IA receipts supported by the IAgent system They are No receipt No receipt is sent to acknowledge IA EDI message from a remote trading partner No receipt is expected or allowed for EDI messages sent to the remote trading partner Basic Receipt SSL encryption only basic receipt which consists of ISA segment of the EDI messag
39. and running prior to starting the IAgent product Sun Solaris only During the Sun Solaris install process pkgadd the prngd program was installed configured and added to the target machine s etc rc3 d scripts for automatic startup on reboot Correct operation may be tested by running the test prngd p1 utility found in opt iagent tools 5 Creating the Trading Partners configuration file Chapter 10 of this manual covers Trading Partner administration in detail 6 Testing Integration API Connectivity Chapter 22 of this manual covers Integration API connectivity testing in detail 7 Testing Trading Partner Connectivity Chapter 11 of this manual covers Trading Partner connectivity testing in detail 8 Post Install Security Tasks Chapter 29 of this manual covers Post Install security tasks and suggestions in detail August 2003 Page 22 version 2 3 2 IAgent User s Guide Configuration Part 3 Agent Configuration Part 3 of this manual contains detailed configuration information for certificate key trading partner and configuration file administration This section also covers receipt use and issues August 2003 Page 23 version 2 3 2 IAgent User s Guide Configuration CHAPTER 8 CERTIFICATE AND KEY GENERATION AND INSTALLATION Certificate and Key generation and configuration IAgent certificate and key generation and installation consists of six steps 1 Selecting a third party Certificate Authority CA
40. as a single atomic bytestream with a 2 byte header consisting of the entire message length and a 2 byte priority flag with 0 for standard delivery priority and 1 for hi delivery priority This data is either written to or read from a named pipe Named Pipe Interface Mode Detailed Message Data Format 2 byte length 2 byte priority Any Input Message Format as ASCII text header flaa Figure 10 The detailed message data format for the named pipe interface mode If the message is shorter or longer than the length value in the header than the message will not be correctly processed It is important to note that processes writing to the named pipe interface must write the entire message header and message body in a single write to insure an atomic message processes using the named pipe interface will fail 1f the specified pipe does not exist or has such file permissions as not to allow reading or writing The input outbound pipe name may be set with the b PIPENAME or inpipe PIPENAME options The output inbound pipe name may be set with the p PIPENAME or outpipe PIPENAME options trading partner messages will be fed into the same input pipe and will exit the same output pipe Sample code to support the Named Pipe Interface is supplied in Chapter 23 August 2003 Page 54 version 2 3 2 IAgent User s Guide Administration CHAPTER 20 SOCKET API INTEGRATION Socket Interface Mode The
41. atomically and to have the length portion of the message accurately reflect the size of the data portion of the message Invalid length values will cause unpredictable results and may cause problems with all further input messages Tibco Interface The tibco interface expects the input messages to be published as an RVMSG_RVMSG message type and will ignore all other message types Only the three defined fields in Chapter 21 are required optional fields can be included but will be ignored by the IAgent client processes It is required that the length portion of the message accurately reflects the size of the data portion of the message Invalid length values will cause the message to be dropped and not processed It is important to remember that if a tibco subscriber is not up and listening for the specific subject name published to that the data will be lost See Appendix D for a sample simple BES Integration API test plan August 2003 Page 59 version 2 3 2 IAgent User s Guide Administration CHAPTER 23 EXAMPLE INTEGRATION CODE SAMPLES The following code samples demonstrate how to interface to each of the supported Integration APIs examples are in Perl 5 6 0 and are only relevant fragments of working programs More information about Perl can be found at http www perl org Directory API Code Samples Directory API Reader Example DIR opt iagent dir out while 1 forever start directory read
42. certificate file in pem forma certificate authority CA file CAfile August 2003 Page 114 aE aE aE dd aE aE AE aE aE RR AE AE t t cert client_certs cert cer path to CA certificates in pem format CApath ca certs in pem format opt iagent ca certs ca cert txt version 2 3 2 override all Any arguments set on the command line will overwrite FE AE AE AE AE AE AE AE AE AE AE AE AE FE AE AE AE AE AE AE AE AE AE AE AE AE AE AE AE AE AE AE AE TE EAE RE AEH IAgent User s Guide Appendixes FEFE E EE E E E E E EH client AE AE IE E AE AE AE E FE AE AE AE AE E FE AE AE AE AE AE FE AE AE AE AE AE FE FE FEAE AE t in pem format AE aE AE E AE AE RR E AE AE E FE RR RR RR AE AE AE RR RR AE AE AE AE RR AE AE AE AE key STP1 std client own private key file in pem format key 5 1 std client key own certificate file in pem forma cert 5 std client cert path to CA certificates in pem format CApath 5 1 std client CApath certificate authority CA file CAfile 5 1 std client CAfile RR RR RR ERK H TP1 std server own private key file in pem format key standard server port stdport 9001 own certificate file hi priority server port in pem format aE aE a
43. debug 1 interface fil mode C filestpone2lwctst edi Example 25 Starting the IAgent system in standalone mode This example will start the Agent process up in Client mode mode C with the file interface supported interface file Basic debug messages will be displayed debug 1 and a single file will be processed then the process will exit bin iagent d 1 m S i dir D test dir Example 26 Another startup example This example will start the Agent process up in Server mode m 5 with the directory interface supported i dir Basic debug messages will be displayed a 1 and all output transactions will be written to the output directory D test dir The server process will continue to process transactions until killed with a TERM or KILL signal then the process will exit At this point the IAgent system may be monitored by watching all of the following log and status files iagent log iagent err iagent alert client trans log receipt trans log server trans log and hipri trans log lAgent Debug Startup A debug startup script is provided in opt iagent bin which may be used to cause all debug messages to be displayed with messages going to either 3agent logoriagent err This may be useful to use during connectivity testing with a remote IA or during testing of BES connections to the IAgent system To run the IAgent system in debug mode the following steps need t
44. ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee 48 CHAPTER 17 INBOUND SERVER FORMATS 50 EDI OUTPUT MESSAGE FORMATS ese ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ene ee 50 RECEIPT OUTPUT MESSAGE FORMATS iese ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee Ee 51 IA STATUS OUTPUT MESSAGE 58 40640400 RE ER ee ee 51 CHAPTER 18 FILE AND DIRECTORY 2 2 2 se ee ee ee ee se ee ee ee s3 HIEETINTEREACE EE EE EE RE OE OE N 53 DIRECTORY INTERFACE ES EG PISO EER SG GR SR ES ER Se SG GR Se ee UP EER Se EG ave inna ee UR DUM ER eevee EPOR Ee ee ge 53 CHAPTER 19 NAMED PIPE 2 ese ee ee ee oe ee ee ee ee oe ee ee ee ee oe ee ee ee 54 NAMED PIPE INTERFACE ee ee 54 CHAPTER 20 SOCKET API INTEGRATION 2 2 10010000000000100001000000080000 nre 55 SOCKET INTERFACE MOD
45. elements are described in the sections that follow Key Exchange Method The key exchange method defines how client and server will agree upon the shared secret symmetric cryptography key used for application data transfer SSL 2 0 uses RSA key exchange only while SSL 3 0 supports a choice of key exchange algorithms including the RSA key exchange when certificates are used and Diffie Hellman key exchange for exchanging keys without certificates and without prior communication between client and server One variable in the choice of key exchange methods is digital signatures whether or not to use them and if so what kind of signatures to use Signing with a private key provides assurance against a man in the middle attack during the information exchange used in generating the shared key Cipher for Data Transfer SSL uses the conventional cryptography algorithm symmetric cryptography described earlier for encrypting messages in a session There are eight choices including the choice to perform no encryption No encryption NULL supported by IA Protocol Stream Ciphers with 40 bit keys with 128 bit keys CBC Block Ciphers RC2 with 40 bit key DES with 40 bit key DES with 54 bit key supported by IA Protocol Triple DES with 168 bit key and supported by IA Protocol Idea M 128 bit key Here CBC refers to Cipher Block Chaining which means that a portion of the previously encrypted cipher text is used in the encryption
46. iagent aslicense dat and should be owned by root August 2003 Page 102 version 2 3 2 IAgent User s Guide Appendixes For reporting IAgent product problems Customer specific information Your Name Your Company Name Your Telephone Number Your E mail Address Your IAgent product version Your IAgent platform Any software add ons to your Agent system A detailed description of the problem The sequence of steps that led to the problem Actions you have taken to diagnose or resolve the problem This Problem Report Form may be faxed to Lymeware Corporation at 801 383 9021 or the same information may be e mailed to support lymeware com Copyright O 1999 2002 Lymeware Corporation rights reserved Permission to copy for use in IAgent installation is granted August 2003 Page 103 version 2 3 2 IAgent User s Guide Appendixes APPENDIX CERTIFICATES AND THE GEN TUTORIAL X 509 Certificates and Certificate Signing Request CSR Creation X 509 Certificates Interactive Agent IA trading partners recognize and verify the identity of peer IA trading partners with X 509 certificates But what is a certificate and what does X 509 mean Simply a certificate associates a public key half of the public private key pair with the real identity of an individual trading partner server company or other entity X 509 refers to the standard Recommendation X 509 Th
47. key A key for symmetric key cryptosystems which is used for the duration of one message or communication session TCIF Telecommunications Industry Forum Transport Layer Security TLS A protocol originally based on SSL and developed by the IETF used for secure Internet communications 2246 URL Universal Resource Locator typically a web browser address or location value verification The act of recognizing that a person or entity is who or what it claims to be X 509 Certificate A certificate as defined in 509 August 2003 Page 126 version 2 3 2 IAgent User s Guide APPENDIX H REFERENCES Appendixes Standards Standards Body Standards Title and Publication Date Identification TCIF 98 006 Issue 2 CIC Electronic Communications Interactive Agent Functional Specification TCIF 98 006 Issue 2 December 16 1998 SSLv3 Netscape The SSL Protocol Version 3 November 18 1996 Communications 2246 TLS Protocol Version 1 0 January 1999 X 200 CCITT Recommendation X 200 Reference Model of Open Systems Interconnection for CCITT Applications 1984 X 208 CCITT Recommendation X 208 Specification of Abstract Syntax Notation One ASN 1 1988 209 Recommendation 209 Specification of Basic Encoding Rules for Abstract Syntax Notation One ASN 1 1988 X 501 CCITT Recommendation X 509 The Directory Model
48. loop foreach file glob DIR open FILE file die can t read file read entire message read FILE 1IAmessage 128 1024 sleep 1 dir loop read delay Example 15 Directory Reader Example Directory Writer Example DIR opt iagent dir_in my file DIR Counter my file2 file tmp open FILE gt file2 Il die can t create write to file2 write entire IA message to file2 in single print print FILE 91 close FILE sleep 2 to avoid dup signals rename file2 file Atomic creation of new valid IA input file Example 16 Directory API Writer Example August 2003 Page 60 version 2 3 2 IAgent User s Guide Administration Named Pipe API Code Samples Named Pipe API Reader Example FIFO opt iagent iapipe next line blocks until there s a writer open FIFO lt FIFO Il die can t read FIFO read length my binary read FIFO binary 2 my IAlength unpack N binary read priority my binary read FIFO binary 2 my SIApriority unpack N binary read data read FIFO IAdata IAlength Example 17 Named Pipe API Reader Example Named Pipe API Writer Example FIFO opt iagent iapipe while 1 next line blocks until there s a reader open FIFO gt FIFO die can t wr
49. message type The Trading Partner s sending IA receipt type The Trading Partner s receiving IA receipt type The Trading Partner s IA receipt timeout and the status of the Trading Partner server It is expected that the local machine will also have a trading partner entry so at a minimum the trading partner configuration file should have two entries one local and one remote The easiest way to build a trading partner configuration file is to make a copy from the example supplied in the iagent examples directory Copy this example file to opt iagent as a new file called tpartners conf Now open the new file with your text editor of choice We will now tackle trading partner maintenance in the following sections Trading Partner Maintenance There are only three actions for trading partner maintenance Addition of a new trading partner Removal of a current trading partner and Modification of a current trading partner Each of these actions is described below It is expected that all of these actions will be made against the trading partner configuration file usually tpartners conf and will be activated upon the re starting of the IAgent system Addition of a new trading partner Adding a new trading partner is very straightforward and consists of only four steps 1 Complete a Trading Partner Configuration Worksheet as found in Appendix A 2 Copy a new section as found in the example file to the end of your tr
50. network connection used to reach the remote IA server The remote IA may be behind a firewall and the firewall may not allow access on the required ports The local IA machine may be behind a firewall and the firewall may be doing any of the following which could cause problems block ports or addresses translate source IP addresses NAT which may confuse remote firewalls or proxy requests through a proxy server Invalid Trading Partner configuration setting Issues IAgent uses the information in the Trading Partner configuration file to determine the destination of outbound IA messages Incorrect information in any of the following fields can cause this error address standard ip port hipri ip port August 2003 Page 87 version 2 3 2 IAgent User s Guide Administration Invalid EDI data IAgent reads the ISA header of the input EDI message to determine the remote Trading Partner and connection information for that partner s IA server The field of interest is 15 08 The Trading Partner Receiver ID TWO in the example below ISAAOOMAGENT 00 TEST ZZ TP 1 ZZ TP TWO 990629 1248 0 00303 000000001 0 T Example 40 Example EDI ISA Segment wrapped CANNOT FIND ISSUERNAME IN CERT This message is caused by error parsing reading the supplied Remote IA certificate CANNOT FIND SUBJECTNAME IN CERT This message is caused by error parsing reading the supplied Remote IA certificate CANNOT
51. of the current block DES refers to the Data Encryption Standard which has a number of variants including DES40 and 3DES EDE DES has recently been supplanted by AES the new NIST standard Idea is not supported by Agent but is very popular in Europe and is patented by MediaCrypt AG RC2 is a proprietary algorithm from RSA Security Digest Function The choice of digest function determines how a digest is created from a record unit SSL supports the following August 2003 Page 14 version 2 3 2 IAgent User s Guide Introduction No digest Null choice 5 128 bit hash Secure Hash Algorithm SHA 1 a 160 bit hash supported by IA Protocol The message digest is used to create a Message Authentication Code MAC which is encrypted with the message to provide integrity and to prevent against replay attacks Handshake Sequence Protocol The handshake sequence uses three protocols The SSL Handshake Protocol for performing the client and server SSL session establishment The SSL Change Cipher Spec Protocol for actually establishing agreement on the Cipher Suite for the session and The SSL Alert Protocol for conveying SSL error messages between clients and servers These protocols as well as application protocol data are encapsulated in the SSL Record Protocol An encapsulated protocol is transferred as data by the lower layer protocol which does not examine the data The encapsulated protocol has no knowledge of the u
52. signature is only good for that message it also ensures the integrity of the message since no one can change the digest and still sign it To guard against interception and reuse of the signature by an intruder at a later date the signature contains a unique sequence number This protects the bank from a fraudulent claim from Alice that she did not send the message only she could have signed it non repudiation Certificates Although Alice could have sent a private message to the bank signed it and ensured the integrity of the message she still needs to be sure that she is really communicating with the bank This means that she needs to be sure that the public key she is using corresponds to the bank s private key Similarly the bank also needs to verify that the message signature really corresponds to Alice s signature If each party has a certificate which validates the other s identity confirms the public key and is signed by a trusted agency then they both will be assured that they are communicating with whom August 2003 Page 11 version 2 3 2 IAgent User s Guide Introduction they think they are Such a trusted agency is called a Certificate Authority and certificates are used for authentication Certificate Contents A certificate associates a public key with the real identity of an entity known as the subject Information about the subject includes identifying information the distinguished name and the public key I
53. socket interface mode reads and writes all messages as a byte stream with a 4 byte header consisting of the entire message length and a 2 byte priority flag with 0 for standard delivery priority and 1 for hi delivery priority data is either written to or read from a BSD style socket the source identified with a port and the destination identified as a fully qualified IP address in the form of AAA BBB CCC DDD port On input the standard client will listen on the input port of the local IP address of the host machine Connections will be accepted in a serial fashion with each connection used only for a single message If the message is shorter or longer than the length value in the header than the message will not be correctly processed It is important to note that processes writing to the socket interface must write the entire message header and message body in a single write to insure an atomic message Socket messages consist of a four byte binary length header containing the entire length of the message a two byte binary flag containing the delivery priority and the message body containing the raw EDI message Socket Interface Detailed Message Data 4 byte length 2 byte priority Any Input Message Format as ASCII text header flag Figure 11 The detailed message data format for the socket interface mode On output the server s will attempt to connect to the specified socket IP address including port to
54. 0 August 2003 Example 41 gen_csr Configuration File Request Section Page 107 version 2 3 2 IAgent User s Guide Creating a Certificate Signing Request Appendixes The csr command is used to create a 5 10 Public Key Cryptography Standards certificate signing request It also generates an RSA key pair PKCS 1 and you may indicate the length of the RSA keys in bits with the rsakey switch The available command line options for gen req are shown in Example 41 gen csr help gen csr v1 4 genera Copyrig ht c T T for use in the OpenSSL Toolkit his program includes cryptographic asnl kludge It is tes X 509v3 certificate signing requests 2001 Lymeware Corporation using OpenSSL 0 9 6b CSRs and RSA key pairs All rights reserved his program includes software developed by the OpenSSL Project http www OpenSSL org software written now always turned on but as default PEM as default that is wrong but some CA s can be turned off with by Eric Young eay cryptsoft com unknown option help gen csr options outfile where options are reqform arg request format one of DER TXT PEM with PE reqout arg request output file stdout as default keyform arg key file format one of DER TXT PEM with P keyout arg private key output file rsakey bits generate a new RSA key of bits in size config fil
55. 1 Messages 222 2 1 1 85 An example of Debug RSA Key Messages essere GR Re enne 85 An example of Debug Receipt Messages codice udi e Ee ee EE ee dads 85 An example of LA Timer Messages eene RD eee die espe 86 Example EDI ISA Segment 88 gen csr Configuration File Request 107 Command line arguments for gen 108 Using gen csr to create a PEM Certificate Signing 22 2 2 109 xi version 2 3 2 IAgent User s Guide Preface Example 44 Using gen csr to create DER Certificate Signing Example 45 Sample PEM Certificate Signing Request essere Exdinple 46 sample Private Ke tug HAS pM o Eti der euius Pr tO Ic ER Ee August 2003 12 version 2 3 2 IAgent User s Guide Preface List of Figures Figure 1 Figure 2 Figure 3 Figure 4 Figure 5 Figure 6 Figure 7 Figure 8 Figure 9 Figure 10 Figure 11 Figure 12 Figure 13 Figure 14 Figure 15 An Interactive Agent IA system for EDI communications 2 Using IAgent system for IA trading partner communications eene 3 LAXcetit Intestatton APIS asd edo aeos dedecore ee eee qao peau 6 Real and Virtual Messaging Connections e
56. 2 Completing the certificate request worksheet 3 Creating a Certificate Signing Request file and private key file 4 Sending the Request to your chosen CA 5 Installing local certificates and keys 6 Installing local Certificate Authority certificates These tasks should be completed in order since subsequent tasks may require information from previous tasks If you encounter any problems with these tasks or instructions refer to Chapter 30 How To Get Help At a minimum a single X 509 Server certificate and private key pair is required to operate the IAgent system The signing CA Certificate from the Certificate Authority which generated your server certificate will also be required 1 Selecting a third party Certificate Authority CA Selection of a third party Certificate Authority is usually a mutual decision between trading partners It is suggested that an agreement of a list of acceptable CAs be made prior to any subsequent tasks 2 Completing the certificate request worksheet See Appendix A for a Certificate Request Worksheet and instructions for completion Once completed continue to the next task 3 Creating a Certificate Signing Request file and private key file A certificate signing request CSR must be created and sent to your chosen Certificate Authority Using your completed Certificate Request Worksheet use the included csr utility to create private keys and CSRs See Appendix B for a certificate over
57. 55 End of IA ASN 1 OIDs 4 20000417 035850 iagent 5355 Number of new ASN 1 Objects added Example 34 An example of Debug ASN1 Messages 20000417 035850 iagent 5355 ASN1 parse returned a 1 0 0 hl 4 1 1418 cons SEQUENCE 4 d 1 hl 2 ls 9 prim OBJECT signedEDImessage 15 d 1 1 4 1 1403 cons SEQUENCE 19 d 2 hl 2 ls 1 prim INTEGER 200 22 d 2 1 2 ls 7 cons SET 24 d 3 1 2 ls 5 prim OBJECT SHAldigestAlgorthm 31 d 2 1 4 1 1176 cons SEQUENCE 35 d 3 hl 2 ls 9 prim OBJECT plainEDImessage 46 d 3 hl 4 1 1161 prim OCTET STRING ISA 00 TAGENT 00 TEST ZZ2 TP 1 ZZ TP TWO 990629 1248 U 00303 000000001 0 T GS PO CLECAPP LWC 990629 1248 000001 X 003030 5T 864 000000001 BMG 28 DTM 097 990629 124849 21 19 IT 000000001 MSG This is a test message from TP ONE to TP TWO over IAgent SG This is a test message line 2 SG This is a test message line 3 MSG This is a test message line 4 SG This is a test message line 5 MSG This is a test message line 6 MSG This is a test message line 7 MSG This is a test message line 8 MSG This is a test message line 9 SG This is a test message line 10 MSG This is a test message line 11 MSG This is a test message line 12 MSG This is a test message line 13 0 5E 23 000000001 GE 1 000001 IEA 1 000000001
58. AME 1 h i nsocket SOCKET ipriport PORT 6998 nterface TYPE dir intibco ESSAGE NAME key key fil FILE mode MODE dirpolldelay stdport port off raw off NAME SECONDS 5 DEPTH 0 tmp entropy PORT 6500 lagent tibco client messag own_key pem PORT 6999 TPconfig tpartner FILENAME tpartner conf usage help off verbose off sendstatus off cert cert file FILENAM CApath PATH ca_certs CAfile FILENAME ca_cer E cert pem pem DEFAULT CHAR mode versionl 1 5 Table 7 Default IAgent configuration values August 2003 Page 33 version 2 3 2 IAgent User s Guide Configuration CHAPTER 10 TRADING PARTNER ADMINISTRATION The IAgent system communicates only with other remote IA systems that have a trading partner identity defined within the IAgent system An identity is defined when a matching trading partner record exists A trading partner record consists of the following The Trading Partner ID The Trading Partner Common Name CN The Trading Partner s server IP address The Trading Partner s standard port The Trading Partner s hi priority port The Trading Partner s SSL session cache timeout The Trading Partner s sending IA message type The Trading Partner s receiving IA
59. DI Integrity with digest EDI message SIGNED EDI Signed with digital signature EDI message ja message to tp IA EDI Message Type to send to this Trading Partner May be any of the following BASIC EDI Basic EDI message INTEGRITY EDI Integrity with digest EDI message SIGNED EDI Signed with digital signature EDI message ja receipt from tp IA Receipt Type supported from this trading partner May be any of the following NO RECEIPT No receipt required or supported BASIC RECEIPT Basic receipt required INTEGRITY RECEIPT Integrity receipt with digest required SIGNED RECEIPT Signed receipt with digital signature required Note the SIGNED RECEIPT receipt type is only supported for a Signed EDI message type ja receipt to tp IA Receipt Type to send to this trading partner May be any of the following NO RECEIPT No receipt required or supported BASIC RECEIPT Basic receipt required INTEGRITY RECEIPT Integrity receipt with digest required SIGNED RECEIPT Signed receipt with digital signature required Note the SIGNED RECEIPT receipt type is only supported for a Signed EDI message type receipt timeout time to wait in seconds for a receipt response before logging an error and removing pending receipt entry If 0 then no timeout This will only work if the ReceiptMode is set to internal Server status initial state of this trading partner s IA s
60. E ae AE aE RR aE aE AE AE AE AE RR IR RR E AE RR aE aE RR RR cert TP1 std client cert path to CA certificates in pem format CApath 5 1 std client CApath certificate authority CA file CAfile 6 std client CAfile EEEE hipri server format AE aE AE aE AE HE aE a HEE AE aE aaa hipriport 9011 own private key file in pem format key STP1 std client key own certificate file in pem format cert 5 std client cert path to CA certificates in pem format CApath 5 1 std client CApath certificate authority CA file CAfile STP1 std client CAfile TETSESETETETETE EOF iagent conf egl August 2003 Page 115 version 2 3 2 IAgent User s Guide Appendixes August 2003 Page 116 version 2 3 2 IAgent User s Guide Appendixes Trading Partner configuration file This is an example of a typical trading partner configuration file IAgent tpartner conf Trading Partner configuration file 5 home iagent tp one RCS tpartner conf v 1 2 2000 07 03 21 25 32 5 Iagent example Trading Partner configuration file This is mostly being used for client side lookups during sending of EDI requests over SSL default section trading partners LWC
61. EC in ISA segment Trading Partner Common Name CN Trading Partner s IA Server IP Address Trading Partner s Standard Priority Port Trading Partner s High Priority Port Trading Partner s SSL Session Timeout in seconds Trading Partner s sending IA message type Trading Partner s receiving IA message type Trading Partner s sending IA receipt type Trading Partner s receiving IA receipt type Trading Partner s IA Server status Maintenance information Date added to IAgent configuration Added by who This information should be saved after being added to the Agent trading partner configuration file Copyright 1999 2002 Lymeware Corporation rights reserved Permission to copy for use in Agent installation is granted August 2003 Page 100 version 2 3 2 IAgent User s Guide Appendixes For requesting a valid commercial server certificate Customer specific information Full Company Name Street Address City State Zip Contact Person Contact Phone Number Contact FAX Number Contact E mail Address Certificate specific information Target Machine Hostname Common Name CN Organization Name O Organizational Unit Name OU Locality city State or Province Name Country Name C Certificate Authority specific information CA Contact in
62. GENERATE EDI MSG FILE This message can be caused by system resource problems file permission errors or an existing duplicate file CANNOT GENERATE IA STATUS MSG This message can be caused by system resource problems file permission errors or an existing duplicate file CANNOT GENERATE RECEIPT This message can be caused by system resource problems file permission errors or an existing duplicate file CANNOT OPEN OUTPUT FILE This message can be caused by system resource problems file permission errors or an existing duplicate file CANNOT PARSE ASN1 This message can be caused by invalid or incomplete IA messages from remote trading partners There are known problems with specific versions of specific ILEC IA systems This error can also be caused by an IA version issue mis match e g IA Issue 2 is not compatible with IA Issue 3 CANNOT READ OWN CERT This message can be caused by system resource problems file permission errors or a missing or misnamed file August 2003 Page 88 version 2 3 2 IAgent User s Guide Administration CANNOT READ OWN KEY This message can be caused by system resource problems file permission errors or a missing or misnamed file CANNOT READ SSL SERVER CANNOT REMOVE PENDING RECEIPT This message can be caused by system resource problems file permission errors or a missing or misnamed receipt file This may also be caused by a malformed pending receipt file CANNOT SAVE EDI MSG FILE This message c
63. IA systems At this time the IAgent Connectivity Worksheet see Appendix A should be completed This may require information and assistance of network or LAN personnel Note The IAgent product expects at a minimum a direct network TCP IP connection to a peer IA machine firewall or router and does not support proxy servers or services Also at this time any required connectivity installation of hardware circuits and connections should be completed provisioned and tested prior to IAgent installation August 2003 Page 19 version 2 3 2 IAgent User s Guide Installation CHAPTER 6 PRODUCT INSTALLATION The actual installation of the IAgent product should take no more than one hour The target machine should not be in general use and may have to be re booted after installation depending on the target machine s operating system Please refer to the platform specific INSTALL file 43nstall txt in the Agent distribution for your specific platform and environment specific installation instructions The specific tasks in the INSTALL file should be completed in order since subsequent tasks may require information from previous tasks If you encounter any problems with these tasks or instructions refer to Chapter 30 How To Get Help NOTE If you are upgrading from a previous version of IAgent please complete the following steps prior to installation Shutdown the current IAgent system 2 Copy all configuration files and any oth
64. IEA 1 000000001 Example 1 An example of an EDI Input message August 2003 Page 47 version 2 3 2 IAgent User s Guide Administration A typical ISA segment is as follows line NOT wrapped Note the ISA segment consists of fixed size fields with a sum of 105 bytes ISA 00 IAGENT 00 TEST ZZ LWC 7 ZZ LWC TEST 990629 1248 U 00307 000002317 0 T Example 2 An example of a typical ISA EDI Segment Receipt input message format The IA gent client process expects to find an as the first 4 bytes of the receipt message followed by the entire ISA segment from the original EDI message 105 bytes then a single field separator colon followed fixed length timestamp 15 bytes in yyyymmddhhmmssz format If the receipt is of type Integrity or Signed then another field separator colon will follow the timestamp followed by a field identifier of for integrity or message digest or 5 for signed or digital signature receipts A field separator must follow the field identifier then either the digest or the digital signature in hexadecimal format The sender ID in the ISA segment determines the Destination Trading Partner The IAgent client will use the appropriate Trading Partner setting to determine the IA Receipt message destination format to convert the input message into Basic Integrity or Signed A typi
65. IPT BAD SIGNITURE FOUND RECEIPT INTEGRITY BROKEN RECEIVED MESSAGE FROM INACTIVE TP TP ID MISSING FROM INPUT IA STATUS MSG UNKNOWN IPADDR SENT FROM CLIENT UNKNOWN ISAID FOUND UNKNOWN ISAID FOUND IN CERT UNKNOWN MSG TYPE IN TPFILE UNKNOWN RECEIPT MSG TYPE IN TPFILE UNKNOWN TYPE OF MSG FOR TP UNSUPPORTED INPUT MSG FOUND UNSUPPORTED MESSAGE TYPE August 2003 Page 90 version 2 3 2 IAgent User s Guide Administration CHAPTER 29 SECURITY ISSUES Post Installation Security Tasks Re Run tripwire and store the tripwire database to an external device floppy tape Make a final full system backup and reinstall from the backup to test it Run Satan Saint or another security configuration verification tool and fix what insecure network configurations are discovered General Security Suggestions Limit the application software installed on the IAgent machine Disable all unnecessary port services as found in etc services Disable all BSD r utilities several can be replaced with more secure alternate open source versions Replace RPC services with RPC Bind Insure that both bind and sendmail are running the latest versions available for the current operating system The newest versions have significantly more security than past versions Do not allow SNMP SMTP HTTP IMAP or POP access from outside of the local LAN Do add a firewall between the IAgent machine and the outside connections Configure the firewall using the sugge
66. ISA segment and all its fields to be mandatory even if empty and of fixed length We suggest using a newline ASCII 0x0a as a segment terminator makes viewing data easier for the rest of us The IAgent client will use the appropriate Trading Partner setting to determine the IA EDI destination message format Basic Integrity or Signed and convert the input EDI message to the correct format A typical input EDI message 15 as follows lines NOT wrapped ISA 00 IAGENT 00 TEST NAAT Pl 227 TWO 990629 1248 U 00303 000000001 0 T GS PO CLECAPP LWC 990629 1248 000001 X 003030 5T 864 000000001 BMG 28 DTM 097 990629 124849 21 19 IT 000000001 SG This is a test message from TP ONE to TP TWO over IAgent SG This is a test message line 2 SG This is a test message line 3 SG This is a test message line 4 SG This is a test message line 5 SG This is a test message line 6 SG This is a test message line 7 MSG This is a test message line 8 SG This is a test message line 9 SG This is a test message line 10 SG This is a test message line 11 SG This is a test message line 12 SG This is a test message line 13 SG This is a test message line 14 SG This is a test message line 15 SG This is a test message line 16 SG This is a test message line 17 MSG This is a test message line 18 SG This is a test message line 19 0 5E 25 000000001 GE 1 000001
67. ND OUTPUT 70 CHAPTER 26 IAGENT MAINTENANCE ISSUES ese 72 UU 72 TOG FILE DETAILS RE EE EE EE OVER DUERME I ed OE EE OE EN 72 THE WEB 75 CHAPTER 27 TROUBLESHOOTING PROBLEMS AND ERRORS cmm 77 FAMED TRANSACTIONS aito iei vedi emite x vedi e 78 5 lt EE 78 TAGENTALERT 85 655 2 55 Ue eee eb eei vele 78 DEBUG MESSAGES 4 iiie idus mee ee GE ER Ge DR 78 CHAPTER 28 PRODUCT ERROR MESSAGES 87 29 SECURITY ISSUES 91 POST INSTALLATION SECURITY 5 8 000000 0 0 ee ee ee ee ee ee ee 91 GENERAL SECURITY SUGGESTIONS ee ee ee ee ee ee ee ee ee ene ee ee ee ee ee ee ee ee
68. NNOT SAVE IASTATUS OUT FILE 27 CANNOT PENDING 26 CANNOT GENERATE 25 CANNOT SAVE RECEIPT PIPE 24 CANNOT WRITE TIBCO EDI MSG 23 CANNOT WRITE EDI MSG TO SOCKET 22 CANNOT WRITE EDI MSG TO PIPE 21 NO PENDING FOUND 20 ID MISSING FROM INPUT STATUS 5 19 ISA SEG MISSING FROM INPUT RECEIPT MSG 18 CANNOT GENERATE IA STATUS MSG 17 CLIENTS CERTS MISSING 16 CLIENTS OWN CERT MISSING 15 IA CANNOT SAVE RECEIPT OUT FILE 14 CANNOT SAVE EDI MSG FILE 13 CANNOT OPEN OUTPUT FILE 12 CANNOT WRITE OUTPUT FILE 11 UNSUPPORTED MESSAGE 10 CANNOT EDI MSG FILE 9 UNKNOWN MSG IN TPFILE 8 UNKNOWN RECEIPT MSG TYPE TPFILE 7 UNKNOWN MSG FOR 6 CANNOT 5 CANNOT SSLCTX 4 CANNOT CLIENT SOCKET 3 CANNOT READ OWN CERT 2 IA ERRM CANNOT READ OWN KEY 1 SUCCESSFUL TRANSMISSION 0 Table 13 IAgent Error Numbers August 2003 Page 73 version 2 3 2 IAgent User s Guide Administration UNSUPPORTED INPUT MSG FOUND
69. ON FILE ese ese ees ee se ee ee ee ee ee ee Ge ee ee GR Re ee Ee Re ee Ge ee 112 TRADING PARTNER CONFIGURATION FILE ese ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee 117 GEN CSR REQUEST CONF CONFIGURATION FILE see ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee eterne gens sess ee ee Re 119 APPENDIX D CONNECTIVITY TESTING 2 120 SIMPLE TRADING PARTNER CONNECTIVITY TEST PLAN ee esse sesse ee ee ee ee ee ee 120 SIMPLE BACKEND INTEGRATION API 5 00 0 0 06 00 6 6 nnn ee Re 120 APPENDIX E EXTENDED 8 2 000000 ee ee ee ee ee ee ee ee ee ee 121 LYMEWARE SPECIFIC EXTENSIONS ese see ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee 121 Defined status input MeSSA RE EE ra EE RA OE EN 121 PROPOSED FUTURE STANDARD EXTENSIONS 1 ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee Ene ee ee 121 TA Ping Status ESE RE RE AE N
70. TES iagent dir T 1 2 opt iagent E Each of the trading partners above should have its own section below Each trading partner section should contain the following list of fields partner id as found in the EDI ISA segment 15 chars max as per X 12 certificate common name as found in the client certificate 64 chars max ip address as string AAA BBB CCC DDD standard ip port partner s standard IA server IP port address same IP address as above hipri ip port partner s hi priority IA server IP port address same IP address as above Session timeout session cache timeout in seconds if 0 then no resumable cached sessions ia message to tp IA EDI Message Type supported as input by Trading Partner May be any of the following BASIC EDI INTEGRITY EDI SIGNED EDI ia message from tp IA EDI Message Type accepted from this Trading Partner May be any of the following BASIC EDI INTEGRITY EDI SIGNED EDI ia receipt to tp IA Receipt Type required as input by this Trading Partner May be any of the following NO RECEIPT no receipt required BASIC RECEIPT INTEGRITY RECEIPT SIGNED RECEIPT August 2003 Page 117 version 2 3 2 IAgent User s Guide Appendixes ia receipt from tp IA Receipt Type accepted from this Trading Partner May be any of the following RECEIPT no rec
71. TIFICA DCCA2GgAwIBAgIB FDASBgNVBAgTCONvbm51Y3 HltZXdhcmU 9029 3YXJ1 DVOOG lIENv YXJ nOxDTALBgNVBAMUBF MAOGCSqG ASZbAkaWMordDqsNxIc7 p7p137nZ7db IidLHlGFdY5nt hFSlozsaTN6Q SAq801pC fNjwoYG3 ETAPBgNV bjEbMBkG ZUR1DW9D MAOGCSqG 2yeijgqG WwO5vcB6v9vvI 91 asHTkLgh OdPg END CER TIFICAT RpY3VOM cG THltZzXdhc lymewar U IAgent D R kiG9wOBAQOFA EwDwYDVQOH Rpb24xGzAZBgNVBASTI DCBsT com issuer ng Clie EL whPbGOgTHltZzTl 1BZ2VudCB depth 0 subject C US ST Connecticut L Old Email security lymeware com t 5348 SSL accept SSLv3 read client certificate A EBUG Getti nt s certificate AKGA1UEBhMCVV AMBSGA1U EZXZlbG9w U J LmNvbTAeF EWJVUZEUM c ROXZzExI IDADOEBA RJcdam5G tbX S wO50OT 1 NBvcmFOaW9UuMRSwGOYDVOOLI kqhkiG9wOBCOQ UAAAGNADCBiOKBgODiNrXXQSCPO3LqmCgO EDMoiK DAeBg Q 2dkD71Bb7l mVEZW1vQOEx DAiBg hkiG9wOBCOEWFXNI EyMTYwMjA5NTBaFwOwM LQ29ubmVj DEyMTUwMjA5 dGljdXOxHTAbBgNV YWdlbnQgZGV2ZWxv EW5vbmVAbHltZzXdh ReE YE G kObywoSYXu7I K3OIDAQABOAIBPTCCATkwCQY HxYdT3BlblNTTCBHZWS5lcmFOZWQgQ2VydGl m wIHm5OF7Z
72. The trading partners using the IA for connectivity with either a direct connection frame relay ATM etc or a public data network the Internet the AXIS network etc have no built in delays and will support near real time transaction processing Trading Partner 1 Trading Partner 2 IP Connection Ha wark Secure encrypted connections Figure 1 An Interactive Agent IA system for EDI communications The IA design provides Secured data transactions over unsecured networks including Internet using Secure Socket Layer SSLv3 protocol a de facto Internet standard developed by Netscape Sender and Receiver Trading Partner authentication identification and validation via Industry standard 509 certificates issued by a valid third party Certificate Authority Digital by both sending and receiving Trading Partners August 2003 Page 2 version 2 3 2 IAgent User s Guide Introduction Supports current and emerging Public Key Infrastructure security standards including RSA PKCS and IETF PKIX standards support Supports transaction receipts with multiple levels of validation customized by trading partner e Supports multiple levels of message validation on each transaction customized by trading partner The following cipher suites are supported by the IA standard RSA Basic authentication without encryption
73. Type Number UNSUPPORTED BASIC EDI INTEGRITY EDI SIGNED EDI BASIC RECEIPT INTEGRITY RECEIPT SIGNED RECEIPT STATUS OOM By Go oO Table 12 Transaction Log Message Type Numbers The ISA segment of the message should be the first 105 bytes of a raw EDI or Receipt message For IA Status messages this field is populated with the status bit string in four hexadecimal numbers The source or destination IP address and port will reflect the other side of the exchange In the server s it should be the transaction s source IP address In clients s it should reflect the destination IP address of the transaction August 2003 Page 72 version 2 3 2 IAgent User s Guide Administration The message type 15 the delivery priority of the inbound or outbound message and may either of the following STANDARD PRIORITY z0 HI PRIORITY 1 The numeric transaction status is the final disposition of the transaction Zero 0 means successful transaction with negative numbers reflecting an internal error condition and positive numbers an external error condition The following table contains all available transaction error status codes for the current release Transaction Error Status Code Description Value IA CANNOT SAVE IASTATUS TO PIPE 28 CA
74. ace specific options Input Socket Port Output Socket IP Address and Port Tibco Interface specific options Input Subject Name Output Subject Name Advanced options Receipt Mode internal or external Resumable Session Cache Size Source of entropy filename Trading Partner Configuration File Will allow any type of message from any Trading Partner Sloppy Allow Will allow messages from inactive Trading Partner Sloppy Inactive Will allow duplicate receipts and duplicate BES messages Ignore Duplicate Receipts Send IA Status messages to Remote trading Partners on error Send Status Copyright 1999 2002 Lymeware Corporation rights reserved Permission to copy for use in IAgent installation is granted August 2003 Page 99 version 2 3 2 IAgent User s Guide Appendixes is worksheet is to be used for each local and remote trading partner to be supported by the IAgent system Fill this out before generating modifying the trading partner configuration file Valid field values will be found in Chapter 10 of the Agent s User s Guide Trading Partner Company specific information Full Company Name Street Address City State Zip Contact Person Contact Phone Number Contact FAX Number Contact E mail Address Trading Partner specific information Local Trading Partner ID as CLEC in ISA segment Remote Trading Partner ID as IL
75. achesize ENTRIES Server session cache size in session entries receiptmode MODE Receipt mode supported May b ither internal or external config FILENAME IAgent configuration file name default is iagent conf interface TYPE Input client or output server interface supported May be any of the following file dir pipe socket or optionally tibco mode MODE IAgent mode either F full S standalone server only or C standalone client only August 2003 Page 26 version 2 3 2 IAgent User s Guide Configuration TPconfig FILENAME IAgent trading partner configuration file name default is tpartner conf Process Specific configuration options These options set the IAgent Server ports both standard and hi priority ports hipriport PORT High priority server port for Hipri Server process only stdport PORT or port PORT Standard server port for Std Server process only Certificate and Key location options These options describe the location of all certificates and private keys in the Agent system key FILENAME Own local private key file in PEM format cert FILENAME Own local certificate file in PEM format CApath PATH Path to Certificate Authority CA certificates in PEM format CAfile FILENAME Certificate Authority CA file in PEM format Integration API
76. ading partner file August 2003 Page 34 version 2 3 2 IAgent User s Guide Configuration 3 Add the new Trading Partner id to the trading partners variable Note this is a comma delimited list of all trading partners in your IAgent system 4 Modify the new section to reflect the values of the Trading Partner Configuration Worksheet Removal of a current trading partner Removing a current trading partner is trivial and consists of only two steps 1 Remove the current Trading Partner id from the trading partners variable Note this is a comma delimited list of all trading partners in your IAgent system 2 Delete the section for this trading partner as found in your current trading partner file Modification of a current trading partner Using a text editor edit the trading partner file tpartner conf by default and modify the setting for each trading partner as required When finished the IAgent system must be stopped and re started for the changes to take effect See below for a description of each field The Trading Partner configuration file The Trading Partner configuration file by default tpartner conf consists of several entries per trading partner and is processed prior to SSL communications trading partners to be supported in the IAgent system clients and or servers will require an entry in the configuration file An entry for the local trading partner is also required Each of the trading partner ent
77. an be caused by system resource problems file permission errors or an existing duplicate file CANNOT SAVE IASTATUS OUT FILE This message can be caused by system resource problems file permission errors or an existing duplicate file CANNOT SAVE IASTATUS TO PIPE This message can be caused by system resource problems file pipe permission errors or a halted read process on the pipe CANNOT SAVE RECEIPT OUT FILE This message can be caused by system resource problems file permission errors or an existing duplicate file CANNOT SAVE RECEIPT TO PIPE This message can be caused by system resource problems file pipe permission errors or a halted read process on the pipe CANNOT START CLIENT HANDSHAKE CANNOT VERIFY CLIENT CERT CANNOT WRITE EDI MSG TO PIPE This message can be caused by system resource problems file pipe permission errors or a halted read process on the pipe CANNOT WRITE EDI MSG TO SOCKET CANNOT WRITE OUTPUT FILE This message can be caused by system resource problems file permission errors or an existing duplicate file CANNOT WRITE SSL CLIENT August 2003 Page 89 version 2 3 2 IAgent User s Guide Administration CANNOT WRITE TIBCO EDI MSG CLIENTS CA CERTS MISSING CLIENTS OWN CERT MISSING CNAME MISMATCH INCORRECT MESSAGE TYPE SENT FROM TP ISA SEG MISSING FROM INPUT RECEIPT MSG MESSAGE BAD SIGNITURE FOUND MESSAGE INTEGRITY BROKEN NO CLIENT CERT SENT NO ISAID FOUND IN TPFILE NO PENDING REC FOUND RECE
78. and configuration of the IAgent system is rather complex Essentially the following actions are required Generate an RSA key pair public and private and Certificate Signing Request CSR Obtain a personalized X 509 certificate signed by a valid certificate authority Install the IAgent product support utilities and associated products Configure IAgent to your local machine and trading partner identity Add one or more remote trading partners Modify and test network connectivity to each trading partner Configure and integrate to the appropriate back end systems BESs Required Documentation This list of documentation may be needed for reference during IAgent installation Instructions for using the operating system on your target machine Documents for your EDI Translator Operation Support System OSS or Gateway products whatever system will act as the IAgent back end system interface Instructions for using the vi or other text editor for configuration file modification The following three chapters cover all the tasks required to install the IAgent product Subsequent chapters cover specific tasks in detail August 2003 Page 17 version 2 3 2 IAgent User s Guide Installation CHAPTER 5 PRE INSTALLATION TASKS Pre Installation Task Instructions IAgent pre installation consists of five tasks 1 Completing the pre install worksheet 2 Acquiring root access on the target machine 3 Acquiring the correct
79. ation Part 5 of this manual contains IAgent administration information including operations tasks maintenance issues and troubleshooting guidelines This section also includes security recommendations August 2003 Page 67 version 2 3 2 IAgent User s Guide Administration CHAPTER 25 IAGENT OPERATIONS ISSUES Product Startup Issues The IAgent system can be run in one of two modes Combined or Standalone Combined mode allows a single binary to spawn the required four major processes to support all IA processing The four processes are a standard client a receipt client a standard server and a high priority server Each process will be started from the original process and will share data via several shared memory databases and message queues STARTING THE IAGENT SYSTEM You must choose to start IAgent either as a system daemon at boot or from the command line Do not do both Either you can put in etc rc3 d and have it started on system boot or you can start it as from the command line See Chapter 9 for details on the command line options It is suggested that you start IAgent from the command line to test your configuration and configuration files When this has been successfully completed run the following to start Agent as a system daemon with the following command su root c etc rc3 d S99iagent start Example 23 Starting Agent as a system daemon Sun Solaris Only It is assumed that the PRNG da
80. ble 22 Commercial or third party documentation used by this product or manual 128 August 2003 xiv version 2 3 2 IAgent User s Guide Preface Preface Software Version This guide is published in support of Lymeware Corporation s IAgent software product version 2 3 2 It may also be pertinent to later releases please consult the release notes accompanying the software for further details Readership This manual is intended for administrators who need to setup and manage the IAgent system Knowledge of TCIF 98 006 Issue 2 EDI formats and TCIF EDI formats ASC X 12 EDI standards system administration and basic cryptography concepts is required Scope of this Guide This manual describes the configuration operation and management of the Agent system as described by TCIF98 006 Issue 2 This manual is divided into five parts and several appendixes Part 1 covers operation concepts of the IAgent system and introduces IA and SSL concepts Part 2 covers how to install the IAgent system with all required components Part 3 covers how to configure the IAgent system with manually generated configuration tables Part 4 covers how to integrate the IAgent system with backend systems BESs using the provided Integration Application Program Interfaces Integration APIs Part 5 is a reference section that also covers advanced topics and describes management tools used to maintain the IAgent system and maintenance issues T
81. but you can leave some blank For some fields there will be a default value If you enter the field will be left blank Country Name 2 letter code US US State or Province Name full name Connecticut Locality Name eg city 1 014 Lyme Organization Name eg company Lymeware Corporation Organizational Unit Name eg section Common Name eg YOUR FODN or CN www lymeware com Email Address iagent lymeware com Pleas nter the following extra attributes to be sent with your certificate request A challenge password none Writing RSA private Key and X509 certificate request Example 44 Using gen csr to create a DER Certificate Signing Request Example 44 shows the results of a certificate signing request being created in newreq pem in this document certificates and keys are truncated This is the text file in PEM format or binary file in DER format that you send to your selected Certificate Authority for certificate creation August 2003 Page 110 version 2 3 2 IAgent User s Guide Appendixes BEGIN CERTIFICATE 5 TGYMIGNAGEAMEIXCZAJBONVBAYTA1VTMROWEgYDVOOIEwtDD25uZWNO0aWN1ADEd BsGA1LUEChMUTH1tZXdhcmUgQ2 9ycG9yYXRpb2 4wXDANBgkqhkiG9w0BAOEFAANL ADBIAkEAy 9g5SaqvZ2Bv82MftHF3Ns80xq4520Vt vxzieQPOj8gjkS7SeShFTSoOU dEgO0pWOX6R58HMFBRJ9KC8Rid03FNwIDAQABOAAWAWYBAAMBAA EIE END CERTIFICATE REQUEST
82. cal Basic Receipt input message is as follows line NOT wrapped AR ISA 00 IAGENT 00 TEST ZZ LWC TEST AZ LWC 7 990629 1621 U 00307 000002466 0 T 199906301200002 Example 3 An example of a Basic Receipt input message A typical Integrity Receipt input message is as follows line NOT wrapped IAR 1SA 00 IAGENT 00 TEST ZZ LWC TEST AZ LWC 7 990629 1621 U 00307 000002466 0 T 2 199906301200002 1 542ac34623 098790 ed987698b0a62f 1436c91a7 Example 4 An example of an Integrity Receipt input message A typical Signed Receipt input message is as follows line NOT wrapped and incomplete AR ISA O00 IAGENT 00 TEST ZZ LWC TEST 7 990629 1621 U 00307 000002466 0 T 199906301200002 5 542ac34623 098790 ed987698b0 743c6a06591ca410027ed7 7 Example 5 An example of a Signed Receipt input message IA Status input message format The IA gent client process identifies a message starting with IAS as an IA Status message There are two types of IA Status input messages Defined and Custom Defined status messages are as defined in the IA Specification test stop WAN and stop OSS is how we name them Custom status messages are not specifically defined and will actually be treated as a pass through by the August 2003 Page 48 version 2 3 2 IAgent User s Guide Administration receiving IAgent server
83. co Combined or Full Directory Named Pipe FIFO Socket Tibco Table 10 Interfaces supported by mode Back End System BES Locations by Interface The location of the back end system BES may be limited by the selected interface The following table lists the limitations Interface BES Locations Supported File Same machine as Agent product Directory Note network or network mounded drives are not Named Pipe FIFO recommended for working directories or pipes Socket Any IP connected machine Tibco IP connected machine on same subnet Note the use of Tibco s rvrd is not recommended Table 11 BES Locations supported by Interface August 2003 Page 46 version 2 3 2 IAgent User s Guide Administration CHAPTER 16 OUTBOUND CLIENT FORMATS The IAgent standard client process expects three possible input message formats regardless of input mode They are EDI message Receipt message and IA Status message formats A description and example of each is included below Input EDI message format The IA gent client process expects to find an ANSI X 12 ISA segment as the first 105 bytes of the message actually the remainder of the message need not be in X 12 EDI format The client process will aggressively check for the ISA segment identifier and the sender and receiver ID up to 15 characters Other fields are not checked or verified However both X 12 and the IAgent expect the
84. co API Writer Example August 2003 Page 65 version 2 3 2 IAgent User s Guide Administration CHAPTER 24 TESTING INTEGRATION WITH BACKEND SYSTEMS Back end systems BESs are assumed to be even driven and capable of producing valid IAgent input message formats and processing valid IAgent output message formats for the specific Integration API selected It is suggested that the Directory Integration API first be supported so input message formats may be examined prior to back end system integration A simple back end system BES integration test must 1 Test each input message format independent of Integration 2 Test each output message format independent of Integration API 3 Test the specific input Integration API functionality This may be tested with a standalone IAgent client see Chapter 25 on how to start a standalone IAgent client 4 Test the specific output Integration API functionality This may be tested with a standalone IAgent server see Chapter 25 on how to start a standalone IAgent server 5 Do an end to end test with the specific Integration API This may be tested with a standalone IAgent client and a standalone IAgent server 6 Do a second end to end test with the specific Integration API This should be tested with a full IAgent system See Appendix D for a sample Backend Integration API test plan August 2003 Page 66 version 2 3 2 IAgent User s Guide Administration Part 5 lAgent Administr
85. cting a third party Certificate Authority CA iese se se se Se Ge ee Se ee ee ee eene nennen ee ee ee 24 2 Completing the certificate request worksheet ee ee Se SA Ge Ge ee Ge ee ee ee ee Ge ee GR RA 24 3 Creating a Certificate Signing Request file and private 24 4 Sending the Request to your chosen CA iese esse esse ese se ee ee Se Ge GR SA Ge Gee ee Ge 24 5 Installing local certificates and 25 6 Installing local Certificate Authority certificates 25 CHAPTER 9 IAGENT SYSTEM CONFIGURATION ADMINISTRATION 26 THE SYSTEM OR IAGENT CONFIGURATION 2 2 22 002 0001000000000000000000000000000000805000000 rennen seen rens inneren nennen 26 suse EE EE HO ER Integration settings and options and MEE AE BROER EER EO RE M 26 BASIC SYSTEM WIDE CONFIGURATION 8 26 PROCESS SPECIFIC CONFIGURATION 5 27 CERTIFICATE AND KEY LOCATION OPTIONS 8 27 INTEGRATION API SETTINGS AND 5 7 27 File Interface Options d ER aes dead ga dine 27
86. cur x FILENAME cert FILENAME cert file FILENAME Own local certificate file in PEM format y PATH CApath PATH Path to Certificate Authority CA certificates in PEM format z FILENAME CAfile FILENAME Certificate Authority CA file in PEM format I Table 6 IAgent Command Line Arguments concluded August 2003 Page 32 version 2 3 2 IAgent User s Guide Default lAgent configuration values and settings The IAgent product uses default values for most of the IAgent configuration file and command line arguments The following table lists all current default configuration values and settings all of which can be overridden with either configuration file values or command line values Configuration IAgent configuration option Default display sloppyallow off sloppyinactive off cachesize ENTRIES 128 outdir PATH out dir file FILENAME tes ignoredupreceipts off loopbackdelay 5 oneshot off receiptmode MODE outsocket SOCKE outtibco MESSAGE NAME i version off savereceipts off packetmode off indir PATH in dir t file ECONDS 0 nternal TADDRESS PORT 127 0 0 1 versionl 1 iagent tibco server messag onfig config file FIL ENAME iagent conf debug debuglevel entropy FILEN
87. deliver the message If the connect fails then the message will be stored as a file see Directory Interface Mode Chapter16 for file details in the TEMP directory tmp by default Use of port numbers greater than 1024 is recommended so as not to run into root permission and port sharing problems The input outbound socket port may be set with the g PORT or insocket PORT options The output inbound socket address and port may be set with S ADDRESS or outsocket ADDRESS options Be sure to include a port in the address trading partner messages will be fed into the same input socket and will exit to the same output socket Sample code to support the Socket Interface is supplied in Chapter 23 August 2003 Page 55 version 2 3 2 IAgent User s Guide Administration CHAPTER 21 TIBCO MESSAGE INTEGRATION Tibco Interface Mode TIBCO Software Inc of Palo Alto California USA sells a number of middle ware message bus type products which allow distributed processes in a heterogeneous environment to communicate using a publisher subscriber model Their TIB Rendezvous product allows multiple publishers to send atomic RV messages to multiple subscribers identified with a unique RV message subject name The tibco interface mode reads and writes an IAgent specific RV message containing a length and an arbitrary ASCII string containing the Input or Output Message Format The RV message is defined as
88. displayed in the following figure 2 800 2007 Dameware Corporation AN Rights Reserved Figure 13 Example Web Reporter display The Web Reporter allows remote monitoring of traffic errors and performance data Specifically it displays all inbound and outbound message traffic in message detail and with message type summaries The web reporter also displays the 10 most current errors encountered inbound or outbound and provides limited performance statistics Any HTML 3 2 or newer compatible web browser may be used for display The reporter function updates the page really the reporter file every minute and the resulting HTML also auto refreshes itself using the HTML meta tag of http equiv refresh every minute August 2003 Page 75 version 2 3 2 IAgent User s Guide Administration The reporter file 1astatus html may be locally browsed with a URL of something like file opt iagent iastatus html without the need for a web server The reporter file may be served as a single web page with any HTTP 1 0 HTML 3 2 or newer web server if remote access 15 desired August 2003 Page 76 version 2 3 2 IAgent User s Guide Administration CHAPTER 27 TROUBLESHOOTING PROBLEMS AND ERRORS Troubleshooting errors and problems with the IAgent system may seem like a daunting task given the distributed processing and collaborative nature of the IAgent system and its peer systems both all other IA systems and t
89. document Convention Use lt gt Substitute value for any term that appears within the angle brackets Do not enter the angle brackets unless specifically instructed to do so Example rm filename means that you should type the name of the file you wish to delete indicate reguired part of a statement Do not enter braces Example f lt filename gt means that you must enter the f parameter followed by a required filename Square Brackets indicate an optional part of a statement Do not enter the brackets Example f lt filename gt means you have the option of entering the f parameter followed by a filename An ellipse indicates that the immediately preceding item can be repeated indefinitely Do not enter the ellipse Example f means you can repeat the f parameter with other values Parentheses should be entered as shown They are part of the syntax of a statement and are not special symbols Example f filename means you should enter a filename enclosed by Parentheses Table 2 Symbols used within syntax statements August 2003 20 version 2 3 2 IAgent User s Guide Introduction Part 1 Introduction Part 1 contains a general description of TCIF Interactive Agents and details of the components of such systems This section also introduces the Lymeware IAgent Product detailing product features and system r
90. dress Firewall Machine information Address Enabled ports Is ICMP echo ping packets allowed to pass through Y N Network Address Translation NAT supported Y N Network Address Translation NAT information External IP address for IAgent machine External Standard IA port External High Priority IA port Router information Address Subnet Limit Port filtering supported Port filtering for IA ports disabled Copyright 1999 2002 Lymeware Corporation rights reserved Permission to copy for use in IAgent installation is granted August 2003 Page 98 version 2 3 2 IAgent User s Guide Appendixes For IAgent configuration information collection To be used during before building the configuration file Machine specific information Hostname FQDN IP address Standard IA port High Priority IA port Certificate specific information RSA Private Key file Must be in PEM format CSR file Format PEM DER Server Certificate file Must be in PEM format CA Certificate file Must be in PEM format Interface specific options Interface to support Directory Interface specific options Input Directory Output Directory Directory Polling Delay in seconds Named Pipe Interface specific options Input Pipe Name Output Pipe Name Socket Interf
91. e Alice sent If they agree then the message was received intact A summary such as this is called a message digest or hash function Message digests are used to create short fixed length representations of longer variable length messages Digest algorithms are designed to produce unique digests for different messages Message digests are designed to make it too difficult to determine the message from the digest and also impossible to find two different messages which create the same digest thus eliminating the possibility of substituting one message for another while maintaining the same digest Another challenge that Alice faces is finding a way to send the digest to the bank securely when this is achieved the integrity of the associated message is assured One way to do this is to include the digest in a digital signature Digital Signatures When Alice sends a message to the bank the bank needs to ensure that the message is really from her so an intruder does not request a transaction involving her account digital signature created by Alice and included with the message serves this purpose Digital signatures are created by encrypting a digest of the message and other information such as a sequence number with the sender s private key Though anyone may decrypt the signature using the public key only the signer knows the private key This means that only they may have signed it Including the digest in the signature means the
92. e Directory Authentication Framework 1988 CCITT which defined the framework of the certificate elements also known as certificate fields Netscape adopted the 509 certificate structure for its Secured Socket Layer SSL protocol design IA message systems also use 509 certificates to verify the identity and public key of all validated IA trading partners If each trading partner has a certificate which validates the other s identity confirms the public key and is signed by a trusted agency then they both will be assured that they are communicating with whom they think they are Such a trusted agency is called a Certificate Authority and certificates are used for authentication Contents of Certificates A certificate associates a public key with the real identity of an individual or some other entity known as the subject As shown in Table 1 information about the subject includes identifying information the distinguished name and the public key It also includes the identification and signature of the Certificate Authority that issued the certificate Issuer information and the period of time during which the certificate is valid It may have additional information or extensions as well as administrative information for the Certificate Authority s use such as a serial number Dun and Bradstreet DUNS company number or other internal information Subject Distinguished Name Public Key Issuer Distinguished Na
93. e PIPENAME Output pipe name for Pipe interface only R MODE receiptmode MODE Receipt mode supported May b ither internal or external S SOCKETADDRESS PORT outsocket SOCKETADDRESS PORT Output socket address and port for Socket interface only Table 4 IAgent Command Line Arguments August 2003 Page 30 version 2 3 2 IAgent User s Guide Configuration T MESSAGE NAME outtibco MESSAGE NAME Output tibco message subject name for Tibco interface only V version Prints the version of IAgent then exits Y savereceipts Flag to force storage of all inbound and outbound receipts 2 packetmod Forces IA Input packet format support only Input directory name for Directory interface only PIPENAME Input pipe name for Pipe interface only FILENAME config FILENAME config file FILENAME IAgent configuration file name default is iagent conf d DEPTH debug DEPTH debuglevel DEPTH Debug display depth for testing purposes only e FILENAME entropy FILENAME Entropy source file required for cryptographic calculations SOCKETPORT port for Socket interface only g SOCKETPORT insocket Input socket h PORT hipri
94. e and a timestamp will be sent to acknowledge an IA EDI message from a remote trading partner A basic receipt is expected and required for each IA EDI message sent to the remote trading partner Integrity Receipt 551 encryption and digest An integrity receipt which consists of the ISA segment of the EDI message a timestamp and a message digest will be sent to August 2003 Page 40 version 2 3 2 IAgent User s Guide Configuration acknowledge an IA EDI message from a remote trading partner An integrity receipt is expected and required for each IA EDI message sent to the remote trading partner e Signed Receipt includes SSL encryption and signed message integrity A signed receipt which consists of the ISA segment of the EDI message a timestamp and a digital signature will be sent to acknowledge an IA EDI message from a remote trading partner A signed receipt is expected and required for each EDI message sent to the remote trading partner August 2003 Page 41 version 2 3 2 IAgent User s Guide Configuration CHAPTER 14 MESSAGE RECEIPT ISSUES One of the requirements of receipt processing is the unique nature of EDI messages and the ISA segment in particular If for any reason including re send or duplicate sending any message is transmitted more than once with the IAgent system a non fatal error of DUPLICATE PENDING RECORD FOUND will be reported This is due to the fact that a pending receipt record already ex
95. e used to monitor this handshake A protocol two computers or processes use to initiate a communication session HTML HyperText Markup Language The language used to build and describe web pages ILEC Incumbent Local Exchange Carrier August 2003 Page 124 version 2 3 2 IAgent User s Guide Appendixes International Standards Organization ISO creates international standards including cryptography standards Internet Engineering Task Force IETF creates Internet standards including security standards ITU T International Telecommunications Union Telecommunications standardization sector key A string of bits used widely in cryptography allowing people to encrypt and decrypt data Given a cipher a key determines the mapping of the plaintext to the ciphertext See also private key public key key exchange A process used by two more parties to exchange keys in a cryptosystem key pair The full key information in a public key cryptosystem consisting of the public key and private key message digest The result of applying a hash function to a message non repudiation A property of a cryptosystem Non repudiation cryptosystems are those in which the users cannot deny actions they performed OSS Operational Support System In the Telecommunications Industry the OSS is the sum of all in house provisioning and billing systems and databases PEM Internet Privacy Enhanced Mail as defined
96. egration Chapter 19 Named Pipe Integration Chapter 20 Socket Integration Chapter 21 Tibco Message Integration Chapter 22 Testing Integration Configuration Chapter 23 Example Integration API Test Programs Chapter 24 Testing Integration with Backend Systems Part 5 Agent Administration Chapter 25 Operations issues Chapter 26 Maintenance issues Chapter 27 Troubleshooting issues Chapter 28 Error Messages Chapter 29 Security issues Chapter 30 How to get help August 2003 xvi version 2 3 2 IAgent User s Guide Manual Revision History Version 2 3 2 Version 1 3 1 Version 1 3 0 Version 0 3 0 Version 0 2 6 Version 0 2 5b Version 0 2 4b Version 0 2 3b August 2003 January 2003 April 2002 November 2001 April 2001 September 2000 March 2000 January 2000 Version 0 2 Quick Readme version November 1999 August 2003 xvii Preface version 2 3 2 IAgent User s Guide Preface Support Questions and Bug Reporting Several e mail addresses are available for customer support technical support and sales questions or to report a potential bug in the software or documentation If your product was purchased from Lymeware please use the following addresses Service lymeware com for all account related inquires and issues including those relating to licenses If customers are unsure which address to use then they should send to this address This address is monitored daily and all messages will be responded to This add
97. eipt required BASIC RECEIPT INTEGRITY RECEIPT SIGNED RECEIPT server status initial state of this partner s IA server 0 not operational 1 active HHT EEE HEHE HEHE HEE HEE HE HEE E E TE HE EE E E E EE HEE HE HEE HEE E E E HEE E E E E E E HE volume testing trading partner 1 partner id TP 1 certificate common name 1 address 127 0 0 1 standard port 9001 hipri port 9011 session timeout 30 30 min resumable sessions ia message to tp SIGNED EDI ia message from tp SIGNED EDI ia receipt to tp INTEGRITY RECEIPT ia receipt from tp INTEGRITY RECEIPT server status 1 HE HEHE EEE HEE HEE HE HE HE HEE HEE HE HEE HEE HEE HE E E E E E E E E E E E E HEE HEE E H 2 1 volume testing trading partner 2 partner_id TP_TWO certificate_common_name TP_TWO ip_address 127 0 0 1 standard_ip_port 9002 hipri_ip_port 9012 session_timeout 30 30 min resumable sessions ia message to tp SIGNED EDI ia message from tp SIGNED EDI ia receipt to tp INTEGRITY RECEIPT ia receipt from tp INTEGRITY RECEIPT server status 1 Het HEHE EEE EEE HEE HE HEE HE HEE HE HEE HEE HEE EE HE E HEE HE HEE E E E E E E E E E HEE HEE HH EOF tpartner conf August 2003 Page 118 version 2 3 2 IAg
98. em or lAgent configuration file The system configuration file 1agent conf by default contains option and setting entries which override any system defaults however command line arguments will override any configuration file settings All IAgent options and settings should be in this file IAgent configuration consists of setting all of the following types of configuration options Basic system wide configuration options Process Specific configuration options Certificate and Key location options Integration API settings and options and Advanced and special options The configuration options may appear on the command line or appear in the system configuration file 4agent conf It is recommended that the configuration file be used when operating the IAgent in a production system and that additional command line options may be used during testing and troubleshooting The easiest way to build a system configuration file is to make a copy from the example supplied in the opt iagent examples directory Copy this example file to opt iagent as a new file called iagent conf Now open the new file with your text editor of choice We will now tackle each group of configuration options available in the following sections Basic system wide configuration options These options set the IAgent configuration file and Trading Partner file names the integration interface to support and the mode in which to run the IAgent system c
99. emon was already started prior to the above command This daemon is also automatically started on boot The Standalone mode allows a single process client or server to be started independently At this time processes running in standalone mode do not have access to the shared memory database and therefore have limited functionality It may be useful to start a client or server in standalone mode for testing purposes Because specific functions may require shared memory database support pending receipt list processing for example they will not be available in standalone mode Starting the system in Combined Mode The IAgent system clients and servers may be started from the command line as follows note this is a single line bin iagent mode F interface dir indir in dir outdir out dir Example 24 Starting Agent form the command line in Combined mode This example will start the Agent system up in Combined or Full mode mode F with the directory interface supported interface dir in both Clients and Servers Input messages August 2003 Page 68 version 2 3 2 IAgent User s Guide Administration will be read from the Client directory indir in dir and output messages will be written to the Servers directory outdir out dir Starting the system in Standalone Mode The IAgent process client or server may be started from the command line as follows bin iagent
100. ent User s Guide Appendixes gen csr Request conf configuration file This is the Request conf configuration file used by csr It may be modified to reflect customer defaults but should be backed up first Gen csr example configuration file version 1 4 This is mostly being used for generation of certificate requests Copyright C 2000 2001 Lymeware Corporation Header export home kobar iagent src RCS request cnf v 1 3 2001 01 13 18 44 05 kobar Exp FE AE AE AE AE AE AE AE AE AE AE AE E AE AE E AE AE E FE AE AE AE AE AE AE AE AE AE AE E AE AE AE AE AE AE AE AE AE FE AE AE AE AE AE AE AE E AE AE AE AE AE AE AE AE AE AE AE E EAE TE EAEE req RANDFILE SENV HOME rnd RANDFILE RAND egd tmp entropy default bits 768 default keyfile privkey pem distinguished name req distinguished name attributes req attributes default md md5 which message digest to use req distinguished name countryName Country Name 2 letter code countryName default US countryName min 2 countryName max 2 stateOrProvinceName State or Province Name full name stateOrProvinceName default Connecticut localityName Locality Name eg city 0 organizationName Organization Name eg Company 0 organizationName default Lymeware Corporation organizationalUnitName Organizational Unit Name eg section forganizationalUnitName default commonName Common
101. equirements Lastly this section includes an introduction to SSL August 2003 Page 1 version 2 3 2 IAgent User s Guide Introduction CHAPTER 1 INTRODUCTION TCIF INTERACTIVE AGENT SYSTEMS In March 1999 The Telecommunications Industry Forum TCIF created an Electronic Interactive Agent IA standard TCIF 98 006 which allows secure EDI transactions over relatively insecure networks i e The Internet via TCP IP and SSLv3 This standards body was chartered with increasing the ease and use of secure EDI ordering in the Telecommunications industry an industry that has seen increasing growth due to the open competition created by the FCC 1994 Telecommunications Act The IA Specification describes and specifies a data interface to provide interoperability between trading partners in the Telecommunications Industry The initial purpose of the data exchange was to support Local Service Ordering but any EDI transaction or type of ordering is supported The intent of the was to improve upon the performance of the conventional store and forward method of messaging used by Value Added Networks VANS When using a VAN for connectivity the sending trading partner drops off an EDI transaction message Later perhaps in minutes or hours the VAN delivers the EDI transaction message to the receiving trading partner This batch mode and the associated delays preclude the use of a VAN for near real time EDI transaction processing
102. er files you have modified including license files to a new location not under opt iagent 3 Backup all transactions pending receipts and log files to a new location You are now ready to install the latest version top of your last installed version Please refer to the INSTALL file instal1 txt in the Agent distribution for platform and environment specific update instructions If the updated version is a newer version number than currently installed if the update is a patched or bug fix release it may have the same version number then a new license dat file with the correct matching version number will be required August 2003 Page 20 version 2 3 2 IAgent User s Guide Installation CHAPTER 7 POST INSTALLATION TASKS Post Installation Task Instructions IAgent post installation consists of five tasks 1 Installing the license file 2 Installing local certificates and keys 3 Creating the IAgent configuration file 4 Verifying PRNGD installation and configuration 5 Creating the Trading Partners configuration file These tasks should be completed in order since subsequent tasks may require information from previous tasks If you encounter any problems with these tasks or instructions refer to Chapter 30 How To Get Help 1 Installing the license file At this time the supplied license file should be installed The license file will be delivered to the Contact E Mail Address as was supplied in the License Re
103. erver not operational 1 active Table 9 Trading Partner Configuration Fields continued An example of a standard trading partner configuration file may be found in Appendix C August 2003 Page 36 version 2 3 2 IAgent User s Guide Configuration CHAPTER 11 TRADING PARTNER CONNECTIVITY It is required that the IAgent machine has a permanent TCP IP connection to each trading partner machine it will communicate with The basic options for these connections are A Direct Connection same LAN or MAN or WAN A Public Connection e g the Internet or other public networks without a Firewall A Public Connection e g the Internet or other public networks with Firewall A Private Connection Frame Relay or ATM without Firewall and A Private Connection Frame Relay or ATM with Firewall This list is organized in from a least desirable but easiest to implement to a most desirable and hardest to implement Trading Partner Connectivity Figure 5 Trading Partner Connectivity Every element in the TCP IP pipeline must be tested and direct connectivity which can be tested with telnet see below must exist prior to any IA connectivity testing Simple Telnet Testing To ensure bi directional TCP IP testing the telnet utility supplied with all supported platform operating systems can be used The following must be performed by each trading partner local and remote to ensure TCP IP connectivity and proper
104. es an issuer to assert the validity of the identity of the certificate subject up to the top level Certificate Authority This presents a problem Since this is who vouches for the certificate of the top level authority which has no issuer In this unique case the certificate 15 self signed so the issuer of the certificate is the same as the subject As a result one must exercise extra care in trusting a self signed certificate The wide publication of a public key by the root authority reduces the risk in trusting this key it would be obvious if someone else publicized a key claiming to be the authority August 2003 Page 105 version 2 3 2 IAgent User s Guide Appendixes A number of companies such as VeriSign and EnTrust have established themselves as certificate authorities These companies provide the following services eVerifying certificate requests eProcessing certificate requests elssuing and managing certificates To use the services of one of these companies one must be able to generate a valid certificate request file containing identification information and the RSA public key in the format required And that is exactly what is described in the next section Creating a Client or Machine Certificate Request A client certificate 15 used to authenticate a client to a server Creating and installing a client certificate 15 difficult because the client must generate a key pair keep the private key to itself and send the pub
105. ese eene eene enne enne 8 Trading Partner Connectivity iu ee et erre eee 37 Messag Dal EG RE Ee ie Der EO petalis 40 Internal Receipt Mode Data EIOW use soe ees eed god Ge ie ds 42 External Receipt Mode Data Flow ese ves Gees ged e se ge Rae se be Gegee eg ede 43 Backend System to Integration API Interfaces 00 404 0 45 The detailed message data format for named pipe interface mode 54 The detailed message data format for the socket interface mode 55 Integration API Support Testing EE ere Qo ee RSG Gee ge sess ee ER GEE See 58 Example Web Reporter display eerte irae Ge SG gee ean de Rd Eed SR Sage NS Heese se ed 75 Processing as a Series of Pipes 77 Processing as a Series of Pipes 77 August 2003 xiii version 2 3 2 IAgent User s Guide Preface List of Tables Typographic convention S aniisi e R s GO E I ee ik 19 Table 2 Symbols used within syntax statements ee see se ee Ee See Ge ee ee ee Ga Ge nnne nnne 20 Table 3 LAsent Handshake Sequence Es 8 Table 4 Agent Command Line Argument sesse sesse es ee ee ee ee ee Ee 30 Table 5 Agent Command Line Argume
106. evels of message and receipt security supported cipher suites certificate requirements and valid Certificate Authorities are typically addressed in a Joint Implementation Agreement between trading partners See Appendix A for necessary Trading Partner information and worksheets How does it work The heart of the IAgent system is the Public Key Infrastructure PKT comprised of X 509 client certificates and private RSA keys 509 server certificates and private RSA keys and one or more Certificate Authority CA X 509 certificates See Chapter 2 for more information on Certificates and Public Key Encryption Here is how it works in a nutshell The IAgent client has its own X 509 certificate with a SSL unique Common Name as supplied by the Trading Partner and the certificate s matching private RSA key The client also has or more usually root certificates These certificates will be used during the IA handshake between the client and the server to verify the validity of the server s certificate Similarly on the other side of the fence the Agent server has its own X 509 certificate and private key The server also has one or more certificates that it uses to validate the client s certificate A very simplified version of the IA SSLv3 handshake with emphasis on certificate transfers and validation would look something like this August 2003 Page 7 version 2 3 2 IAgent User s Guide Introduction
107. f any type of messages from active trading partners for testing purposes only sloppyinactive 0 1 Flag to allow receipt of message from inactive trading partners for testing purposes only ignoredupreceipts 0 1 Flag to allow duplicate receipts without triggering errors for testing purposes only loopbackdelay SECONDS Debug loopback delay in seconds for testing purposes only debug DEPTH or debuglevel DEPTH Debug display depth for testing purposes only August 2003 Page 28 version 2 3 2 IAgent User s Guide entropy FILENAME vhack 0 1 Self signed issuer certificate verify hack flag sendstatus 0 1 Configuration Entropy source file required for cryptographic calculations For Solaris product versions only Flag to force automatic sending of IAstatus messages when internal errors occur verbose 0 1 Flag oneshot 0 1 Flag For raw 0 1 Flag packetmode 0 1 Flag For savereceipts 0 to force verbose more messages to display and logs to force exit after a singl debug only to force sending of raw IA to force sending of packet mod debug only 1 IA messag EDI messages is sent or received For debug only messages only Flag to force storage of all inbound and outbound receipts An example of a directory interface configuration file and a socket interface configuration file may be found in Appe
108. face IAGENT PRE INSTALLATION WORKSHEET ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee 97 IAGENT CONNECTIVITY WORKSHEET ese ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee 98 IAGENT CONFIGURATION WORKSHEET ese ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee 99 IAGENT TRADING PARTNER WORKSHEET ee se se ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee nene ee ee ee ee ee 100 CERTIFICATE REQUEST Gee ee rra ER eade Ge Ge PR Res 101 LICENSE REQUEST ER EE EE EE EE EE OG 102 TAGENT LICENSE REQUEST FORM Se Ee Se Ge SR Ge Ee etre EER Ge ee Ge See ER ER ee Ge Ee ee ER Ge DER ee RR Ge Ge GER Ee ee ed ee Ge Ge ER 102 TAGENT PROBLEM REPORT FORM 5 Ee VER Ge Ee Se ee 103 APPENDIX B CERTIFICATES AND THE GEN CSR ese ccn 104 APPENDIX C SAMPLE CONFIGURATION FILES eie ese ee ee see ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee 112 SYSTEM OR AGENT CONFIGURATI
109. formation required This Certificate Request Worksheet should be used to complete the specific forms provided by your selected Certificate Authority Please contact your CA for any additional information that may be Copyright 1999 2002 Lymeware Corporation rights reserved Permission to copy for use in Agent installation is granted August 2003 Page 101 version 2 3 2 IAgent User s Guide Appendixes License Request Form A specific license data file will be required to run the Agent system Lymeware or your distributor will supply this license file if the following information is supplied For requesting a valid commercial or evaluation IAgent product license Customer specific information Customer Company Name Lymeware Product Name Lymeware Product Version Lymeware Product Options Target Machine IP Address Target Machine Host ID Target Machine Make and Model Target Machine Operating System and Version Contact Person Contact Phone Number Contact E mail Address This License Request Form may be faxed to Lymeware Corporation at 801 383 9021 or the same information may be e mailed to support lymeware com Copyright O 1999 2002 Lymeware Corporation rights reserved Permission to copy for use in IAgent installation is granted license file will be delivered to the Contact E Mail Address The license file must be installed at opt
110. gether such as a user s identity and public key Certificate Authorities CAs provide certificates Certificate Authority CA A person or organization that creates certificates and verifies the identity of the certificate owner Certificate Revocation List CRL A list of certificates that have been revoked before their expiration date cipher An encryption decryption algorithm ciphertext Encrypted data CLEC Competitive Local Exchange Carrier Data Encryption Standard DES block cipher developed by and the U S government in the 1970 s as an official standard decryption The inverse reverse of encryption DER Distinguished Encoding Rules for ASN 1 as defined in X 509 Section 8 7 digest Commonly used to refer to the output of a hash function e g message digest refers to the hash of a message digital signature The encryption of a message digest with a private key ECIC The Electronic Communications Implementation Committee of TCIF Electronic Data Interchange EDI an international business to business data interchange format as specified by ANSI X 12 standards encryption The transformation of plaintext into an apparently less readable form called ciphertext through a mathematical process The ciphertext may be read by anyone who has the key that decrypts undoes the encryption the ciphertext expiration date Certificates and keys may have a limited lifetime expiration dates ar
111. gured to provide a server certificate or request a client certificate Though cases exist where additional handshake steps are required for management of cipher information this article summarizes one common scenario see SSL specification for the full range of possibilities Once an SSL session has been established it may be reused thus avoiding the performance penalty of repeating the many steps needed to start a session For this the server assigns each SSL session a unique session identifier which is cached in the server and which the client can use on forthcoming connections to reduce the handshake until the session identifier expires in the cache of the server The elements of the handshake sequence as used by the client and server are listed below Negotiate the Cipher Suite to be used during data transfer Establish and share a session key between client and server Optionally authenticate the server to the client required for IA Optionally authenticate the client to the server required for IA The first step Cipher Suite Negotiation allows the client and server to choose a Cipher Suite supportable by both of them SSL3 0 protocol specification defines 31 Cipher Suites Cipher Suite is defined by the following components August 2003 Page 13 version 2 3 2 IAgent User s Guide Introduction Key Exchange Method Cipher for Data Transfer Message Digest for creating the Message Authentication Code MAC These three
112. he BES The IAgent system can best be diagnosed by envisioning the entire system as a series of pipes and checking the status and data at each pipe connection Outbound Pipes and Test Points Bat Los 7 Figure 15 Processing as Series of Pipes inbound It is suggested that running Agent product a standalone mode from a command line and with the verbose and debug display flag set is the first and usually best step Inspect the iagent log iagent err and iagent alert logs after sending a single message to the IAgent system from the BES August 2003 Page 77 version 2 3 2 IAgent User s Guide Administration Failed Transactions Failed Transactions are local input messages that for some reason could not be sent to the remote trading partner IA system Currently all failed transactions will be saved in very ugly temporary file names to the failed message directory opt iagent failed messages If possible they will be saved in their ASNI DER binary format so don t try to cat them Invalid Messages Invalid Messages are remote input messages which for some reason could not be properly received from the remote trading partner IA system invalid messages and receipts will be saved in very ugly temporary file names to the invalid message directory opt iagent invalid messages If possible they will be saved in their ASNI DER binary format lAgent Alert Messages
113. he following is a brief outline of the contents of the manual Part 1 Introduction Chapter 1 Contains general introductory material to Interactive Agent IA systems IA protocols and the different components of IA messaging and communication Chapter 2 Introduces the IAgent product and components Chapter 3 Contains basic introductory material to the SSL protocol and the security components of SSL messaging and communication Part 2 IAgent Installation Chapter 4 Outlines how to install and configure the IAgent system for production use Chapter 5 Describes pre installation tasks Chapter 6 Describes how to install the IAgent system Chapter 7 Describes post installation tasks Part 3 Agent Configuration Chapter 8 Describes how to generate a server key and server certificate request and how to obtain test and install the certificate Chapter 9 Describes how to configure the Agent system with configuration files August 2003 XV version 2 3 2 IAgent User s Guide Preface Chapter 10 Describes how to add a Trading Partner to the IAgent system Chapter 11 Describes how to test connectivity and messaging to a Trading Partner Chapter 12 Multiple Trading Partner issues Chapter 13 IA receipt overview Chapter 14 IA receipt issues Part 4 Integration API Technical Reference Chapter 15 Integration Overview Chapter 16 Outbound Client Formats Chapter 17 Inbound Server Formats Chapter 18 File amp Directory Int
114. her private messages The task of privately choosing a key before communicating however can be problematic Public key cryptography also known as asymmetric cryptography solves the key exchange problem by defining an algorithm that uses two keys each of which may be used to encrypt a message If one key is used to encrypt a message then the other must be used to decrypt it This makes it possible to receive secure messages by simply publishing one key the public key and keeping the other secret the private key The most widely supported key pair algorithm is the RSA algorithm from RSA Security now in the public domain Anyone may encrypt a message using the public key but only the owner of the private key will be able to read it In this way Alice may send private messages to the owner of a key pair the bank by encrypting it using their public key Only the bank will be able to decrypt it August 2003 Page 10 version 2 3 2 IAgent User s Guide Introduction Message Digests Although Alice may encrypt her message to make it private there 18 still a concern that someone might modify her original message or substitute it with a different one in order to transfer the money to themselves for instance One way of guaranteeing the integrity of Alice s message is to create a concise summary of her message and send this to the bank as well Upon receipt of the message the bank creates its own summary and compares it with the on
115. in RFC 1421 and RFC 1422 Also may refer to the Base 64 certificate format defined in RFC 1422 plaintext The data to be encrypted private key In public key cryptography this key is the secret key It is primarily used for decryption but is also used for encryption with digital signatures public key In public key cryptography this key is made public to all it is primarily used for encryption but can be used for verifying signatures public key cryptography Cryptography based on methods involving a public key and a private key Public Key Cryptography Standards PKCS A series of cryptographic standards dealing with public key issues published by RSA Laboratories Public Key Infrastructure Standards PKIX A series of cryptographic standards dealing with public key infrastructure and X 509 certificate issues published by the IETF RBOC Regional Bell system Operating Company The pieces of AT amp T created to provide Local telephone service Often referred to as the Bells RSA algorithm A public key cryptosystem developed by RSA Data Security Inc secret key In secret key cryptography this is the key used both for encryption and decryption secure channel A communication medium safe from the threat of eavesdroppers Secure Socket Layer SSL A protocol developed by Netscape used for secure Internet communications August 2003 Page 125 version 2 3 2 IAgent User s Guide Appendixes session
116. ing problem report should include the problem report ID in the subject line Customers without support contracts with Lymeware Corporation should not use this address but should contact their distributor directly Bugs lymeware com for bug reports and documentation problems Bug reports on software releases are always welcome These may be sent by any means but e mail to the bug reporting address listed above is preferred Please send proposed fixes and successful workarounds with the report if possible Additional useful information would include IAgent software version hardware description operating system version and patches screen dumps relevant sections of logs and configuration files and failed messages files Any reports will be acknowledged but further action is not guaranteed Any changes resulting from bug reports may be included in future releases August 2003 Page 94 version 2 3 2 IAgent User s Guide Appendixes Appendixes The final part of this manual contains appendixes with additional information on IAgent administration including worksheets and other maintenance issues August 2003 Page 95 version 2 3 2 IAgent User s Guide Appendixes APPENDIX A CONFIGURATION WORKSHEETS AND FORMS This appendix contains worksheets that should be used to complete specific tasks during the installation configuration and maintenance of your IAgent system The following table describes each worksheet Agent Pre In
117. ion on SSL and the cryptographic components used in SSL see Appendix H References Cryptographic Techniques Understanding SSL requires an understanding of cryptographic algorithms message digest functions also called one way or hash functions and digital signatures These techniques are the subject of entire books and provide the basis for privacy integrity and authentication Cryptographic Algorithms Suppose Alice wants to send a message to her bank to transfer some money Alice would like the message to be private since it will include information such as her account number and transfer amount One solution is to use a cryptographic algorithm a technique that would transform her message into an encrypted form unreadable except by those it is intended for Once in this form the message may only be interpreted through the use of a secret key Without the key the message is useless good cryptographic algorithms make it so difficult for intruders to decode the original text that it isn t worth their effort There are two categories of cryptographic algorithms conventional and public key Conventional cryptography also known as symmetric cryptography requires the sender and receiver to share a key a secret piece of information that may be used to encrypt or decrypt a message If this key is secret then nobody other than the sender or receiver may read the message If Alice and the bank know a secret key then they may send each ot
118. ion API Support Testing It is expected that any BES output function or routine should be able to feed the matching BES input function or routine successfully using a range of expected types of input or output data and covering specific data cases known to exist within the BES Integration API Specific testing issues Directory Interface Issues The directory interface expects the input files to be written atomically and to have IAgent process read and write permissions since the extensions will be changed after processing It is required that both the input and output directories exist and have IAgent process read write and execute permissions Named Pipe Interface The named pipe interface expects the input pipe messages to be written atomically and to have the length portion of the message accurately reflect the size of the data portion of the message Invalid length values will cause unpredictable results and may cause problems with all further input messages It is required that both the input and output pipes exist and have IAgent process read and write permissions set On some operating systems the maximum length of a FIFO may limit the size of IA messages supported If this is the case and IA message can exceed this system limit than use of another Integration API is recommended August 2003 Page 58 version 2 3 2 IAgent User s Guide Administration Socket Interface The socket interface expects the input messages to be written
119. ists The second message will not generate a pending receipt record IAgent allows a third party or external process to send an external receipt message to the remote trading partner through Agent system see the receipt message format in Chapter 16 These receipt messages will not create a pending receipt record and therefore will not be able to timeout or alert the user if no matching initial message exists Receipt Modes IAgent supports two receipt modes internal and external Only a single mode will be used for all trading partner communication Internal Receipt Mode Internal Receipt Mode Data Flow EDI Message Figure 7 Internal Receipt Mode Data Flow The Internal Receipt Mode is as described in the TCIF standard and can be though of as the automatic mode The IAgent system will generate the appropriate pending receipt for each outbound IA EDI message and will send the appropriate receipt back for each IA EDI message it receives IA EDI messages sent which do not receive an acknowledging receipt within the trading partner specific receipt timeout period will be determined to be undeliverable and logged as such August 2003 Page 42 version 2 3 2 IAgent User s Guide Configuration External Receipt Mode External Receipt Mode Data Flow Figure 8 External Receipt Mode Data Flow The External Receipt Mode allows an external program or process not supplied to generate the response receipt
120. ite FIFO store length my binaryl pack N SIAlength store priority my binary2 pack N SIApriority write it all print FIFO IAlength SIApriority 1Adata close FIFO sleep 2 to avoid dup signals Example 18 Named Pipe API Writer Example August 2003 Page 61 version 2 3 2 IAgent User s Guide Administration Socket API Code Samples Socket Reader Example my iaddr gethostbyname frodo my proto getprotobyname tcp my port 6669 my paddr sockaddr in 0 iaddr socket SOCKET INET SOCK STREAM proto die socket connect SOCKET paddr Il die bind read length my binary read SOCKET binary 4 my IAlength unpack N binary read priority my binary read SOCKET binary 2 my IApriority unpack N binary read data read SOCKET IAdata IAlength Example 19 Socket API Reader Example August 2003 Page 62 version 2 3 2 IAgent User s Guide Administration Socket API Writer Example my proto getprotobyname tcp my port 6669 socket SOCKET INET SOCK STREAM proto die socket setsockopt SOCKET SOL SOCKET SO REUSEADDR pack 1 Il die setsockopt bind SOCKET sockaddr in port INADDR ANY II die bind listen SOCKET SOMAXCONN die listen my paddr accept CLIENT SOCKET store length my binaryl pac
121. k N SIAlength store priority my binary2 pack N SIApriority write it all print CLIENT IAlength IApriority IAdata close CLIENT Example 20 Socket API Writer Example August 2003 Page 63 version 2 3 2 IAgent User s Guide Administration Tibco API Code Samples Additional example code is provided with the Tibco product These examples use the Tibco RV 5 x interface Tibco API Reader Example use Rv subjectname iagent tibco server message versionl 1 my IAmessage my S IAlength my IA priority Callback sub to print the messages Sub my callback my session name replyName msgType msgSize msg arg _ if msgType RVMSG_RVMSG then look for our three fields IA message length ret rvmsg_Get session msg length msgType msgSize SIAlength die rvmsg_Get ret length n unless ret RVMSG_OK IA message priority ret rvmsg_Get session msg priority msgType msgSize IApriority die rvmsg_Get ret priority n unless ret RVMSG_OK IA message data ret rvmsg_Get session msg data msgType msgSize IAmessage die rvmsg_Get ret data n unless ret RVMSG_OK Initialize the rv session ret rv_Init session die rv_Init ret n unless ret RV_OK Listen for subject name ret rv_ListenSubject session sub_id subjectname amp my_callback 0 die rv_ListenSubject n unless ret
122. k layer protocol e g TCP IP and the application protocol layer e g HTTP or IAP SSL provides for secure communication between client and server by allowing mutual authentication the use of digital signatures for integrity and encryption for privacy The protocol is designed to support a range of choices for specific algorithms used for cryptography digests and signatures This allows algorithm selection for specific servers to be made based on legal export or other concerns and also enables the protocol to take advantage of new algorithms Choices are negotiated between client and server at the start of establishing a protocol session There are a number of versions of the SSL protocol primarily version 2 0 and 3 0 One of the benefits in SSL 3 0 is that it adds support of certificate chain loading This feature allows a server to pass a server certificate along with issuer certificates to the browser Chain loading also permits the browser to validate the server certificate even if Certificate Authority certificates are not installed for the intermediate issuers since they are included in the certificate chain SSL 3 0 is the basis for the Transport Layer Security TLS protocol standard currently in development by the Internet Engineering Task Force IETF Session Establishment The SSL session is established by following a handshake sequence between client and server This sequence may vary depending on whether the server is confi
123. le 36 Example 37 Example 38 Example 39 Example 40 Example 41 Example 42 Example 43 August 2003 IAgent User s Guide Preface An example of an EDI Input message ese ee nasa e Ie 47 An example of a typical ISA EDI Segment 2 222222 2 42 48 An example of a Basic Receipt input 48 An example of an Integrity Receipt input 48 An example of a Signed Receipt input message esse es ee se ee GR ee GR ee Re ee A8 An example of a Defined status input message 2 49 An example of a Custom status input message 49 A typical ISA EDL Segment oreet e utet aceite 50 An example of an EDI output 2 112 1 1102 4 2 0 74 4 4244 142454 ds se 50 example of a Basic Receipt output 51 An example of an Integrity Receipt output 000 51 example of a Signed Receipt output message 51 An example of a Defined status output message iese ee ee Ge ee GR ee Re ee 52 An example of a Custom status output message ies see ee ee Re RR Re 52 Directory API Reader Example 60 Directory API Writer E ie et 60 Named Pi
124. le of Debug SSL Handshake State Messages Client side 20000417 035850 iagent 5348 calling SSL accept 20000417 035850 iagent 5348 Starting SSL handshake with SSL accept 20000417 035850 iagent 5348 SSL accept before accept initialization 20000417 035850 iagent 5348 SSL accept SSLv3 read client hello 20000417 035850 iagent 5348 SSL accept SSLv3 write server hello A 20000417 035850 iagent 5348 SSL accept SSLv3 write certificate A 20000417 035850 iagent 5348 SSL accept SSLv3 write certificate request A 20000417 035851 iagent 5348 SSL accept SSLv3 flush data 20000417 035851 iagent 5348 verify cert 20000417 035851 iagent 5348 SSL accept SSLv3 read client certificate A 20000417 035852 iagent 5348 SSL accept SSLv3 read client key exchange A 20000417 035852 iagent 5348 SSL accept SSLv3 read certificate verify 20000417 035852 iagent 5348 SSL accept SSLv3 read finished A 20000417 035852 iagent 5348 SSL accept SSLv3 write change cipher spec 20000417 035852 iagent 5348 SSL accept SSLv3 write finished A 20000417 035852 iagent 5348 SSL accept SSLv3 flush data 20000417 035852 iagent 5348 DEBUG Getting Client s certificate 20000417 035852 iagent 5348 SSL connection using DES CBC3 SHA 20000417 035852 iagent 5348 SSL Handshake DONE Example 29 An example of Debug 551 Handshake State Messages Server side August 2003 Page 80 version 2 3 2
125. lic key to the certificate authority to be incorporated into a certificate request Our utility csr does just that Once a signed certificate has been created using the Certificate Authority this client certificate must be installed in the client so that the client may present it when needed In Agent operation the client certificate is often also called the machine certificate The general steps for creating a client certificate are as follows User generates a key pair public and private key 2 Private key is stored locally 3 User enters identification information and public key into a certificate signing request CSR 4 Submission of the request to a Certificate Authority 4 Certificate Authority verifies identity of user 4 2 Creates a valid certificate good for only a specific period of time and for a specific unique CN 4 3 And returns the new certificate back to the user The Gen csr Certificate Environment and Configuration File Gen csr Generate Certificate Signing Request is the supplied utility which builds RSA PKCS 1 key pairs and PKCS 10 certificate signing requests in either PEM or DER format The following examples assume you ehave installed Agent system eare working in the opt iagent directory eAnd have available the Common Name CN of your local trading partner Gen csr uses a configuration file request cnf which supports multiple sections so one configuration file may be used for several
126. loading CTL fill stuff 20000417 035850 iagent 5355 only loaded CTX return 0 20000417 035850 iagent 5355 CACHED SESSION lookup 20000417 035850 iagent 5355 GENERATING A NEW SESSION 0 20000417 035850 iagent 5355 CTX already loaded skipping CTL fill stuff 20000417 035850 iagent 5355 SSL is NULL loading SSL with SSL new 20000417 035850 iagent 5355 SSL connect before connect initialization 20000417 035850 iagent 5355 SSL connect SSLv3 write client hello A 20000417 035851 iagent 5355 SSL connect SSLv3 read server hello A 20000417 035851 iagent 5355 PKI verify cert 20000417 035851 iagent 5355 SSL connect SSLv3 read server certificate A 20000417 035851 iagent 5355 SSL connect SSLv3 read server certificate request 20000417 035851 iagent 5355 SSL connect SSLv3 read server done A 20000417 035851 iagent 5355 SSL connect SSLv3 write client certificate A 20000417 035851 iagent 5355 SSL connect SSLv3 write client key exchange 20000417 035851 iagent 5355 SSL connect SSLv3 write certificate verify 20000417 035851 iagent 5355 SSL connect SSLv3 write change cipher spec 20000417 035851 iagent 5355 SSL connect SSLv3 write finished A 20000417 035851 iagent 5355 SSL connect SSLv3 flush data 20000417 035852 iagent 5355 SSL connect SSLv3 read finished A 20000417 035852 iagent 5355 SSL connection using DES CBC3 SHA 20000417 035852 iagent 5355 SSL Session 20000417 035852 iagent 5355 SSL Handshake DONE Example 28 An examp
127. ly required for operation of the IAgent machine FTP should be replaced with SCP and telnet should be replaced with SSH It is recommended that all indirect network access particularly mounted or shared network file systems e g SMB NFS AFS DFS should not be used for both performance and security reasons Suggested Firewall rules set The firewall rules should only allow the specific trading partners IP addresses access to only the local IAgent via specific standard and high priority ports other access should be blocked form these addresses ICMP ping packets should probably not be allowed due to the amount of information that can be determined from ICMP fragment pings More information on this interesting but hazardous loophole can be found at www insecure com The use of Network Address Translation NAT should be used if available This would allow outside elements including remote IA trading partners to access virtual IP addresses which translate to specific real internal to the local LAN IP addresses The use of a Demilitarized Zone DMZ external network is suggested August 2003 Page 92 version 2 3 2 IAgent User s Guide Administration CHAPTER 30 HOW TO GET HELP This chapter explains how to contact Lymeware Product Support if you need assistance with your IAgent product Scope of Support Services Lymeware Product Support can provide assistance and information for the following Installing the IAgent p
128. me Signature Period of Validity Not Before Date Not After Date Administrative Information Version Serial Number Optional Requestor s Extensions Extended Information Optional Issuer s Extensions Optional Application Extensions Table 18 Certificate Information Elements A distinguished name is used to provide an identity in a specific context for instance an individual might have a personal certificate as well as one for their identity as an employee Distinguished names are defined by the X 509 standard that defines the fields field names and abbreviations used to refer to the fields August 2003 Page 104 version 2 3 2 IAgent User s Guide Appendixes Field Abbreviation Description Example Name being certified Typically the fully e Common Name CN qualified domain name FQDN e g lymeware com host company com Organization or Company O Name is associated with this organization O Lymeware Corporation Name is associated with this organization unit such as a department This field is often blank Ep Organizational Unit OU City Locality L Name is located in this City L Old Lyme State Province SP Name is located in this State or Province SP Connecticut Country C Name is located in this Country ISO code C US Table 19 Distinguished Name Information A Certificate Authority may define a policy specifying which distinguished field names are optional and which a
129. n APIs Tik Directory ie Server Client IP Sodket Figure 3 IAgent Integration APIs File Directory interface atomically reads and writes ASCII text files EDI messages in standard ASC X 12 formats The Named Pipe interface reads from and writes to specific user defined named pipes or FIFOs IP Socket interface reads from a single user defined input socket and writes to a single output socket The customer processes reading writing to this interface do not have to reside on the same platform as the IAgent system optional Tibco TIB Rendezvous message bus interface reads input Tibco messages with a single subscriber and writes output Tibco messages with multiple publishers supporting multiple platforms August 2003 Page 6 version 2 3 2 IAgent User s Guide Introduction User defined connectivity Connectivity IA Trading partners must share TCP IP connectivity either through a direct private connection between both trading partners e g Frame Relay or over a shared public network such as the Internet Each trading partner must provide the other partner their unique IP addresses and port assignments for the location to send and receive IA messages e g EDI Pre Order and Ordering or other message types IAgent uses standard SSLv3 to provide the secured transport over the TCP IP connection The specific agreed method to connect with TCP IP and other IA implementation issues such as l
130. nd time 040013 20000417 040014 iagent 5348 Total Message Transport time 01 1 Seconds August 2003 Example 39 An example of IA Timer Messages Page 86 version 2 3 2 IAgent User s Guide Administration CHAPTER 28 PRODUCT ERROR MESSAGES Descriptions and possible solutions for specific IAgent Transaction Errors CANNOT ACCEPT CLIENT HANDSHAKE This message is usually caused by SSL version or cipher mismatch from IA Client or Remote IA CANNOT ALLOCATE CLIENT SOCKET This message is caused by system resource problems CANNOT ALLOCATE CTX This message is caused by system resource problems CANNOT ALLOCATE SSLCTX This message is caused by system resource problems CANNOT CONNECT TO REMOTE SERVER This message can be caused by several issues including connectivity invalid trading partner configuration settings and invalid EDI data Connectivity Issues The IA gent client processes need to be able to connect to the remote IA server using the ports found in the Trading Partner configuration file Connections may have problems if any of the following is true The remote IA is not reachable via TCP IP For successful operation all remote IA servers must be reachable via the local IA client machine Dialup or intermittent connections are not supported Possible problems the remote IA server is down or not connected to the IP network the local machine has lost it s own connection to the network or the specific
131. nderlying protocol The encapsulation of SSL control protocols by the record protocol means that if an active session is renegotiated the control protocols will be transmitted securely If there were no session before then the Null cipher suite is used which means there is no encryption and messages have no integrity digests until the session has been established Data Transfer The SSL Record Protocol is used to transfer application and SSL Control data between the client and server possibly fragmenting this data into smaller units or combining multiple higher level protocol data messages into single units It may compress attach digest signatures and encrypt these units before transmitting them using the underlying reliable transport protocol Note currently all major SSL implementations lack support for compression The foregoing has only been an introduction if you really want to see the protocol details then read the Secure Socket Layer protocol standard The SSL Protocol Version 3 November 18 1996 Netscape Communications http wp netscape com eng ss13 August 2003 Page 15 version 2 3 2 IAgent User s Guide Installation Part 2 lAgent Installation Part 2 of this manual contains a step by step description of IAgent product installation including pre installation and post installation tasks August 2003 Page 16 version 2 3 2 IAgent User s Guide Installation CHAPTER 4 INSTALLATION OVERVIEW The installation
132. ndix C August 2003 Page 29 version 2 3 2 IAgent User s Guide Configuration lAgent command line arguments The second way to modify the way the IAgent system operates is with command line arguments These are usually only used during testing and are not used in the automatic startup during system boot see Chapter 25 for more information on IAgent startup options The following table lists all the available Agent command line arguments Each argument may also appear in the system configuration file iagent conf but will be overridden by any identical argument on the command line A sloppyallow Flag to allow receipt of any type of messages from active trading partners for testing purposes only B sloppyinactive Flag to allow receipt of message from inactive trading partners for testing purposes only C ENTRIES cachesize ENTRIES Server session cache size in session entries D PATH outdir PATH Output directory name for Directory interface only F FILENAME file FILENAME Input or output file name for File interface only Iy ignoredupreceipts Flag to allow duplicate receipts without triggering errors for testing purposes only L SECONDS loopbackdelay SECONDS Debug loopback delay in seconds for testing purposes only O oneshot Flag to force processing of only a single transaction P PIPENAME outpip
133. nges resulting from bug reports may be included in future releases Support for products purchased from our distributors For all products purchased from our distributors all questions with the notable exception of bug reports should be sent directly to the distributor If your distributor does not offer a service contract then one may be obtained from Lymeware Corporation Please send all such inquiries to Sales 9 Iymeware com August 2003 xviii version 2 3 2 IAgent User s Guide Preface Documentation nvention Conve f ons This table describes typographic conventions used within this Typographic conventions document Convention Use Italics Italics type is used for titles of other manuals and documents and for files and file extensions iagent conf file Bold Bold type is used for key terms the first time they are used within a chapter Example The Common Name is Curier New fontis used for commands to be Font typed by the user or for system commands or utilities Example Type iagent m I dir Angle Angle brackets indicate variable brackets information such as input file names created by the user Example lt inputfilename gt edi Table 1 Typographic conventions August 2003 xix version 2 3 2 IAgent User s Guide Preface Symbols used within syntax statements This table describes symbols used within program syntax statements used within this
134. not be in X 12 EDI format The message will use a newline ASCII 0x0a as a segment terminator A typical ISA segment is as follows line NOT wrapped ISA 00 IAGENT 00 TEST ZZ LWC 7 ZZ LWC TEST 990629 1248 U 00307 000002317 0 T Es Example 8 A typical ISA EDI segment A typical output EDI message is as follows lines NOT wrapped ISA 00 IAGENT 00 TEST 227 1 744 TWO 990629 1248 U 00303 000000001 0 T GS PO CLECAPP LWC 990629 1248 000001 X 003030 5T 864 000000001 BMG 28 DTM 097 990629 124849 21 19 IT 000000001 SG This is a test message from TP ONE to TP TWO over IAgent MSG This is a test message line 2 SG This is a test message line 3 SG This is a test message line 4 SG This is a test message line 5 SG This is a test message line 6 SG This is a test message line 7 SG This is a test message line 8 SG This is a test message line 9 SG This is a test message line 10 SG This is a test message line 11 MSG This is a test message line 12 SG This is a test message line 13 SG This is a test message line 14 SG This is a test message line 15 SG This is a test message line 16 SG This is a test message line 17 SG This is a test message line 18 SG This is a test message line 19 SG This is a test message line 20 0 5E 26 000000001 GE 1 000001 IEA 1 000000001
135. nt or server will exit with a Fatal Error On input the client process reads only files with an edi extension for standard priority or a hpri extension for hi priority Processed files will have their extensions changed to either sent if successfully sent or to notsent if handshake or socket errors are encountered On output for any server process all files will be generated for processing by a downstream EDI translator files are written with either an edi extension for standard priority or a hpri extension for hi priority in ASCII text mode and are saved atomically To assure atomic creation of input files it is recommended that the files be built with a temporary extension not edi or hpri and after the full message has been created rename the file with edi or hpri extension The Move mv user command is known to be atomic on all IAgent supported environments The input outbound directory may be set with the a PATH or indir PATH options The output inbound directory may be set with the D PATH or outdir PATH options trading partner messages will exist and be processed in the same above directories Sample code to support the Directory Interface is supplied in Chapter 23 August 2003 Page 53 version 2 3 2 IAgent User s Guide Administration CHAPTER 19 NAMED PIPE INTEGRATION Named Pipe Interface Mode The named pipe interface mode reads and writes all messages
136. nts 3l Table 6 Agent Command Line Arguments concluded 32 Table 7 Default Agent configuration values bre ire eris stu pete Fe an Gone 33 Table 8 Trading Partner Configuration Fields esee 35 Table 9 Trading Partner Configuration Fields continued 36 Table 10 Interfaces supported by Dei oet nae epe iun eaae nc N 46 Table 11 BES Locations supported by AE eo eode S A6 Table 12 Transaction Log Message Type Numbers ee ee ee ee GR ee 72 Table 13 Agent Error Numbers e RR Rede PURSE PUPA E UN 73 Table 14 Agent Error Numbers 74 Table 5 Debug Levels Masks 78 Table 16 Suggested Security Tools ter SMSe Ns hae N SR sodas ROSAS eda gus 91 Table 17 gent Product WOrksheets AG Ee 96 Table 18 Certificate Information Elements 104 Table 19 Distinguished Name Information a nere N eek 105 Table 20 National International Internet and Industry Standards used by this product 127 Table 21 National International Internet and Industry Standards used by this product concluded RE MUI E c ce capot RE ER DE 128 Ta
137. o be done 1 login to the machine as root 2 change the working directory to opt iagent 3 stop the IAgent system if it was running 4 start the IAgent system with the new debug startup script as detailed below August 2003 Page 69 version 2 3 2 IAgent User s Guide Administration The root user will then be able to start stop the IAgent system in debug mode manually by typing OT bin debugia start bin debugia stop Log and Output Files The IAgent system and processes generate several different types of log and output files The log files consist of A system wide output log file iagent 10g which contains almost everything that is written to the console stdout including verbose messages A system wide error log file iagent err which contains all error messages written to the console stderr including warnings debug statements and fatal error messages A system wide alert log file iagent alert which contains all major error alerts as single line alert entries This log may be automatically inspected to alert support personnel of IAgent system distress that should be immediately attended to Process specific transaction logs one per major process which log the final status of a transaction either inbound to the server s or outbound from the client s These logs are called client trans log receipt trans log server trans log and hipri trans log The log contents are described in Chap
138. on to grant such a license This Manual is O Copyright 1999 2003 Lymeware Corporation Old Lyme Connecticut USA Rights Reserved 2003 IAUG232 0011 IAgent User s Guide Preface ANY UNAUTHORIZED DUPLICATION OF THIS DOCUMENT SHALL BE AN INFRINGEMENT OF COPYRIGHT Trade Secret Notice This document the software it describes and the information and know how they contain constitute the proprietary confidential and valuable trade secret information of Lymeware Corporation its affiliated companies or its or their licensors and may not be used for any unauthorized purpose or disclosed to others without the prior written permission of the applicable Lymeware Corporation entity Page iv IAgent User s Guide Preface Page IAgent User s Guide Preface Contents EIS TE SE ne ene eme XI DIS TOE FIGURES iS p tO Eee todas XIII LIST O TABLES musto is ee eae sua eo Ge XV SOETWARE VERSION OS SE Re EE eae DS GE EE RA XV READBRSHIP nieve t uH E RE XV SCOPEOOE THIS GUIDE I Te FERRE XV MANUAE REVISION HISTORY Ee agp Ge De execs Seven gue i ee GE Ee Re SUPPORT QUESTIONS AND BUG 2 4 42 44 0000 Ge ee Re ee ER Re sr GR ee ee ER
139. on trading partner s own IA server via a TCP IP connection either a dedicated connection Frame Relay ATM etc or a public connection such as the Internet After the initial TCP IP connection the Client sets up a validated secure connection to the destination trading partner s IA Server via SSL and sends the IA message in a August 2003 Page 8 version 2 3 2 IAgent User s Guide Introduction shared encrypted form The Client then breaks down the secure connection and disconnects from the Server The IA Server waits for a remote IA Client connection request When such request is received the Server sets up a validated secure connection and reads the encrypted IA message sent by the remote Client The Server parses and validates the message contents and if valid sends the body of the message in EDI format to a backend EDI system BES for further processing August 2003 Page 9 version 2 3 2 IAgent User s Guide Introduction CHAPTER 3 INTRODUCTION TO SSL As an introduction this chapter is aimed at readers who are familiar with the Web HTTP and TCP IP but are not security experts It is not intended to be a definitive guide to the SSL protocol nor does it discuss specific techniques for managing certificates in an organization Rather it is intended to provide a common background for IAgent users by pulling together various concepts definitions and examples as a starting point for further exploration For more detailed informat
140. pe API Reader Example iiie se ese Ede a ts 61 Named Pipe API Writer Example 2e Ae GS oet ie tte 61 Socket APU Reader Example va idis ddp de edlen die didus 62 Socket API Writer Example issie sd eese m Uti REATUS Ede ee Urea de ee ede Ke dee 63 Tibco API Reader Example 5 e tud me ated quis 64 Tibee APL Writer Bxample se tae 65 Starting Agent as system dae HOD secures EG 68 Starting Agent form command line in Combined mode 68 Starting IAgent system in standalone mode see 69 Another Startup example a c esca e aerei au N es ee Eg Deed 69 An example of Basic Debug Messages oec pecia ege Sepa bou qe GE DE 29 An example of Debug SSL Handshake State Messages Client side 80 An example of Debug SSL Handshake State Messages Server side 80 An example of Debug Transaction Data Messages eee 8l An example of Debug Certificate Messages Client Side 8l An example of Debug Certificate Messages Server 14 22 2 222 1 82 An example of Debug Certificate Messages Server side continued 83 An example of Debug ASN1 Messages eie eee idera uite pene 84 An example of Debug Parsed ASNI Messages esee 84 An example of Debug Parsed ASN
141. port PORT High priority server port for Hipri Server process only i TYPE interface TYPE Input client or output server interface supported May be any of the following file dir pipe socket or tibco j MESSAGE NAME intibco MESSAGE NAME Input tibco message subject name for Tibco interface only k FILENAME key FILENAME key file FILENAME Own local private key file in PEM format m MODE mode MODE IAgent mode either F full S standalone server only or C standalone client only Table 5 IAgent Command Line Arguments continued August 2003 Page 31 version 2 3 2 IAgent User s Guide Configuration n SECONDS dirpolldelay SECONDS Client directory poll delay in seconds for Directory interface only p PORT stdport PORT port PORT Standard server port for Std Server process only vhack Self signed issuer certificate verify hack flag r Flag to force RAW text not ASN1 message transfer t FILENAME TPconfig FILENAME tpartner FILENAME IAgent trading partner configuration file name default is tpartner conf usage help Displays this usage page V verbos Flag to force A LOT of logging to stdout and log files sendstatus Flag to force automatic sending of IAstatus messages when internal errors oc
142. pports multiple levels of message validation on each transaction customized by trading partner lAgent product benefits eClient Server Architecture with Public Standards including TCIF IETF and RSA support eNear Real time High Volume Performance up to 30 transactions a minute eMulti threaded and Scaleable Design eCustomer centric Security and Auditing eElimination of EDI Value Added Network V AN fees August 2003 Page 5 version 2 3 2 IAgent User s Guide Introduction eSimple Operational Support System OSS Integration via Multiple Application Program Interfaces Integration APIs eWeb based Monitoring eOptionally supports the Tibco TIB Rendezvous for BES support eUses the popular OpenSSL cryptography toolkit Simple Integration is the key The underlying structure of the TCIF IA standard and Agent design is a symmetrical client server configuration where both the client and server functions are required at each implementation Integrating these client and server components into an existing OSS or backend system is key to performance scalability and deployment time Agent provides Integration APIs designed for simple integration with common application interfaces The four supported integration APIs for internal message input and output transfer include the File Directory interface the Named Pipe interface the IP Socket interface and the Tibco TIB Rendezvous message bus interface Integratio
143. purposes The req section of the configuration file is August 2003 Page 106 version 2 3 2 IAgent User s Guide Appendixes used when creating certificate requests with csr and supplies defaults and length limits for the various distinguished name fields Example 40 In our examples it has the configuration as shown in Gen csr example configuration file req default bits default_keyfile distinguished_name attributes 768 req_distinguished_name countryName countryName default countryName min countryName max stateOrProvinceName stateOrProvinceName default req attributes challengePassword chal This is being used for generation of certificate reguests RANDFILE SENV HOME rnd privkey pem req distinguished name req attributes Connecticut localityName 0 organizationName 0 organizationName default organizationalUnitName organizationalUnitName_default commonName commonName_max emailAddress emailAddress max challenge password lengePassword min hallengePassword max Country Name 2 letter code US 2 2 State or Province Name full name Locality Name e g city Organization Name e g Lymeware Corporation company Unit Name Organizational Common Name LS e g YOUR FQDN or CN Email Address 40 4 2
144. quest Form The license file must be installed at opt iagent as license dat and should be owned by root 2 Installing local certificates and keys At a minimum a single X 509 Server certificate and private key pair is required to operate the IAgent system A minimum of the signing CA Certificate will also be required Chapter 8 of this manual covers Certificate Signing Request CSR and Key generation and installation in detail Creating the lAgent configuration file Chapter 9 of this manual covers IAgent configuration management in detail 4 Verifying PRNGD installation and configuration Sun Solaris versions only Cryptographic software needs a source of unpredictable data to work correctly Due to requirements of the underlying cryptography toolkit OpenSSL this version of Agent requires use of a secure pseudo random number generator to seed and supply entropy to specific cryptographic functions Because all target systems do not supply this facility as a standard system service additional software is provided to perform these services This software generates pseudo random entropy from collecting data and reading logs from several system processes and then digests the data into some form of randomness Lymeware provides August 2003 Page 21 version 2 3 2 IAgent User s Guide Installation PRNGD and as solutions to this requirement Note It is required that one of the two entropy programs is installed configured
145. r debug the problem from each side of the connection to repair the required connectivity See Appendix D for a sample Trading Partner connectivity test plan See Chapter 29 for a sample Firewall rules set August 2003 Page 38 version 2 3 2 IAgent User s Guide Configuration CHAPTER 12 MULTIPLE TRADING PARTNER ISSUES Multiple trading partners are both supported and encouraged in the IAgent system with the following caveats Remote Trading Partners may but are not required to Have different port assignments Have different IP Addresses Have different message and receipt settings Have different Client Certificates Have different signing CA Certificates Each Remote Trading Partner must Have different trading partner identifiers in both the ISA segment of EDI messages and in the trading partner file Support the same single Client certificate and signing CA certificate from the local IAgent system Support the same trading partner identity used by the local IAgent system Note An IAgent system only supports a single local trading partner Additional IAgent products typically on other machines will be required to support multiple local trading partners A Trading Partner Worksheet should be completed for the local machine A copy of this worksheet should be provided to all remote trading partners prior to connectivity testing These issues should be agreed to and captured by both trading partners in
146. re required It may also place requirements upon the field contents as may users of certificates As an example a Netscape browser requires that the Common Name for a certificate representing a server have a name which matches a regular expression for the domain name of that server such as www lymeware com The binary format of a certificate is defined using the ASN 1 notation This notation defines how to specify the contents and encoding rules define how this information is translated into binary form The binary encoding of the certificate is defined using Distinguished Encoding Rules DER which are based on the more general Basic Encoding Rules BER For those transmissions that cannot handle binary the binary form may be translated into an ASCII form by using base 64 encoding This encoded version is also called PEM from Privacy Enhanced Mail encoded when placed between the following lines BEGIN CERTIFICATE END CERTIFICATE Certificate Authorities By first verifying the information in a certificate request before granting the certificate the Certificate Authority assures the identity of the private key owner of a key pair For instance if Alice requests a personal certificate the Certificate Authority must first make sure that Alice really is the person the certificate request claims But what is a Root Level Certificate Authority As noted earlier each certificate requir
147. request template fil text text form of request nodes don t encrypt the output key asnl kludge Output the request in a format have been reported as requiring Example 42 Command line arguments for gen csr PEM text base 64 certificate signing request may be created as shown in Example 42 Or a DER binary ASN 1 certificate signing request may be created as shown in Example 43 August 2003 Page 108 version 2 3 2 IAgent User s Guide Appendixes tools gen csr keyout newkey pem reqout newreq pem nodes gen csr v1 4 generates X 509v3 certificate signing requests CSRs and RSA key pairs Copyright c 2001 Lymeware Corporation All rights reserved using OpenSSL 0 9 6b This program includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit http www OpenSSL org This program includes cryptographic software written by Eric Young eay cryptsoft com Using configuration from opt iagent request cnf Generating a 768 bit RSA private key p eth PETF writing new private key to newkey pem You are about to be asked to enter information that will be incorporated into your certificate request What you are about to enter is what is called a Distinguished Name or a DN There are quite a few fields but you can leave some blank For some fields there will be a default value If you enter the field will be left blank Country Name 2 letter code
148. ress also has the alias CustomerService lymeware com Support lymeware com for all technical inquires and problem reports including documentation issues from customers with support contracts Customers should include relevant contact details including company name and phone number in initial message to speed processing Messages that are continuations of an existing problem report should include the problem report ID in the subject line Customers without support contracts with Lymeware Corporation should not use this address but should contact their distributor directly This address is monitored daily and all messages will be responded to See Chapter 30 for more support information and options Sales ymeware com for all sales related inquires and similar communication This address is monitored daily and all messages will be responded to Bugs lymeware com for bug reports and documentation problems Bug reports on software releases are always welcome These may be sent by any means but e mail to the bug reporting address listed above is preferred Please send proposed fixes and successful workarounds with the report if possible Additional useful information would include IAgent software version hardware description operating system version and patches screen dumps relevant sections of logs and configuration files and failed messages files Any reports will be acknowledged but further action is not guaranteed Any cha
149. ries will need to have a separate section in the configuration file as shown below Each trading partner section should contain the following fields Configuration Field Description partner id This is a internal trading partner identifier and does not reflect any EDI value local partner id This is the local trading partner identifier as found in the EDI ISAO5 or ISA06 segment 15 characters maximum as ANSI X 12 remote partner id This is the remote trading partner identifier as found in the EDI 15 05 or ISA06 segment 15 characters maximum as per ANSI X 12 certificate common This is the CommonName CN as found in the Client Certificate sent name from the remote Trading Partner ip address trading partner s IP address as a string AAA BBB CCC DDD Table 8 Trading Partner Configuration Fields August 2003 Page 35 version 2 3 2 IAgent User s Guide Configuration standard ip port trading partner s standard IA server IP port address on same address as above hipri ip port trading partner s high priority IA server IP port address on same address as above Session timeout Connection session cache timeout in seconds If 0 then no resumable sessions supported for this trading partner ja message from tp The IA EDI Message Type supported from this Trading Partner May be any of the following BASIC EDI Basic EDI message INTEGRITY E
150. roduct IAgent product questions Software revisions and upgrades Implementing a specific feature How to use the IAgent product The status of your support call Requests for product enhancement Unfortunately we cannot assist you with problems involving the following but we may be able to suggest a next step or another vendor to call Your hardware Your operating system or other system software Your application or user written programs Software not developed by Lymeware Corporation Scripts written by Lymeware consultants service partners or other third parties Try this first Before you call Lymeware Product Support use your software manuals including this manual to locate the section that documents the program or feature where you are having problems The documentation may explain the software s behavior or give you insight to help you solve the problem August 2003 Page 93 version 2 3 2 IAgent User s Guide Administration Contact Lymeware Product Support Two e mail addresses are available for IAgent product support or to report a potential bug in the software or documentation Please use the following addresses Support lymeware com for all technical inquires and problem reports including documentation issues from customers with support contracts Customers should include relevant contact details including company name and phone number in initial message to speed processing Messages that are continuations of an exist
151. routing 1 Find the remote trading partner s server IP address from the Trading Partner Worksheet for this example we will use 191 168 1 1 2 Find the remote trading partner s standard priority port also from the Trading Partner Worksheet we will use the IA default of 6999 3 Log in to your local machine as root August 2003 Page 37 version 2 3 2 IAgent User s Guide Configuration 4 telnet to the remote trading partner s machine with the following command telnet P address port so in our example the command line would look like this telnet 191 168 1 1 6999 5 At this point of two things will happen The connection will either be allowed or rejected If rejected th en an error message similar to this will be displayed telnet Unable to connect to remote host Connection refused Otherwise a connection message will be displayed which means that TCP IP connectivity does exist To exit telnet type Ctrl the control key and the right square bracket key and at the telnet prompt type exit 6 Repeat Steps 3 through 5 using the High Priority port from the remote trading partner Simple TCP IP connectivity should now be established Several reasons may be the cause of Connection refused message They include incorrect IP address and port numbers invalid firewall rule sets bad routing which could be caused by a host of sources It is usually a good idea to have a network administrato
152. rt pem Path to CA certificates in PEM format CApath ca certs Certificate authority CA file in PEM format CAfile CAcert pem August 2003 Page 112 version 2 3 2 IAgent User s Guide Appendixes stdport 1111 Own private key file in PEM format key client keys LWCTkey pem Own certificate file in PEM format cert client certs LWCTcert pem Path to CA certificates in PEM forma CApath ca certs Certificate authority CA file in CAfile CAcert pem FERE RE EE EE HE E E TE AE FE FE FE HE HE E E E E E AE E E E E E E E E E E E E E E H LWC_TEST_hipri_server High priority server port hipriport 2222 key client keys LWCTkey pem Own certificate file in PEM format 11 CAcert pem EOF iagent conf FEFE E RR ER RR RR RR RR RR E E RR RR RR HE HEHE IR LWC TEST rec client client keys LWCTkey pem Own certificate file in PEM format cert client certs LWCTcert pem Path to CA certificates in PEM format CApath ca certs Certificate authority CA file in CAfile CAcert pem E E E E E E E E E E E E E LWC_TEST_std_server Standard server port cert client certs LWCTcert pem Path to CA certificates in PEM format CApath ca certs Certificate authority CA file in
153. s 1988 509 Recommendation 509 Directory Authentication Framework 1988 520 Recommendation 520 Directory Selected Attribute 1988 RFC1421 Privacy Enhancement for Internet Electronic Mail Part I Message Encryption and Authentication Procedures February 1993 RFC1422 S Kent Privacy Enhancement for Internet Electronic Mail Part II Certificate Based Key Management February 1993 PKCS 1 RSA Laboratories PKCS 1 RSA Cryptography Standard version 2 0 September 1998 PKCS 6 RSA Laboratories PKCS 6 Extended Certificate Syntax Standard version 1 5 November 1993 PKCS 7 RSA Laboratories PKCS 7 Cryptographic Message Syntax Standard version 1 5 November 1993 PKCS 8 RSA Laboratories PKCS 48 Private Key Information Syntax Standard version 1 5 November 1993 PKCS 9 RSA Laboratories PKCS 49 Selected Attribute Types version 1 1 November 1993 PKCS 10 RSA Laboratories PKCS 10 Certification Request Syntax Standard version 1 0 November 1993 X 12 5 ANSI ANSI X 12 5 1977 Interchange Control Structure November 24 1997 Table 20 National International Internet and Industry Standards used by this product August 2003 Page 127 version 2 3 2 IAgent User s Guide Appendixes X 12 6 ANSI ANSI X 12 6 1977 Application Control Structures November 24 1997 12 22 ANSI ANSI 12 22 1977 Segment Directory January
154. s downstream OSS local IAgent should stop transmission to peer Trading Partner PING RESPONSE Response to a previous Request ping from a remote trading partner A typical Defined Status output message is as follows IAS LWC TEST STOP Example 13 An example of a Defined status output message The Custom status output message format is IAS trading partner ID custom bit string 32 bits A typical Custom status output message is as follows IAS LWC 7 00000000110011000000000000000000 Example 14 An example of a Custom status output message August 2003 Page 52 version 2 3 2 IAgent User s Guide Administration CHAPTER 18 FILE AND DIRECTORY INTEGRATION File Interface Mode The file interface mode interface file is only supported by the Standalone Client mode C and assumes that the oneshot flag has also been set The Client will require the input file argument to be supplied file FILENAME and expects the file to be an ASCII text file readable by the IAgent process and containing any one of the Input Message Formats The input file is not modified or moved EDI messages starting with ISA will be sent with standard priority Directory Interface Mode The directory interface mode reads and writes all messages as ASCII text files either from or to a specified directory The input or output directory must exist or the specific process clie
155. s started with the etc rc3 d 90prng startup script pm This shell script is used to test the installation of the PRNG The test will display a success message if the PRNG is installed and running correctly Note this script does expect that the PRNG daemon was started with the etc rc3 d 90prng startup script pmloop This shell script is used to test the installation of the PRNG The test will display a success message if the PRNG is installed and running correctly Note this script does expect that the PRNG daemon was started with etc rc3 d 90prng startup script August 2003 Page 122 version 2 3 2 IAgent User s Guide Appendixes debugia This shell script is used to test the installation of the PRNG The test will display a success message if the PRNG is installed and running correctly Note this script does expect that the PRNG daemon was started with the etc rc3 d 90prng startup script August 2003 Page 123 version 2 3 2 IAgent User s Guide Appendixes APPENDIX G GLOSSARY AND ACRONYMS ANSI American National Standards Institute ASN 1 Abstract Syntax Notation One as defined in X 208 ATIS Alliance for Telecommunications Industry Solutions authentication The action of verifying information such as identity ownership or authorization Base 64 see PEM BER Basic Encoding Rules for ASN 1 as defined 209 certificate In cryptography an electronic document binding some pieces of information to
156. settings and options These options describe the setting for the Integration API Interface used and set above other options for other Integration API Interfaces will be ignored if they exist File Interface Options file FILENAME Input file name for File interface only Directory Interface Options dirpolldelay SECONDS Client directory poll delay in seconds for Directory interface only indir PATH Input directory name for Directory interface only August 2003 Page 27 version 2 3 2 IAgent User s Guide Configuration outdir PATH Output directory name for Directory interface only Named Pipe Options inpipe PIPENAME Input pipe name for Pipe interface only outpipe Output pipe name for interface only Socket Interface Options insocket SOCKETPORT Input socket port for Socket interface only outsocket SOCKETADDRESS PORT Output socket address and port for Socket interface only Optional Tibco Interface Options intibco MESSAGE NAME Input tibco message subject name for Tibco interface only outtibco MESSAGE NAME Output tibco message subject name for Tibco interface only Advanced and special options These options are not required for standard operation of your IAgent system and are usually used only during testing sloppyallow 0 1 Flag to allow receipt o
157. software for your machine 4 Requesting the license file 5 Hardware connectivity issues These tasks should be completed in order since subsequent tasks may require information from previous tasks If you encounter any problems with these tasks or instructions refer to Chapter 30 How To Get Help 1 Completing the pre install worksheet See Appendix A for the IAgent Pre Installation Worksheet and instructions for completion Once completed continue to the next task 2 Acquiring root access on the target machine Root or super user access will be required to install the IAgent product on your host machine No additions of special users or groups are required A CD ROM drive is required for standard installation as the IAgent product is supplied on an ISO 9660 format CD ROM Please contact Lymeware or your distributor if a different form of media is required Also sufficient disk storage of 50 Megabytes should be available on a local not network AFS DFS or NFS drive Network drive performance could adversely impact the performance of the installed IAgent system At this time the security suggestions see Chapter 29 should be addressed and implemented 3 Acquiring the correct software for your machine Be sure that the version of the IAgent product is correct both for the hardware and operating system of your target machine For example if your target machine is an Intel platform running Sun Solaris 2 6 then the IAgent Solaris produc
158. stallation Worksheet This worksheet is used to identify all the information and resources required for installing the IAgent product IAgent Connectivity Worksheet This worksheet is used to capture all networking information required to complete a network diagram for the local IAgent system and its connection to remote trading partners IAgent Configuration Worksheet This worksheet is used to identify all required and optional configuration settings and to assist the user in configuration file management Trading Partner Worksheet This worksheet is used to capture all required remote trading partner information to support trading partner management Certificate Request Worksheet This worksheet is used to capture all the usual information required for requesting a certificate from a commercial Certificate Authority License Request Form This form is required for issuing of an evaluation or permanent license required for IAgent operation Problem Reporting Form This form should be used for any problems encountered which can be reported back to Lymeware Table 17 IAgent Product Worksheets These worksheets may be copied for use in maintaining your IAgent system It is expected that completed worksheets will be used during product instillation and configuration and should be saved with other machine documentation for future use Digital version of these worksheets are available at the L
159. standard EDI translator to a Gateway product to a full Operational Support System OSS IAgent just treats all data from the BES as message to send to trading partners and all data from trading partners as messages to send to the BES Integration APIs Figure 9 Backend System to Integration API Interfaces File Directory interface atomically reads and writes ASCII text files EDI messages in standard ASC X 12 formats The Named Pipe interface reads from and writes to specific user defined named pipes or FIFOs IP Socket interface reads from a single user defined input socket and writes to a single output socket The BES processes reading and writing to this interface do not have to reside on the same platform as the IAgent system optional Tibco TIB Rendezvous message bus interface reads input Tibco messages with a single subscriber and writes output Tibco messages with multiple publishers supporting multiple platforms August 2003 Page 45 version 2 3 2 IAgent User s Guide Administration Mode Restrictions Note that not all Integration API interfaces are supported by each of the three system modes Combined or full Standalone Client or Standalone Server The following table lists the restrictions Mode Interfaces Supported Standalone Client File Directory Named Pipe FIFO Socket Tibco Standalone Server Directory Named Pipe FIFO Socket Tib
160. stions below Suggested Security Tools The following tools are strongly suggested for inclusion into a security site maintenance plan and should be used on a periodic basis Tool Name Tool Descriptions Satan Detects insecure system and network configurations Saint Detects insecure system and network configurations Tripwire Intrusion Detection System IDS sudo Monitored root Access SSH Secure Shell Nmap IP Port Scanner Table 16 Suggested Security Tools Certificate and Key Issues Always save your private keys and certificates to an external device floppy tape for archiving Additional Off site archiving is suggested It is suggested to use a minimum of a 768 bit RSA key pair 1024 bits is even more secure and should be used The use of a major commercial third party Certificate Authority is suggested The use of a externally stored domain name service DNS hostname and Common Name in the August 2003 Page 91 version 2 3 2 IAgent User s Guide Administration certificate request is recommended Operating System Issues IAgent does use shared memory in its operation and does require the shared memory and semaphores be enabled to operate properly The minimum shared memory segment size should support at least 128K bytes Other Access Issues It is suggested that all forms of direct network access including telnet rlogin ftp finger rwho etc be minimized to only those specifical
161. t also includes the identification and signature of the Certificate Authority that issued the certificate and the period of time during which the certificate is valid It may have additional information or extensions as well as administrative information for the Certificate Authority s use such as a serial number Certificate Authorities By first verifying the information in a certificate request before granting the certificate the Certificate Authority assures the identity of the private key owner of a key pair For instance if Alice requests a personal certificate the Certificate Authority must first make sure that Alice really is the person the certificate request claims Certificate Chains A Certificate Authority may also issue a certificate for another Certificate Authority When examining a certificate Alice may need to examine the certificate of the issuer for each parent Certificate Authority until reaching one which she has confidence in She may decide to trust only certificates with a limited chain of issuers to reduce her risk of a bad certificate the chain Creating a Root Level CA Certificate As noted earlier each certificate requires an issuer to assert the validity of the identity of the certificate subject up to the top level Certificate Authority CA This presents a problem Since this is who vouches for the certificate of the top level authority which has no issuer In this unique case the certificate is
162. t is not appropriate since this product only supports Solaris running on SPARC platforms If you have any question about which version of IAgent product supports your specific machine and operating system please contact the Lymeware sales team or your distributor for assistance August 2003 Page 18 version 2 3 2 IAgent User s Guide Installation Insure that the target machine has all vendor suggested patches packages updates and or service packs applied A full list of known required updates for supported platforms is listed on the Lymeware web site www lymeware com www lymeware com Install all optional packages and products including the Tibco TIB Rendezvous product at this time The Perl scripting language at least version 5 003 is required for several of the optional utilities located in opt iagent tools It should be installed at this time More information about the Tibco requirements may be found in Chapter 21 4 Requesting the license file A specific license data file will be required to run the IAgent system on your target machine Lymeware or your distributor will supply this license file if a License Request Form see Appendix A is completed and returned to Lymeware or your distributor The license file will be delivered to the Contact E Mail Address within 5 business days 5 Hardware connectivity issues Network TCP IP connectivity is required to successfully communicate with other trading partners and
163. ter 26 The Agent system will create a process ID file PID file iagent pid for the process group of all IAgent processes created It is suggested that all signals sent to the IAgent processes use this file received IA Status messages are saved to text files with a specific file name Transaction Partner ID Status With Status being either test for status TEST messages stop for WAN or OSS stop messages ping for PING response messages or status for custom status messages custom status message file will only contain a single bit string up to 32 bits failed transactions are saved in very ugly temporary file names to the failed message directory opt iagent failed messages If possible they are saved in their ASN1 DER binary format so don t try to cat them They may be inspected with the included asnidump utility see Appendix invalid messages and receipts will be saved in very ugly temporary file names to the invalid message directory opt iagent invalid messages If possible they are August 2003 Page 70 version 2 3 2 IAgent User s Guide Administration also saved in their ASN1 DER binary format They may also be inspected with the included asnidump utility inbound receipts be saved in Receipt Input Message Format to temporary file names in the receipt log directory opt iagent receipts for manual examination and archiving if the savereceipts flag is set
164. the TCIF IA standard Issue 3 See Chapter 16 for more information on IA Ping status messages August 2003 Page 121 version 2 3 2 IAgent User s Guide Appendixes APPENDIX PRODUCT UTILITIES The following utilities are packaged with the IAgent product and may be used during installation configuration or testing monitoring of the system asnidump This is a utility from Peter Gutmann http www cs auckland ac nz pgut001 allows ASN 1 DER binary files to be displayed dumped in text and tag friendly format More information on the utility can be found by typing asnldump x iaappck This is a shell script which may be used to allow non root users to start and stop the IAgent system via touch scripts This file must be installed as a root cron job see the script for installation details Once installed the user need only type touch opt iagent iastart To start the IAgent system or touch opt iagent iastop To stop the IAgent system listen This is a shell script which can detect and display IAgent processes listening on the IA ports monitor This is a shell script which displays all IAgent processes currently running Is may be started in a second window and used to monitor the IAgent processes prngd test pl This Perl script is used to test the installation of the PRNG The test will display a success message if the PRNG is installed and running correctly Note this script does expect that the PRNG daemon wa
165. ut L Old Lyme O Lymeware Corporation OU IAgent Development CN LymewareDemoCA Email security lymeware com issuer C US ST Connecticut L Old Lyme O Lymeware Corporation OU IAgent Development CN LymewareDemoCA Email security lymeware com 20000417 035851 iagent 5355 PKI verify cert 20000417 035851 iagent 5355 Certificate Verification depth 0 subject C US ST Connecticut O Ly development CN TP 2 Email Lyme O Lymeware Corporati Development CN LymewareD meware Corporatio none lymeware co on OU IAgent moCA Email securi n OU Iagent m issuer C US ST Connecticut L Old ty lymeware com Example 31 An example of Debug Certificate Messages Client side August 2003 Page 81 version 2 3 2 IAgent User s Guide Administration 20000417 035 851 iage C US ST Connecticut Lym development CN TP_1 e O Lymeware Corporation O n t 5348 Certificate Verification O Lymeware Corporation OU Iagent m mail non 20000417 035 20000417 035 Client certi 851 iage 852 1 ficate Development CN LymewareDemoCA n nt 5348 EGIN C ChMUT bWVudD Y3VyaX NTBaM 11 amp mUuY29tMIGf R50Gx5 Ex5bWV3 nATI3TOCY kgBhvhCAQ0l BYEFN54YgJJ 4ABurW9u2VO VjdGljdXOx Jwb3JhdGlv woMeW11d2Fy mUuY 2 9tggEA 4rZ5FCoT2TIX o IGOMOswCOY ER
166. view and a gen csr tutorial 4 Sending the Request to your chosen CA How to send the CSR to the Certificate Authority CA and what forms of proof of identity will be required depend on the CA chosen Refer to the CA s support or sales staff for further instructions August 2003 Page 24 version 2 3 2 IAgent User s Guide Configuration Typically the CA will return the signed certificate via e mail Upon receipt of the signed certificate proceed to the next task 5 Installing local certificates and keys A directory opt iagent client certs is provided to store all your local X 509 certificates It is assumed that all certificates will contain the Trading Partner Common Name see Chapter 10 as the Certificate Common Name and be in PEM or base 64 format A directory opt iagent client keys is provided to store all your local private RSA keys It is assumed that all private keys will be in PEM or base 64 format It is suggested that all private keys be kept in this directory 6 Installing local Certificate Authority certificates A directory opt iagent ca certs is provided to store all CA X 509 certificates Typically your signing CA certificate and any CA certificates used by your Trading Partners should be stored here It is assumed that all certificates will be in PEM or base 64 format August 2003 Page 25 version 2 3 2 IAgent User s Guide Configuration CHAPTER 9 IAGENT SYSTEM CONFIGURATION ADMINISTRATION The Syst
167. with the bit string being ignored It is expected that some other back end process will handle them The Defined status input message format is IAS trading partner ID command with command being any one of the following TEST Special Test Message will be logged but otherwise ignored STOP WAN Problem with inbound WAN peer should stop transmission STOP OSS Problem with downstream OSS peer should stop transmission PING REQUEST Request ping from the remote trading partner A typical Defined Status input message is as follows IAS LWC TEST STOP Example 6 An example of a Defined status input message The Custom status input message format is IAS trading partner ID custom bit string 32 bits A typical Custom status input message is as follows IAS LWC 7 00000000110011000000000000000000 Example 7 An example of a Custom status input message August 2003 Page 49 version 2 3 2 IAgent User s Guide Administration CHAPTER 17 INBOUND SERVER FORMATS The IAgent server processes generate three possible output message formats regardless of output mode They are EDI message Receipt message and IA Status message formats A description and example of each is included below EDI Output message formats The IAgent server processes generate a raw ASCII text EDI ANSI X 12 message with a valid ISA segment as the first 105 bytes of the message actually the remainder of the message need
168. ymeware web site http www lymeware com products html August 2003 Page 96 version 2 3 2 IAgent User s Guide Appendixes For IAgent Machine information collection to be used before product installation Machine specific information Hostname FQDN IP address Host id if SPARC platform Physical Location Machine Hardware information CPU Type Number of CPUs Model Amount of System Memory Disk space CD ROM Device Machine Software information Operating system version Operating system patches installed Optional software installed Perl Tibco Web Browser Other System administration Contact information Primary Name Primary Telephone Number Primary Pager Number Primary E mail address Second Name Second Telephone Number Second Pager Number Second E mail address Primary Root availability Y N Second Root availability Y N Copyright 1999 2002 Lymeware Corporation All rights reserved Permission to copy for use in Agent installation is granted August 2003 Page 97 version 2 3 2 IAgent User s Guide Appendixes For IAgent Machine information collection to be used during connectivity testing Machine specific information Hostname FQDN IP address Standard IA port High Priority IA port Net mask Gateway IP ad

Download Pdf Manuals

Related Search

Related Contents

AAMI EC11 - Electrical, Computer & Biomedical Engineering  IP POWER 9258 USER MANUAL  

Copyright © All rights reserved. Failed to retrieve file