Home

Adobe PDF - Lymeware Corporation

1. Transaction Error Status Code Description Value ERRM CANNOT FIND LOCAL CERT ENTRY 40 VERSION NOT SUPPORTED 39 IA ERRM OVERLOAD REFUSED INBOUND CONNECTION 38 ERRM FAILOVER CANNOT READ DATA LOST 37 ERRM FAILOVER REFUSED INBOUND CONNECTION 36 ERRM CANNOT FIND CONNECTION 35 ERRM CANNOT CREATE CONNECTION 34 ERRM CANNOT STORE PENDING RECEIPT 33 IA ERRM CANNOT START PROCESS 32 ERRM INTERNAL DATA LISTEN FAILED 31 ERRM CANNOT SEND INTERNAL DATA 30 ERRM CANNOT INTERNAL DATA 29 CANNOT SAVE IASTATUS TO PIPE 28 ERRM CANNOT SAVE IASTATUS OUT FILE 27 CANNOT REMOVE PENDING RECEIPT 26 ERRM CANNOT GENERATE RECEIPT 25 ERRM CANNOT SAVE RECEIPT TO PIPE 24 ERRM CANNOT WRITE EDI MSG 23 ERRM CANNOT WRITE EDI MSG TO SOCKET 22 IA ERRM CANNOT WRITE EDI MSG TO PIPE 21 ERRM NO PENDING REC FOUND 20 TP ID MISSING FROM INPUT IA STATUS MSG 19 ERRM ISA SEG MISSING FROM INPUT RECEIPT MSG 18 ERRM CANNOT GENERATE IA STATUS MSG 17 CLIENTS CERTS MISSING 16 ERRM CLIENTS OWN CERT MISSING 15 IA ERRM CANNOT SAVE RECEIPT OUT FILE 14 ERRM CANNOT SAVE EDI MSG FILE 13 IA ERRM CA
2. iap 00 process type IAP PROCESS iaversion 2 stdport 2000 hipriport 2001 key opt iagent3 security TP lkey pem cert opt iagent3 security TP lcert pem CAfile opt iagent3 security CAcert pem pacing delay 220 transport listen port 127 0 0 1 8103 November 2004 Page 112 version 3 1 1 IAgent3 User s Guide Appendixes FE ETE AE HEHE FE AE FE AE FE EEE FE E FE EH EEE EEE AE TE AE EE EEE EE EE FE AE FE EEE EE EE HE EEE FE HE FE H clientp process_type CLIENT PROCESS indir toILEC insocket intibco dirpolldelay oneshot packetmode E aE aE aE AE AE E a aE aE aE AE E HE aE ae AE E FE aa aaa aaa aaa EOF iagent conf November 2004 Page 113 version 3 1 1 IAgent3 User s Guide Appendixes A second example of the IAgent configuration file demonstrating the Socket Interface f IAgent3 example Process configuration file default section process names std svr hpr svr receipt iap p00 clientp system wide settings Tff ata a at aaa AE aE AE aE aE aE AE aE aE aE ae AE aE aE AE EEE EE EE EEE socket 4125 interface debug verbose clusternum loopbackdelay sloppyallow sloppyinactive cachesize receiptmode vhack raw tpartner
3. e EORR 60 CHAPTER 23 EXAMPLE INTEGRATION CODE SAMPLES cH 61 DIRECTORY APE CODE SAMPLES ero 61 Directory APl Reader EXAMP Eno rhe dote petat a 61 Directory API Writer Example uec oderat edad hime oe tto iei 61 November 2004 7 version 3 1 1 IAgent3 User s Guide Preface SOCKET APT CODE S AMPLES 5 retro suds dou dents ive eie Une eee as eere e iS e les ttes 62 Socket APT Reader Example 2 e e ed eats Sou eee t beoe rte entered eee 62 Socket ART Writer Examples o eee tide 63 64 Web Services API Reader Example c ccccccsscssssscesesseesecssesecucesecseeseesecseesecaeesecnteeseeaesseesecseesecaeeeeeeaesseeaeeaesaesaeeeeenaes 64 Web Services API Writer Example 0 ccccsccsssssssssssesesecssesscceescsseeceeseeecsecacesccuaeeceeaseceesesasesecseessesaseceeaeeasesesaceeesnaes 64 TIBCO API CODE SAMPLEES i e cicer to ee erret de e te aaa PA E T eae 65 Tibco API ReaderiExample o ases bee eite peret te dese on 65 libto API Writer Example uo ente HEP RR REE
4. Example 11 An example of an Integrity Receipt output message A typical Signed Receipt output message is as follows line NOT wrapped AR ISA 00 IAGENT 00 TEST ZZ LWC TEST ZZ LWC 7 990629 1621 U 00307 000002466 0 T 199906301200002 8 542ac34623 098790 ed9876985b0 743c6a06591ca410027ed7 7 Example 12 An example of a Signed Receipt output message IA Status Output message formats The Agent 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 in the IA Specification test stop W AN 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 November 2004 Page 52 version 3 1 1 IAgent3 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
5. seen enn 116 GEN_CSR REQUEST CONF CONFIGURATION 118 APPENDIX D CONNECTIVITY TESTING 119 SIMPLE TRADING PARTNER CONNECTIVITY 0002 0000000000000000000 119 SIMPLE BACKEND INTEGRATION API TEST 119 APPENDIX E EXTENDED 02 2 2 000 0000000 120 TE YYMEWARE SPECIFIC Se sce ec cbc eee e e etes P Feb a Tree b SUI ec oe e ru e a O bu ues 120 Defined Status Input messdge os Rer her etre eie actin erede ica ee 120 PROPOSED FUTURE STANDARD EXTENSIONS e TREE dts iot RN Sek ec aeree ku a A duse 120 TA Ping Status Messages c cedet n ed eae e p Mr e ta SUG ae Ree ege eo edo Fe pe ee be Ree 120 APPENDIX F PRODUCT 8 0000000000 0000 nee nnnm nnnm eee nennen nre eene 121 ASNTDUMP sid ste t f even eh e enn isti 121 iste Sette eat ihi on LL LESE onini E ig 121 LEISTEN Sodann sete ser s A 121 MONITORS Er 121 PRNGD seceten HRS REED 121 157 enr dede dM 121 5 ctr etm read 121
6. Example 9 An example of an EDI output message November 2004 Page 51 version 3 1 1 IAgent3 User s Guide Administration Receipt Output message formats The receipt output message format is identical to the receipt input message format The IAgent server processes generate a 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 AR 1SA 00 IAGENT 00 TEST ZZ LWC TEST ZZ LWC 7 990629 1621 U 00307 000002466 0 T 2 199906301200002 Example 10 An example of a Basic Receipt output message A typical Integrity Receipt output message is as follows line NOT wrapped AR 1SA 00 IAGENT 00 TEST ZZ LWC TEST ZZ LWC 7 990629 1621 U 00307 000002466 0 T 2 199906301200002 1 542ac34623 098790 ed987698b0
7. 96 CONNECTIVITY WORKSHEET ecce entre 97 CONFIGURATION WORKSHEET ccccccccsscesssecsssceessecesssecsseceassecsseceussecssecusseessecsusseessecessseessecsssseessecsaseeessese 98 TRADING PARTNER WORKSHEET ccccccscesssccessssessecessceeseecessceessecasseessecessssessecsssseessecesssseseecsasseessecsaseeeseees 99 November 2004 8 version 3 1 1 IAgent3 User s Guide Preface CERTIFICATE REQUEST WORKSHEET cssssssssececsessssscecccecsenesececeeccseneseseeeeececeesaaeseeeceesesaseseeeesesessaaeeeeececeeseaeaeeeeeees 100 TAGENSE REQUEST HORM RT 101 1 LICENSE REQUEST FORM ccccccccccccessecssceessecsscesssecssscesssecsuscesssccsuscessscsasesessecsuscsessecsasceessscsusesesssenssensees 101 PROBLEM REPORT FORM Q cccccccsscesssecsssceessecsuscesssscsascessecsuscesssecsuscesssecuscesssecsasceeseecasceessecssseeessecssseeesess 102 APPENDIX B CERTIFICATES AND THE GEN CSR 0400000 103 APPENDIX C SAMPLE CONFIGURATION FILES cese enne eres 111 SYSTEM OR IAGENT CONFIGURATION FILE sees ener enne en rennen en enitn enne eere 111 TRADING PARTNER CONFIGURATION
8. 108 Using gen csr to create a DER Certificate Signing 109 Sample PEM Certificate Signing Request enne nennen ennt 110 Sample Private Key eene ed Reeth bea ia de mtem nate Oo Ie eate ed 110 November 2004 version 3 1 1 List 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 IAgent3 User s Guide Preface of Figures An Interactive Agent IA system for EDI communications esee eene 2 Using an IAgent3 system for trading partner communications eese eren 5 IAgent3 Intesration APIS n un Rer e RU ER n OU AER e ect deed 6 Real and Virtual Messaging Connections 8 Trading Partner Connectivity dated spere EE Rage ce repre BEER eed 38 Message Receipt Data Flow eis eR ete teda v P t e Ut ems earned A 41 Internal Receipt Mode Data Flow sees nenne nrennt trennt a a R 43 External Receipt Mode Data Flow ss itte eii ROI Rees Rese RE des 44 Backend System to Integration API Interfaces essere 46 The detailed message data format for the socket interface 55 The detailed message data format for the socket interface 56 Integration Suppor
9. 5E 25 000000001 GE 1 000001 IEA 1 000000001 Example 1 An example of an EDI Input message November 2004 Page 48 version 3 1 1 IAgent3 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 LWC7 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 IAgent3 client process expects to find an IAR 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 a colon 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 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
10. bin debugia start bin debugia stop Log and Output Files The IAgent3 system and processes generate several different types of log and output files The log files consist of A system wide output log file 1agent 10g which contains almost everything that is written to the console stdout including verbose messages A system wide error log file 41agent 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 4agent 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 file contents are described in Chapter 26 The IAgent3 system will create a process ID file PID file iagent pid for the process group of all Agent processes created It is suggested that all signals sent to the IAgent3 processes use this file All 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 s
11. CANNOT FIND ISSUERNAME IN CERT CANNOT ACCEPT CLIENT HANDSHAKE CANNOT VERIFY CLIENT CERT N IA ERRM NO CLIENT CERT SENT 92 ERRM UNKNOWN IPADDR SENT FROM CLIENT CANNOT PARSE ASNI ERRM MESSAGE INTEGRITY BROKEN nN ERRM MESSAGE BAD SIGNITURE FOUND RECEIPT INTEGRITY BROKEN oo ERRM RECEIPT BAD SIGNITURE FOUND ERRM CNAME MISMATCH N A ERRM INCORRECT MESSAGE TYPE SENT FROM TP N ERRM RECEIVED MESSAGE FROM INACTIVE TP N N ERRM TOO MANY OPEN CONNECTIONS FROM TP N Table 11 IAgent3 Error Numbers continued More details of specific errors can be found in Chapter 28 November 2004 Page 74 version 3 1 1 IAgent3 User s Guide Administration CHAPTER 27 TROUBLESHOOTING PROBLEMS AND ERRORS Troubleshooting errors and problems with the IAgent3 system may seem like a daunting task given the distributed processing and
12. 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 iagent3 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 IAgent3 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 IA systems At this time the Agent3 Connectivity Worksheet see Appendix A should be completed This may require information and assistance of network or LAN personnel Note The IAgent3 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 A
13. 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 1 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 the 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 purposes The req section of the configuration file is November 2004 Page 105 version 3 1 1 IAgent3 User s Guide Appendixes used when creating certificate requests with csr and supplies defaults and length limits for the various distinguished name fields In our examples it has the configuration as shown in Example 40 Gen csr example configuration file This is being used for generation of certificate requests RANDFILE SENV HOME rnd re
14. November 2004 Page 121 version 3 1 1 IAgent3 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 in X 209 certificate In cryptography an electronic document binding some pieces of information together 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 a block cipher developed by IBM 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 ke
15. TCIF 98 006 Issue 2 amp Issue 3 Interactive Agent Users Guide Version 3 1 1 Lymeware Corporation www lymeware com TCIF 98 006 Issue 2 amp Issue 3 Interactive Agent User s Guide Version 3 1 1 Lymeware Corporation 19 Halls Road Suite 216 Old Lyme Connecticut USA 2004 IAUG3 11 0011 IAgent3 is a 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 TIB Rendezvous are trademarks of TIBCO Software Inc All 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 IAgent3 software is Copyright 1999 2004 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 licens
16. config FILENAME config file FILENAME IAgent configuration file name default is iagent conf 1 ie debug DEPTH debuglevel DEPTH Debug display depth for testing purposes only Table 5 IAgent3 Command Line Arguments continued November 2004 Page 31 version 3 1 1 IAgent3 User s Guide Configuration e FILENAME entropy FILENAME Entropy source file required for cryptographic calculations f failover Failover subsystem mode may be None Std or All defaults to None g SOCKETPORT insocke Input socke SOCKETPORT port for Socket interface only h PORT hipriport 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 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 l clusternum Set cluster number for operations 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 q vh
17. 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 November 2004 Page 90 version 3 1 1 IAgent3 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 specifically required for operation of the Agent 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 port
18. Client sends own certificate gt Server validates Client certificate with correct CA 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 IAgent3 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 destination 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 November 2004 Page 8 version 3 1 1 IAgent3 User s Gu
19. Copyright 1999 2004 Lymeware Corporation All rights reserved Permission to copy for use in IAgent3 installation is granted November 2004 Page 97 version 3 1 1 IAgent3 User s Guide Appendixes For IAgent3 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 Interface 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 IA message from any Trading Partner Sloppy Allow Will allow messages from inactive Trading Partner Sloppy Inactive Will allow duplicate
20. P KI verify eware Corpora Lyme O Lymeware Corpora Development CN Lymewar Dem oCA development CN TP_2 Email none lymewar tion OU IAgent Email sec urity lymeware com issuer are Corporation OU IAgent urity lymeware com cert t 5355 Certificate Verification depth 0 subject tion OU Iagent com issuer C US ST Connecticut L Old urity lymeware com Example 28 An example of Debug Certificate Messages Client side November 2004 Page 79 version 3 1 1 IAgent3 User s Guide Administration development CN TP 1 Lyme O Lymeware 20000417 035851 iagent 5348 Certificate Verification C US ST Connecticut O Lymeware Corporation OU Iagent Clien MIID ChMUT lbWVud NTBaM Y3VyaX Development CN 1 20000417 035851 iagen 20000417 035852 iagent 534 t certificate Cp7p137nZ7db Iidl cmUuY29tgg EGIN C IGOMOswCOY wO5vcB6v9vvias 63 7E91 GPKCy0dPg gQ29ycG 1 EAMAOGCSqGSIb ArZ5FCOT2TIX2yeijgqGCBN HTkLqhw53J END C ERTIFICATE DCCA2GgAwIBAgIBDDANBg FDASBgNVBAgTCONvbm51Y3 HltZzXdhcmU DEXMBUGA1U R5OGx5DbWV3YXJlI Email none lymewar Corporation OU IAgent LymewareDemoCA Email securit com issuer depth 0 subject y lymeware com C US ST Connecticut L Old 5348 551 acc
21. ccccesccesecssecsceeseeeseeeseeseceseesseenseceseeaecaecsaecaeecaeeeaeeeateass 50 An example of a Custom status input message 12 2 2 70 00 02000200000000000000000000000000000000000 50 A typical IS A BDT segment eR OR ERG EC GUIDE EU EROR OR EE E 51 An example of an EDI output message sssssssessesseeee eene 51 An example of a Basic Receipt output message sse ener enne 52 An example of an Integrity Receipt output message ssssssssesseseeeeneneen enne enne nnne 52 An example of a Signed Receipt output message ener enne 52 An example of a Defined status output message sse enne nnne 53 An example of a Custom status output message 53 Directory API Reader Example 61 Directory API Writer Example dece e 61 Socket API Reader Example 3 eei tee he eee eee de e eie ne see 62 Socket APL Writer Example eese ete aene tee iicet ie dens 63 Web Services API Reader Example eee ede eee e rte e ete last 64 WebServices Writer Example eene eni pe ne e die ua 64 Tibco API Reader Example eere redeo EC ee e E eee es 65 Tibco API Writer Example enean it pe t ae ees 66 Starting Agent3 as a system 69 An example of Basic Debug Messages 00 csccesecesesesecsseeseeeseeeseeeeeseeeseensecue
22. operation concepts of the Agent3 system and introduces IA and SSL TLS concepts Part 2 covers how to install the Agent3 system with all required components Part 3 covers how to configure the Agent system with manually generated configuration tables Part 4 covers how to integrate the IAgent3 system with backend systems BESs using the provided Integration Application Program Interfaces Integration APIs Part 5 isa reference section that also covers advanced topics and describes management tools used to maintain the IAgent system and maintenance issues The 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 IAgent3 product and components Chapter 3 Contains basic introductory material to the SSL TLS protocol and the security components of SSL amp TLS messaging and communication Part 2 Agent Installation Chapter 4 Outlines how to install and configure the Agent3 system for production use Chapter 5 Describes pre installation tasks Chapter 6 Describes how to install the IAgent3 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 Desc
23. opt iagent3 invalid messages Ifpossible they will be saved in their ASNI DER binary format lAgent3 Alert Messages All operational alerts events and errors the IAgent3 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 ASN1 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 IAgent3 system performance and is not recommended for standard production use All 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 ASN1 messages 32 Display Parsed ASN1 messages 64 Display Debug RSA Key messages 128 Display Debug Receipt messages 256 Display IA Timer messages 512 Display Internal Debug messages Table 12 Debug Level Masks November 2004 Page 76 ve
24. 01 03 32 88 8 45 1 14 26 6 31 45 50 0 34 14 5 2 22 72 9 9 47 7 7 67 07 5 88 9 2 7d 46 15 d6 39 9e db 55b 5d 81 3e 1b 9 0e 6f 2 28 49 85 89 81 86 4 86 40 5 37 0 44 7 94 74 9 49 4 3 41 61 15 29 68 6 93 37 4 0 Exponent 65537 0x10001 20000417 035852 iagent 5348 END of Peer RSA Public Key Example 34 An example of Debug RSA Key Messages 20000417 035852 iagent 5348 receipt required for TP 1 20000417 035852 iagent 5348 Basic receipt required for TP 1 20000417 035852 iagent 5348 Digest receipt required for TP 1 20000417 035852 iagent 5348 Signed receipt required for TP 1 20000417 035852 iagen 20000417 035852 iagen 5348 Digest verified 5348 RSA digital signature verified Example 35 An example of Debug Receipt Messages November 2004 Page 83 version 3 1 1 IAgent3 User s Guide Administration 20000417 035852 iagen 20000417 035854 iagen 20000417 035855 iagen 5348 551 Handshake start time 035852 5348 551 Handshake end time 035854 5348 Total Handshake time 02 5 Seconds EE FEFA 20000417 040012 iagen 20000417 040013 iagen 20000417 040014 iagen 5348 Message Transport start time 040012 5348 Message Transport end time 040013 5348 Total Message Transport time 01 1 Seconds Cr cT CT Example 36 An example o
25. A for the IAgent3 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 Agent3 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 IAgent3 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 IAgent3 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 IAgent3 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 IAgent3 Solaris product is not appropriate since this product only supports Solaris running on SPARC platforms If you have any question about which version of IAgent3 product supports your specific machine and operating system please contact the Lymeware sales team or your distributor for assistance November 2004 Page 18 version 3 1 1 IAgent3 User s Guide Installation
26. CHAPTER 15 INTEGRATION API OVERVIEW The IAgent3 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 IP Socket interface the Web Services 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 The BES can be anything from a standard EDI translator to a Gateway product to a full Operational Support System OSS The IAgent3 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 eThe File Directory interface atomically reads and writes ASCII text files EDI messages in standard ASC X 12 formats eThe 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 eThe Web Services interface reads from and writes to specific SOAP endpoints defined by WSDLs optional Tibco TIB Rendezvous message bus interface reads input Tibco messages with a single subscriber and writes output Tibco m
27. IAgent3 system Support the same trading partner identity used by the local gent3 system Note standard IAgent3 system only supports a single local trading partner Lymeware does have a multiple CLEC version of IAgent3 available please contact our sales office for more details 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 a Joint Implementation Agreement JIA a sample of which is available from TCIF through the ATIS web site www atis org November 2004 Page 40 version 3 1 1 IAgent3 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
28. T 3520 1 4 1 3576 9 IA NON EDI eciaNonEdi 1 3 6 1 4 1 3576 7 1 IA EDI 1 plainEDImessage 1 3 6 1 4 1 3576 7 2 IA EDI 2 signedEDImessage 1 3 6 1 4 1 3576 7 5 IA EDI 3 integrityEDImessage 1 34606 1 4 1 3576 7 065 IA R 1 iaReceiptMessag 14 1 35 76 7 94 IA S 1 iaStatusMessage 20000417 035850 iagent 5355 End of IA ASN 1 OIDs 4 20000417 035850 iagent 5355 Number of new ASN 1 Objects added 8 Example 31 An example of Debug ASN1 Messages 20000417 035850 iagent 5355 ASN1 parse returned a 1 0 d20 hl 4 1 1418 cons SEQUENCE 4 d 1 hl 2 1 9 prim OBJECT SignedEDImessage 15 d 1 hl 4 1 1403 cons SEQUENCE 19 d 2 hl 2 l 1 prim INTEGER 00 22 d 2 1 2 1 7 cons SET 24 d 23 1 2 l 5 prim OBJECT SHAldigestAlgorthm 31 d 2 1 4 1 1176 cons SEQUENCE 35 d 3 hl 2 l 9 prim OBJECT plainEDImessage 46 d 3 hl 4 1 1161 prim OCTET STRING ISA 00 IAGENT 00 TEST ZZ 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 MSG 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 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 MSG This is a test message line 10 MSG This is a tes
29. accept Starting SSL handshake with SSL accept SSL_accept before accept initialization SSL_accept SSLv3 read client hello SSL_accept SSLv3 write server hello SSL_accept SSLv3 write certificate SSL_accept SSLv3 write certificate request A 5348 SSL_accept SSLv3 flush data 5348 verify cert 5348 551 accept SSLv3 read client certificate 5348 551 accept SSLv3 read client key exchange 5348 551 accept SSLv3 read certificate verify 5348 SSL_ accept SSLv3 read finished 5348 551 accept SSLv3 write change cipher spec 5348 551 accept SSLv3 write finished 5348 551 accept SSLv3 flush data 5348 DEBUG Getting Client s certificate 5348 SSL connection using DES CBC3 SHA 5348 SSL Handshake DONE LEF REO VE XE CRE CE EE Ek UE Example 26 An example of Debug SSL Handshake State Messages Server side November 2004 Page 78 version 3 1 1 IAgent3 User s Guide Administration 20000417 035850 iagent 5355 RAW Input Data 4 20000417 035850 iagent 5355 18A 00 IAGENT 00 TEST 227 1 227 TWO 990629 1248 U 00303 000000001 0 T GS PO CLECAPP LWC 990629 1248 000001 X 003030 ST 864 000000001 BMG 28 D
30. asad A TEE 17 PART TINTRODUCAIAIOJI a 1 CHAPTER 1 INTRODUCTION TCIF INTERACTIVE AGENT SYSTEMS 2 CHAPTER 2 INTRODUCTION TO THE IAGENT3 PRODUCT cree 5 SIMPLE INTEGRATION IS voce oleh ettet reete eee reset eet et Bree eee egets over 6 USER DEFINED CONNECTIVITY 7 HOW DOBSTEANVOREJ ese ote b e eie ei outer eh 7 CHAPTER 3 INTRODUCTION 5665 nnns nsns nnne 10 CRYPTOGRAPHIC TECHNIQUES ertet ettet e etre ee e tr ev eee eite vei evertere ir erre e ed 10 CRYPTOGRAPHIC ALGORITHMS nee tee iive eie eeepc ev iv ice s 10 MESSAGE DIGESTS in eret ehe re ete e eque eei eoo n potrete ie e ire ben ER 11 DIGITAL SIGNATURES I ree it ure ee T ete ee cr eer RAE 11 CERTIFICATES e eie e ve e pet ete e ge ems 11 CERTIFICATE CONTENTS i fite te t eg uie etre ro pee 12 CERTIFICATE AUTHORITIES pee eee bw ye e rer pe 12 CERTIFICATE CHAINS n eet er sese eter Pe repere RR Eee even eive eno a EEE 12 CREATING A ROOT EEVEL CA CERTIFICATE 3 eee etre ert tree re rei teure vel OVE 12 CERTIFICATE MANAGEMENT vcs tre eo e terere OE oak Rees baa rt Pe ERU Pee TUE er OIE e Re e UPON V dvd 12 SECURE S
31. collaborative nature of the Agent3 system and its peer systems both all other IA systems and the BES The IAgent3 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 Data Pipes and Test Points Rerrate A Server Rerrate IA Client Faded IEureactiore Figure 14 IAgent3 Processing as a Series of Pipes inbound It is suggested that running the IAgent3 product in 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 andiagent alert logs after sending a single message to the IAgent3 system from the BES November 2004 Page 75 version 3 1 1 IAgent3 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 iagent3 failed messages Ifpossible 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
32. expect the 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 IAgent3 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 is as follows lines NOT wrapped ISA 00 IAGENT 00 TEST SAL TBs 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 MSG 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 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 MSG 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 MSG This is a test message line 14 MSG This is a test message line 15 MSG This is a test message line 16 MSG This is a test message line 17 MSG This is a test message line 18 MSG This is a test message line 19
33. message from tp ia receipt to tp ia receipt from tp Server status Uu XXIX LOOPBAC LOOPBAC 127 0 0 2000 2001 0 BASIC BASIC BASIC BASIC 2 FI GI 1 LOOPBAC LOOPBAC 127 0 0 2000 2001 0 INTEGRI INTEGRI INTEGRI INTEGRI 1 1 tat a at LOOPBAC LOOPBAC 127 0 0 2000 2001 0 FE aE aE aE AE AE aE FE aE ae aE AE AE aE FE aE aaa aaa K R K R 1 no resumable sessions DI DI ECEIPT ECEIPT FE aE aE aE AE AE aE FE aE aE aE AE AE E aaa aaa K I K I SET no resumable sessions TY EDI EY TY RECEIPT TY RECEIPT FEAE AE aE AE AE aE aE aE ae aE AE aE aE aE aE aa K S K S Eit no resumable sessions SIGNE EDI SIGNE EDI SIGNE RECEIPT X XJ SIGNE FE aE aE aE aT AE aE a ae aE aE AE EOF tpartner conf RECEIPT FE aE aE aE AE AE E aE FE aE AE AE E FE aaa November 2004 Page 117 version 3 1 1 IAgent3 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
34. my iaddr gethostbyname frodo my proto getprotobyname tcp my port 6669 my paddr sockaddr_in 0 iaddr socket SOCKET PF_INET SOCK STREAM proto die socket connect SOCKET paddr die bind read length my binary read SOCKET binary 4 my S IAlength unpack N binary read priority my binary read SOCKET binary 2 my IApriority unpack N binary read data read SOCKET IAdata SIAlength Example 17 Socket API Reader Example November 2004 Page 62 version 3 1 1 IAgent3 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 die setsockopt bind SOCKET sockaddr in port INADDR ANY die bind listen SOCKET SOMAXCONN die listen my paddr accept CLIENT SOCKET store length my binaryl pack N SIAlength store priority my binary2 pack N SIApriority write it all print CLIENT JAlength SIApriority IAdata close CLIENT Example 18 Socket API Writer Example November 2004 Page 63 version 3 1 1 IAgent3 User s Guide Administration Web Services API Code Samples Web Services API Reader Example FIFO opt iagent iapipe next line blocks until there s a writer op
35. of X 509 client certificates and private RSA keys X 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 is how it works in a nutshell The IAgent3 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 one or more CA 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 Agent3 server has its own X 509 certificate and private key The server also has one or more CA certificates that it uses to validate the client s certificate A very simplified version of the IA SSLv3 TLS handshake with emphasis on certificate transfers and validation would look something like this November 2004 Page 7 version 3 1 1 IAgent3 User s Guide Introduction IAgent3 Client IAgent3 Server Connect gt lt Server Hello handshake start Client Hello gt K Server sends own certificate Client validates Server certificate with correct CA certificate if local copy exists If valid then
36. or Signed A typical Basic Receipt input message is as follows line NOT wrapped AR 1SA 00 IAGENT 00 TEST ZZ LWC TEST ZZ LWC 7 990629 1621 U 00307 000002466 0 T 2 199906301200002 Example 3 An example of a Basic Receipt input message A typical Integrity Receipt input message is as follows line NOT wrapped AR 1SA 00 IAGENT 00 TEST ZZ LWC TEST ZZ LWC 7 990629 1621 U 00307 000002466 0 T 2 199906301200002 1 542ac34623 098790 ed987698b0a62 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 IAR 1ISA 00 IAGENT 00 TEST ZZ LWC TEST ZZ LWC 7 990629 1621 U 00307 000002466 0 T 199906301200002 8 542ac34623 098790 ed98769850 743c6a06591ca410027ed7 7 Example 5 An example of a Signed Receipt input message IA Status input message format The IAgent 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 November 2004 Page 49 version 3 1 1 IAgent3 User s Guide Administration receiving IAgent serv
37. 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 overview and 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 November 2004 Page 24 version 3 1 1 IAgent3 U
38. resume after reaching limit K failover limit Maximum number of failover records to save Table 4 IAgent3 Command Line Arguments November 2004 Page 30 version 3 1 1 IAgent3 User s Guide Configuration L SECONDS loopbackdelay SECONDS Debug loopback delay in seconds for testing purposes only N server socket Standard Server socket address and port for process tcp pipes only O oneshot Flag to force processing of only a single transaction Q hpri server socket Hi Priority Server socket address and port for process tcp pipes 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 T MESSAGE NAME outtibco MESSAGE NAME Output tibco message subject name for Tibco interface only U receipt socket Receipt Client socket address and port for process tcp pipes only V version Prints the version of IAgent3 then exits X failover path Failover data directory path opt iagent3 data is the default Y savereceipts Flag to force storage of all inbound and outbound receipts Z packetmode Forces IA Input packet format support only a PATH indir PATH Input directory name for Directory interface only c FILENAME
39. 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 WAN 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 November 2004 Page 53 version 3 1 1 IAgent3 User s Guide Administration CHAPTER 18 FILE AND DIRECTORY API 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
40. savereceipts config entropy ignoredupreceipts process sections AE AE AT aE aE AE AE aE aT aE aE AE AE E AE aE aT AE AE AE aE AE AE AE FE FE TE AEA it a EE FE FE FE EEE PEEP std svr process type STD SERVER PROCESS outsocket 192 168 1 108 7301 bes connect attempts bes connect delay transport listen port 127 0 0 1 8101 FERE FE EE EE HE E TE TE FE FE FE FE HE HE E TE TE FE FE FE FE HE E E E TE EE EE E E TE AE AE EE EE E E E E E E E E E E E E E E E E E E A E H hpr svr process type HPR SERVER PROCESS outsocket 192 168 1 108 7301 bes connect attempts bes connect delay transport listen port 127 0 0 1 8102 November 2004 Page 114 version 3 1 1 IAgent3 User s Guide Appendixes FE aE aE aE AE AE aE HE aE aE AE AE E FE aE aaa aaa receipt process type RECEIPT PROCESS transport listen port 127 0 0 1 8100 i a REI failovr process type FAILOVER PROCESS failover failover path failover reconnect delay low failover threshold failover limit HEHEHE HE EE EE EE EE EE EEE EE EE EE E EE EE 00 1 process type IAP PROCESS iaversion 2 stdport 2000 hipriport 2001 key opt iagent3 security TP lkey pem cert opt iagent3 security TP lcert
41. savereceipts config entropy ignoredupreceipts process sections Fa AAT EAE E aE aE aT ita a a EE EE EE EEE std svr process type STD SERVER PROCESS outdir fromILEC outsocket outtibco bes connect attempts bes connect delay transport listen port 127 0 0 1 8101 November 2004 Page 111 version 3 1 1 IAgent3 User s Guide Appendixes FE AE aE aE AE AE AE E aE Ea E FE aE aaa hpr process type HPR SERVER PROCESS outdir hpfromILEC outsocket outtibco bes connect attempts bes connect delay transport listen port 127 0 0 1 8102 FE AE AE AE AE AE AE FE FE AE FE AE E E FE AE FE AE AE FE FE FE E AE AE E FE FE TE AE AE E FE FE TE AE AE E FE FE AE AE AE AE FE FE AE FE AE AE AE FE AE FE AE AE E FE AE TE AE AE REI receipt process type RECEIPT PROCESS transport listen port 127 0 0 1 8100 FE aE aE aE AE AE E a aaa aaa failovr process type FAILOVER PROCESS failover failover path failover reconnect delay low failo ver threshold failover limit
42. 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 November 2004 Page 11 version 3 1 1 IAgent3 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 It 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 infor
43. the IAgent RV message subject name 4agent 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 TEMP 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 All 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 Sample code to support the Tibco Interface is supplied in Chapter 23 Additional tibco rv examples are provided with the TIB Rendezvous product November 2004 Page 57 version 3 1 1 IAgent3 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 tix license file 2 Set the Agent user s PATH environmental variable to include the rvd executable path 3 Set the Agent user s LD LIBRARY PATH to include the 1ibrvd so location Note This Agent implementation does not support either the certif
44. 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 deliver the message If the connect fails then the message will be stored as a file see Directory Interface Mode Chapter18 for file details in the 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 the S ADDRESS or outsocket ADDRESS options Be sure to include a port in the address All trading partner messages will be fed into the same input socket and will exit to the
45. 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 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 November 2004 Page 38 version 3 1 1 IAgent3 User s Guide Configuration 4 telnet to the remote trading partner s machine with the following command telnet IP address port so in our example the command line would look like this telnet 191 168 1 1 6999 5 At this point one of two things will happen The connection will either be allowed or rejected If rejected then 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 conne
46. 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 A 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 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
47. 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 1999 2004 Lymeware Corporation All rights reserved Permission to copy for use in IAgent3 installation is granted November 2004 Page 102 version 3 1 1 IAgent3 User s Guide Appendixes APPENDIX B CERTIFICATES AND THE GEN CSR 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 The X 509 refers to the standard Recommendation X 509 The Directory Authentication Framework 1988 CCITT which defined the framework of the certificate elements also known as certificate fields Netscape adopted the X 509 certificate structure for its Secured Socket Layer SSL protocol design IA message systems also use X 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
48. trusting this key it would be obvious if someone else publicized a key claiming to be the authority November 2004 Page 104 version 3 1 1 IAgent3 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 e ssuing 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 is used to authenticate a client to a server Creating and installing a client certificate is difficult because the client must generate a key pair keep the private key to itself and send the public key to the certificate authority to be incorporated into a certificate request Our utility gen_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 IAgent operation the client certificate is often also called the machine certificate The general steps for creating a client certificate are as follows 1 User generates a key pair public and private key
49. 000000000000000000000000000 52 CHAPTER 18 FILE AND DIRECTORY INTEGRATION 0 00 54 FILE INTERFACE M ODE 25 v eit er En e HE e tee E e EON Ses CR aa 54 DIRECTORY INTERFAGE MODE REOR UR VENE EX E D IU Pure 54 CHAPTER 19 SOCKET 55 SOCKET NIBREACE MODE ee eri dives ii ete e in VOLES 55 CHAPTER 20 WEB SERVICES nns 56 WEB SERVICESINTERFAGE MODE o tette pem siat eter CIN eise v Ete es 56 CHAPTER 21 TIBCO MESSAGE 00 00004000000 0 57 INTEREACE MODE iege RED oa REGII Og ae E ER EE P RE Ee ee e PER e ext 57 TIBCOINSEATEATION ISSUES 58 CHAPTER 22 TESTING INTEGRATION API CONFIGURATIONS ee 59 INTEGRATION API SPECIFIC TESTING ISSUES ccccsessscccececeessssececececsensseceeececeeseseseceeseseseseaeeeeecsceeseaaseeeeceseenssaseeeeeeens 59 Directory Interface ASSUCS 205 5 30 etes IE OP Rb ete dtu e o CAR IDEA 59 Sockel InteYace scc See m LO sumo quud t ex 59 59 Am
50. 1999 November 2004 XV Preface version 3 1 1 IAgent3 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 address 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 lymeware com for all sales related inquires and similar communication This address is monitored daily and all m
51. 2000 2004 Lymeware Corporation Header export home aclark iagent src RCS request cnf v 1 3 2001 01 13 18 44 05 kobar Exp HEHE HEHE FE AE FE HH EEE HE HE EEE FE AE FE EE AE FE AE EE FE E FE EE EEE HE EE EEE EEE HE EE EEE HH 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 Sod stateOrProvinceName State or Province Name full name stateOrProvinceName default Connecticut localityName Locality Name eg city 0 organizationName Organization Name eg company O organizationName default Lymeware Corporation organizationalUnitName Organizational Unit Name eg section organizationalUnitName default commonName Common 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 72 0 EOF November 2004 Page 118 version 3 1 1 IAgent3 User s Guide Appendixes APPENDIX D CONNECTIVITY TESTING Simple Tra
52. DATA CANNOT START PROCESS CANNOT STORE PENDING RECEIPT CANNOT WRITE SSL CLIENT CANNOT WRITE TIBCO EDI MSG CLIENTS CA CERTS MISSING CLIENTS OWN CERT MISSING CNAME MISMATCH FAILOVER CANNOT READ DATA LOST Cannot read data due to FAILOVER being full Some data may be lost FAILOVER REFUSED INBOUND CONNECTION Refused inbound connection due to FAILOVER being full No data has been lost IAP VERSION NOT SUPPORTED Requested IAP Version is not supported by this license INCORRECT MESSAGE TYPE SENT FROM TP INTERNAL DATA LISTEN FAILED ISA SEG MISSING FROM INPUT RECEIPT MSG MESSAGE BAD SIGNITURE FOUND MESSAGE INTEGRITY BROKEN November 2004 Page 88 version 3 1 1 IAgent3 User s Guide Administration NO CLIENT CERT SENT NO ISAID FOUND IN TPFILE NO PENDING REC FOUND OVERLOAD REFUSED INBOUND CONNECTION Refused inbound connection due to too many incoming messages No data has been lost RECEIPT BAD SIGNITURE FOUND RECEIPT INTEGRITY BROKEN RECEIVED MESSAGE FROM INACTIVE TP TOO MANY OPEN CONNECTIONS FROM TP TP ID MISSING FROM INPUT IA STATUS MSG UNKNOWN IPADDR SENT FROM CLIENT UNKNOWN ISAID FOUND UNKNOWN ISAID FOUND 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 November 2004 Page 89 version 3 1 1 IAgent3 User s Guide Administration CHAPTER 29 SECURITY ISSUES Post Installation Security Tasks Re Run tri
53. DEBUG AS tented dt dtes aod i e Metodo Morte ete eee 121 APPENDIX G GLOSSARY AND ACRONYMS eene nenenenenen ener ee eren n 122 APPENDIX H REFERENCES tou acte te a dere ette eret reete ee ot Peres ette eeu opes 125 INDEX oett ete acsi a actua M tates etta t och Mo A RRL COTE RRR Rare 127 November 2004 9 version 3 1 1 IAgent3 User s Guide Preface 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 Example 36 Example 37 Example 38 Example 39 Example 40 Example 41 Example 42 Example 43 An example of an EDI Input 20 1201 2 2 0 111 ener enne rre erre 48 An example of a typical ISA EDI Segment sessi 49 An example of a Basic Receipt input message eene enne nns 49 An example of an Integrity Receipt input message ssssssssssssseseeeeeeenee eene enne enne neris 49 An example of a Signed Receipt input eene ener nnns 49 An example of a Defined status input message
54. EH EEE HE FEE EH EE HE HE FF Local IN 1 iap name iap p00 endpoints EP IN 1 1 EP IN 12 EP IN 1 3 EP IN 1 4 end points aba a a aaa AE AE AE E AE aE aE AE AE aE aE FE aE aE aE AE AE E a aE ae aE AE E E aE a AE E FE a aaa aaa EP IN I 1 local partner id LOOPBACK remote partner id LOOPBACK ip address cOIZT3IOZXOT standard ip port 2000 hipri ip port 2001 session timeout 0 no resumable sessions ia message to tp BASIC EDI ia message from tp BASIC EDI ia receipt to tp NO RECEIPT ia receipt from tp NO RECEIPT Server status 1 November 2004 Page 116 version 3 1 1 IAgent3 User s Guide Appendixes FE aE aE E AE AE aE a IN 12 local partner id remote partner id ip address standard ip port hipri ip port session timeout ia message to tp ia message from tp ia receipt to tp ia receipt from tp Server status FEAE aE E aT AE AE AE aE a E FE F EP IN 13 local partner id remote partner id ip address standard ip port hipri ip port session timeout ia message to tp ia message from tp ia receipt to tp ia receipt from tp Server status FE AE IN 1 4 local partner id remote partner id ip address standard ip port hipri ip port session timeout ia message to tp ia
55. F the tee EINER 66 CHAPTER 24 TESTING INTEGRATION WITH BACKEND SYSTEMS 67 PART 5 IAGENT3 ADMINISTRATION n 68 CHAPTER 25 IAGENT3 OPERATIONS 158517 5 69 PRODUCT STARTUP ISSUES 2 ertt o ee Se an D RE Peu d te NONE Ld dene 69 TFAGENT3 DEBUG STARTUP ca es caida er bea Dele RO ed eet 69 OUTPUT rir iin Ra eet aed a bres 70 CHAPTER 26 IAGENT3 MAINTENANCE ISSUES eee ennemi nennen nnn 72 nee quee e e se a ete o e eS n po vie o eee e RR 72 ERR T nv e cate e ae c era 72 CHAPTER 27 TROUBLESHOOTING PROBLEMS AND ERRORS cem 75 TRANSACTIONS 76 INVALID MESSAGES cisco ret rre eee re epe ote ie tee rie en 76 TAGENT3 ALERT MESS AGES erect educa Fe ete e eie eicere por o eee e rre ie ee 76 IYEBUG MESSAGES e A s rene venas er br P sia dine SRO oe Ree d RR TS 76 CHAPTER 28 PRODUCT ERROR 55 7 0250 0 85 CHAPTER 29 SECURITY 55 5 90 POST
56. 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 November 2004 Page 28 version 3 1 1 IAgent3 User s Guide Configuration entropy FILENAME Entropy source file required for cryptographic calculations For Solaris product versions only vhack 0 1 Self signed issuer certificate verify hack flag sendstatus 0 1 Flag to force automatic sending of IAstatus messages when internal errors occur verbose 0 1 Flag to force verbose more messages to display and logs oneshot 0 1 Flag to force exit after a single IA message is sent or received For debug only raw 0 1 Flag to force sending of raw IA EDI messages For debug only packetmode 0 1 Flag to force sending of IA packet mode messages only For debug only savereceipts 0 1 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 Appendix C November 2004 Page 29 version 3 1 1 IAgent3 User s Guide Configuration lAgent3 command line arguments The second way to modify the way
57. HAPTER 14 MESSAGE RECEIPT 1 5517 5 43 RECEIPT MODES e rrt revertere tere TIO aetema cae e 43 Internal Receipt Mode ieu E eem ned iem pte edema 43 External Receipt Modes ettet aa He ie ve opertis eh aoe Res aaa 44 PART 4 INTEGRATION API REFERENCE 45 CHAPTER 15 INTEGRATION 46 BACK END SYSTEM BES LOCATIONS BY INTERFACE ccsccesseesseeseesecesecesecesecesecaecaaecaeecaeseaeeeaeseeeseeesrenaeenaeenaeenaeenaes 47 CHAPTER 16 OUTBOUND CLIENT 5 2 48 INPUT EDI MESSAGE FORMAT e EUER Hee eee e b b dece dece ea 48 RECEIPT INPUT MESSAGE FORMAT ccccecsessscececececsecsececececsenaseeecececeesessececececseessaseeeescsesessaaeeeesesenenaaeseeceseeesesaeeeeeeeees 49 IA STATUS INPUT MESSAGE FORMAT csessssssecececsessesececccecsesssaececececseesseseeececseesuececeeecseseaaaaeeeescseeeaueseeceeceesesaseeeeeeees 49 CHAPTER 17 INBOUND SERVER 5 51 EDI OUTPUT MESSAGE FORMATS ccccssssssscecececeesssscaececccsesesseaecesecscsensaaecesececsesaseceseceeseneuseaececccsesenaaececcescsensaaeeeeecsens 51 RECEIPT OUTPUT MESSAGE FORMATS cscssssssececeesessssececececeseaececececseseaseseeececseneaeeeeeeecseseaeaeeeecesceesnsaeseecesceensaaeeeeeeeees 52 IA STATUS OUTPUT MESSAGE 8 0 0 2 2 2 01 000000 0000
58. INSTALLATION SECURITY TASKS nane seen setate 90 GENERAL SECURITY SUGGESTIONS cccessssscecececsssseseceecceceenasecesececeessaseceeececeeeesseseeeeecseseseaeeeeseseneeaaeeeeeesceessaaseeeeeeens 90 SUGGESTED SECURITY 90 CERTIFICATE AND KEY ISSUES cccccccccsessssecececececsesscaececececsesaaececececeesessaaeceecesesensaaeeeeecscsessaeeeeeesceesaaeeeecesesensaaeeeeeeeees 90 OPERATING SYSTEM ISSUES i vA Gees etn i Fe io Fed EE EURO VU Y E OP P RAE EE Wives eee Uo d 91 OTHER2AGCESS ISSUES ese E o te ee ee dite vere o Tee Teen eS EFE ve Yoda 91 SUGGESTED FIREWALL RULES SET c cccscccccsesssssssscccecesesseseseeececseeseseesescsenssaeeeeececeesaeeeeececeeesseceeeesesenesssaeeeesesenenaaeees 91 CHAPTER 30 HOW 78 ene enne ener ener nnns enean senes n ese nsns sanas aua 92 SCOPEOFSUPPORT SERVICES EG E TREE Pe TU GE GR ATE OE REGERE 92 TRY THIS FIRST etre Ge rt ERR RT RR T PT ERG T e TER ea 92 CONTACTLYMEWARE PRODUCT SUPPORT ertet er hr ve re eee reote eee deed 93 APPENDIXES tae tt in tet adem ed 94 APPENDIX A CONFIGURATION WORKSHEETS AND FORMS eee 95 PRE INSTALLATION WORKSHEET eerte enne nennen entre eere trn
59. NNOT 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 November 2004 Page 86 version 3 1 1 IAgent3 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 This message describes a successful IA connection but the server is unable to read data from the remote IA client 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 can be caused by s
60. NNOT OPEN OUTPUT FILE 12 ERRM CANNOT WRITE OUTPUT FILE 11 UNSUPPORTED MESSAGE 10 ERRM CANNOT GENERATE EDI MSG FILE 9 ERRM UNKNOWN MSG TYPE IN TPFILE 8 Table 10 IAgent3 Error Numbers November 2004 Page 73 version 3 1 1 IAgent3 User s Guide Administration ERRM UNKNOWN RECEIPT MSG TYPE IN TPFILE IA ERRM UNKNOWN TYPE OF MSG FOR TP A ERRM CANNOT ALLOCATE CTX A ERRM CANNOT ALLOCATE SSLCTX A ERRM CANNOT ALLOCATE CLIENT SOCKET ERRM CANNOT READ OWN CERT A ERRM CANNOT READ OWN KEY SUCCESSFUL TRANSMISSION A ERRM UNSUPPORTED INPUT MSG FOUND ERRM UNKNOWN ISAID FOUND IA ERRM UNKNOWN ISAID FOUND IN CERT A ERRM NO ISAID FOUND IN TPFILE ERRM CANNOT CONNECT TO REMOTE SERVER A ERRM CANNOT START CLIENT HANDSHAKE ERRM CANNOT WRITE SSL CLIENT A ERRM CANNOT READ SSL SERVER A ERRM CANNOT FIND SUBJECTNAME IN CERT hA ana ERRM
61. OCKETS LAYER SSD GO NER BE rt eie E 13 SESSIONS ESTABLISHMENT ceri REO Ee dte ee tus qe repeto t ete eee o er RCE IE dedos Pet ds 13 KEY EXCHANGEMBTHOD 5 5 A E Litt e e Os OEIC Bo ce 14 CIPHER EOR SDEAT A T RANSEER ette ero ote E OTE CI BONERS 14 DIGEST EUNGTION c redet eene E ELA Pe re RATER PE BONN see e REECE 14 HANDSHAKE SEQUENCE PROTOCOL Pe REEL COO RE E ae 15 DATA TRANSEEBR 0 eod uL ED M ILE 15 PART 2 IAGENT 3 INSTALLATION 5n 16 CHAPTER 4 INSTALLATION OVERVIEW 17 REQUIRED DOCUMENTATION sccsessscseccecsessnecceceecsesesececececseseaeceeccecsensaseceeececeensseeeeeseeseenseaeeeeccscsessaaececececsensaaeeeeeeeens 17 CHAPTER 5 18 November 2004 version 3 1 1 IAgent3 User s Guide Preface PRE INSTAELATION TASK INSTRUCTIONS Pene eges 18 1 Completing the pre install worksheet 18 2 Acquiring root access on the target machine esee eee eene eren eene 18 3 Acquiring the correct software for your machine eese eene enemies 18 4 Requesting the license file eet eee cpe n eae Pe eee 19 5 Hardware connectivity ISSUES ois
62. ObOTpghHTGlwClltX7u IVfEUliBfd7m2BEUC7e7lftfHgzAjvWStCFgkYly3kg7Zh6jPALu0 DFYzmPtMZ VTft d 49NoX5R ZEM eKJXSIOCUk7ZUriFPfkRsdDdcz7AfW99rHA EAS END RSA PRIVATE KEY Example 43 Sample Private Key The CSR file should then be sent to the appropriate Certificate Authority approved by both trading partners the local and remote in their joint implementation agreement The Certificate Authority will then provide signed certificate file with themselves the issuers November 2004 Page 110 version 3 1 1 IAgent3 User s Guide Appendixes APPENDIX C SAMPLE CONFIGURATION FILES The following files may be used as samples but should not be used without modification A digital soft copy of these files may be found under opt iagent3 examples after installation System or lAgent configuration file A simple example of the IAgent3 configuration file f IAgent3 example Process configuration file default section process names std svr hpr svr receipt p00 clientp system wide settings interface dir debug 4125 verbose clusternum loopbackdelay sloppyallow sloppyinactive cachesize receiptmode vhack raw tpartner
63. RTNER 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 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 opt iagent3 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 R
64. TM 097 990629 124849 21 19 MIT 000000001 MSG 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 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 MSG 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 MSG This is a test message line 14 MSG This is a test message line 15 MSG This is a test message line 16 MSG This is a test message line 17 MSG This is a test message line 18 MSG This is a test message line 19 MSG This is a test message line 20 CTT O SE 26 000000001 GE 1 000001 IEA 1 000000001 20000417 035850 iagent 5355 End of RAW Input Data 4 Example 27 An example of Debug Transaction Data Messages 20000417 035851 C US ST Connec iagen ticut Old 5355 Certificate Verification Lymeware Corporation OU IAgent O depth 1 subject Development CN LymewareDem oCA C US ST Connecticut L Old Development CN LymewareDem 20000417 035851 iagent 535 20000417 035851 C US ST Connec iagen ticut O Lym oCA Email sec O Lymew Email sec 5
65. Trading Partner 1 receives the IA Receipt message Message Recelpt Data Flow LARecegpt Missa Figure 6 Message Receipt Data Flow There are currently four versions of IA receipts supported by the IAgent3 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 A basic receipt which consists of the ISA segment of the EDI message 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 SSL 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 November 2004 Page 41 version 3 1 1 IAgent3 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 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 requir
66. 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 IAgent3 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 iagent3 iastart To start the IAgent system or touch opt iagent3 iastop To stop the IAgent3 system listen This is a shell script which can detect and display IAgent3 processes listening on the IA ports monitor This is a shell script which displays all IAgent3 processes currently running Is may be started in a second window and used to monitor the IAgent3 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 was started with the etc rc3 d 90prng startup script pm This shell script is used to display the status of a currently running IAgent3 system Transaction details and alerts will be displayed in a summary report pmloop This shell script is used to run the pm script above on a periodic basis debugia This shell script is used to run the IAgent3 system in debug mode with verbose debug messages
67. ace TYPE Input client or output server interface supported May be any of the following file dir socket or optionally tibco November 2004 Page 26 version 3 1 1 IAgent3 User s Guide Configuration pacing delay MSECONDS Pacing delay for each transaction in milliseconds process type TYPE Type of process for section This values can be STD SERVER PROCESS HPR SERVER PROCESSS RECEIPT PROCESS FAILOVER PROCESS IAP PROCESS or CLIENT PROCESS E receiptmode MODE Receipt mode supported May b ither internal or external tpartner FILENAME IAgent3 trading partner configuration file name default is tpartner conf transport listen port ADDRESS Process specific transport listen IP address and port in the form of addresss port Process Specific configuration options These options set the IAgent3 Server ports both standard and hi priority ports hipriport PORT High priority server port for IAP process only stdport PORT or port PORT Standard server port for IAP process only Certificate and Key location options These options describe the location of all certificates and private keys in the IAgent3 system key FILENAME Own local private key file in PEM format cert FILENAME Own local certificate file in PEM format CAfile FILENAME Cer
68. ack Self signed issuer certificate verify hack flag r raw 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 u usage help Displays this usage page v verbose Flag to force A LOT of logging to stdout and log files Table 6 IAgent3 Command Line Arguments continued November 2004 Page 32 version 3 1 1 IAgent3 User s Guide Configuration w sendstatus Flag to force automatic sending of IAstatus messages when FILENAME 2 FILENAME internal errors occur cert FILENAME cert file FILENAME Own local certificate file CAfile FILENAME Certificate Authority CA in PEM format file in PEM format November 2004 Table 7 IAgent3 Command Line Arguments concluded Page 33 version 3 1 1 IAgent3 User s Guide Configuration Default Agent3 configuration values and settings The IAgent3 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 IAgent3 configuration option Default display sloppyallow off
69. ading partner as required When finished the Agent 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 any SSL communications All 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 entries 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 ISA05 or ISA06 segment 15 characters maximum as per ANSI X 12 remote_partner_id This is the remote trading partner identifier as found in the EDI ISA05 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 The trading partner s IP address as a string AAA BBB CCC DDD Table 6 Trading Partner Configuration Fields November 2004 Page 36 ve
70. airs Copyright c 2001 Lymeware Corporation All rights reserved using OpenSSL 0 9 7d 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 unknown option help csr options gt outfile where options are reqform arg request format one of DER TXT PEM with PEM as default reqout arg request output file stdout as default keyform arg key file format one of DER TXT PEM with PEM as default keyout arg private key output file rsakey bits generate a new RSA key of bits in size Gonfig fil request template fil text text form of request nodes don t encrypt the output key asnl kludge Output the request in a format that is wrong but some CA s have been reported as requiring It is now always turned on but can be turned off with no asnl kludge Example 39 Command line arguments for gen csr A 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 November 2004 Page 107 version 3 1 1 IAgent3 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 Lymew
71. alty 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 The SSL3 0 protocol specification defines 31 Cipher Suites A Cipher Suite is defined by the following components November 2004 Page 13 version 3 1 1 IAgent3 User s Guide Introduction Key Exchange Method Cipher for Data Transfer Message Digest for creating the Message Authentication Code MAC These three 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 u
72. are 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 aa ar al Rr 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 US US State or Province Name full name Connecticut Locality Name eg city Old Lyme Organization Name eg company Lymeware Corporation Organizational Unit Name eg section Common Name eg YOUR FQDN 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 40 Using gen csr to create a PEM Certificate Signing Request November 2004 Page 108 version 3 1 1 IAgent3 User s Guide Appendixes tools gen csr keyout newkey
73. ated 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 November 2004 Page 72 version 3 1 1 IAgent3 User s Guide Administration The message type is the delivery priority of the inbound or outbound message and may be either of the following STANDARD PRIORITY 0 HI PRIORITY 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
74. ave to reside on the same platform as the IAgent3 system These interfaces are described in the Web Services Description Language WSDL format see Appendix ZZ November 2004 Page 6 version 3 1 1 IAgent3 User s Guide Introduction optional Tibco TIB Rendezvous message bus interface reads input Tibco messages with single subscriber and writes output Tibco messages with multiple publishers supporting multiple platforms 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 IAgent3 uses standard SSLv3 or TLS 1 0 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 levels 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 IAgent3 system is the Public Key Infrastructure PKI comprised
75. ber 16 1998 TCIF 98 006 Issue3 Electronic Communications Interactive Agent Functional Specification TCIF 98 006 Issue 3 December 8 1999 SSLv3 Netscape The SSL Protocol Version 3 November 18 1996 Communications RFC2246 IETF The TLS Protocol Version 1 0 January 1999 200 Recommendation X 200 Reference Model of Open Systems Interconnection for CCITT Applications 1984 208 Recommendation 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 Models 1988 X 509 CCITT Recommendation X 509 The Directory Authentication Framework 1988 520 Recommendation X 520 The Directory Selected Attribute Types 1988 RFC1421 IETF Privacy Enhancement for Internet Electronic Mail Part I Message Encryption and Authentication Procedures February 1993 422 5 Kent Privacy Enhancement for Internet Electronic Mail Part II Certificate Based Key Management February 1993 PKCS 1 IRSA Laboratories PKCS 1 RSA Cryptography Standard version 2 0 September 1998 PKCS 6 IRSA Laboratories PKCS 6 Extended Certificate Syntax Standard version 1 5 November 1993 PKCS 7 IRSA Laboratories PKCS 7 Cryptographic Message Syntax Standard version 1 5 November 1993 PKCS 8 IRSA Labo
76. cnaeceaecaaecaeecaeeeaeeeeeenreeerenseens 77 An example of Debug SSL Handshake State Messages Client side 78 An example of Debug SSL Handshake State Messages Server side sss 78 An example of Debug Transaction Data Messages eene enne 79 An example of Debug Certificate Messages Client side 79 An example of Debug Certificate Messages Server 1 2 80 An example of Debug Certificate Messages Server side continued sss 81 An example of Debug ASNI Messages ccccescsssesssesseeeseeeseeeeeeeeeeseeesecnsecsaecsaecnaecaeecaeecaeesaeeneeserenerenarees 82 An example of Debug Parsed ASN1 Messages essere enne nnne 82 An example of Debug Parsed ASN1 Messages continued sse 83 An example of Debug RSA Key 1 4 1 nnne nennen 83 An example of Debug Receipt eren ener nnne eren nennen 83 An example of IA Timer 84 Example EDI ISA Segment wrapped nennen enne enne enne nnn nnns 86 gen csr Configuration File Request 4 106 Command line arguments for gen Csr sssssssssssssssesseeeeene 107 Using gen csr to create a PEM Certificate Signing
77. 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 Agent3 operation Problem Reporting Form This form should be used for any problems encountered which can be reported back to Lymeware Table 14 IAgent3 Product Worksheets These worksheets may be copied for use in maintaining your IAgent3 system Completed worksheets should be used during product instillation and configuration and should be saved with other machine documentation for future use Digital versions of these worksheets are available at the Lymeware web site http www lymeware com products html November 2004 Page 95 version 3 1 1 IAgent3 User s Guide Appendixes For IAgent3 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 Soft
78. 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 November 2004 Page 109 version 3 1 1 IAgent3 User s Guide Appendixes I ict BEGIN CERTIFICATE REQUEST MIGyMIGnAgEAMEIXCZAJBgNVBAYTAlVTMRQOwEgYDVQOIEwtDb25uZWNOaWNl1dDEd MBsGAlUEChMUTHltZXdhcmUgQ29ycG9yYXRpb24wXDANBgkqhkiG9wOBAQEFAANL ADBIAkEAy9g5SaqvZ2Bv82MftHF3Ns80xq4520V vxzieQPOj8gjkS7SeShFTSoU dEgO0pWOX6R58HMFBRJ9KC8Rid03FNwIDAQABOAAwAwYBAAMBAA ee END CERTIFICATE REQUEST Example 42 Sample PEM Certificate Signing Request Example 45 shows a private key for the certificate being created in newkey pem This 1s 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 ZI BEGIN RSA PRIVATE KEY jvOTuymeQBjZFYfzlLtOzlnPj8giZ2DZ84TByqe8LevjudN96sg3HLiWIBzelL E LYiqFCcW6RFO57qU5rkn6jAvrD7DGeUdNmfKoie3RisXSPC hmoWE7PO9xCVPvGkx gXwOv5FtC3IPBjKiNFamlHanu44yJi92yFR5BuA jJKTLK50Y12aJHuEqTLC1J4D ch4qsNTqeLSSyxOE2gX9 w20DhnlIuKKTjcSIuK8jNKfDArVaHedlIGM1pI5JCwoD N552yNI16qjEwBgfbgWRsu8DYbMiGsSra37Jd oJpZ2jOKr
79. ctivity 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 ofthe 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 administrator 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 November 2004 Page 39 version 3 1 1 IAgent3 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
80. d ret n unless ret RVMSG OK Add IA message priority as RWUMSG INT ret rvmsg Append S 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 S session rvMessage strlen rvMessage data RVMSG STRING IAlength IAmessage die rvmsg Append ret n unless ret RVMSG OK now send it ret rv Send S session subjectname RVMSG_RVMSG 0 rvMessage die rv Send ret n unless ret RV rv Term S session Example 22 Tibco API Writer Example November 2004 Page 66 version 3 1 1 IAgent3 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 Agent 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 Test each input message format independent of Integration API 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 gent client see Chapter 25 on how to start a standa
81. dard that defines the fields field names and abbreviations used to refer to the fields November 2004 Page 103 version 3 1 1 IAgent3 User s Guide Appendixes Field Abbreviation Description Example Name being certified Typically the fully CN www Common Name CN qualified domain name FQDN e g host company com panewarecom pany co Organization or Company O Name is associated with this organization O Lymeware Corporation S Name is associated with this organization unit Teemana nh such as a department This field is often blank 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 16 Distinguished Name Information A Certificate Authority may define a policy specifying which distinguished field names are optional and which are 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 T
82. ding 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 November 2004 Page 119 version 3 1 1 IAgent3 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 IA Ping Status Messages This feature has been added to the current proposed next version of the TCIF IA standard Issue 3 See Chapter 16 for more information on IA Ping status messages November 2004 Page 120 version 3 1 1 IAgent3 User s Guide Appendixes APPENDIX F PRODUCT UTILITIES The following utilities are packaged with the IAgent3 product and may be used during installation configuration or testing monitoring of the system 1 This is a utility from Peter Gutmann http www cs auckland
83. dustry Solutions 4 ASN 1 asymmetric cryptography B BES C cryptographic algorithm E Electronic Interactive Agent F FCC 1994 Telecommunications Act I Interactive Agent O OpenSSL cryptography toolkit Operational Support System OSS PKI PKIX November 2004 4 10 Page 127 Public Key Infrastructure RSA keys RSA PKCS 5 symmetric cryptography T TCIF TCIF 98 006 TCIF 98 016 TCP IP Telecommunications Industry Forum Tibco TIB Rendezvous TLS Trading Partner Transaction Layer Security Value Added Networks VAN WwW Web Services x X 509 server certificates Appendixes ANN See TCIF NUNDA version 3 1 1
84. e Ne eo sede e Ee ed 90 Table 14 IAgent3 Product 95 Table 15 Certificate Information Elements sese nrenne 103 Table 16 Distinguished Name Information sessi enn en nr en rennen nennen nennen nenne 104 Table 17 National International Internet and Industry Standards used by this product 125 Table 18 National International Internet and Industry Standards used by this product concluded 126 Table 19 Commercial or third party documentation used by this product or eese 126 November 2004 xii version 3 1 1 IAgent3 User s Guide Preface Preface Software Version This guide is published in support of Lymeware Corporation s IAgent3 software product version 3 1 1 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 IAgent3 system Knowledge of TCIF 98 006 Issue 2 and Issue 3 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 IAgent3 system as described by TCIF98 006 Issue 2 and Issue 3 This manual is divided into five parts and several appendixes Part 1 covers
85. e e qp eq eee abs ge e be ede nee eene eret ede gue pe setae 28 Optional Tibco Interface Options esses 28 ADVANCED AND SPECIAL OPTIONS sesccscsiceceieses 28 IAGENT3 COMMAND EINE ARGUMENTS 30 DEFAULT IAGENT3 CONFIGURATION VALUES AND SETTINGS 2 34 CHAPTER 10 TRADING PARTNER ADMINISTRATION eere enne 35 TRADING PARTNER MAINTENANCE aeiiae cesiestscestenisceesctrscesteaticeriesesdessoaiiceonctedeesscnsiceunettedestendbiestesedsestentesectestesessens 35 ADDITION OF A NEW TRADING PARTNER iii raia r n AA AEA A EA AAAA EAE E 35 REMOVAL OF A CURRENT TRADING en en nennen eene retener trennen nennen enne nenne nnns 36 MODIFICATION OF A CURRENT TRADING PARTNER eee ee n e n n ene nenne 36 THE TRADING PARTNER CONFIGURATION FILE E nennen nnne nennen nennen nennen nennen rennen enne nnne 36 November 2004 6 version 3 1 1 IAgent3 User s Guide Preface CHAPTER 11 TRADING PARTNER 2 2 38 SIMPEE TBENET FESTINGz e DE S er viria costo ob cae vats durer ve ab ae 38 CHAPTER 12 MULTIPLE TRADING PARTNER ISSUES eene 40 CHAPTER 13 MESSAGE RECEIPT 4 C
86. e need 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 LWC7 ZZ LWC TEST 990629 1248 U 00307 000002317 0 T Example 8 A typical ISA EDI segment A typical output EDI message is as follows lines NOT wrapped ISA 00 IAGENT 00 TEST SOLO TPL 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 MSG 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 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 MSG 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 MSG This is a test message line 14 MSG This is a test message line 15 MSG This is a test message line 16 MSG This is a test message line 17 MSG This is a test message line 18 MSG This is a test message line 19 MSG This is a test message line 20 CTT O 5E 26 000000001 GE 1 000001 IEA 1 000000001
87. e stored as a file see Directory Interface Mode Chapter18 for file details in the 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 the S ADDRESS or outsocket ADDRESS options Be sure to include a port in the address All 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 November 2004 Page 55 version 3 1 1 IAgent3 User s Guide Administration CHAPTER 20 WEB SERVICES API INTEGRATION Web Services Interface Mode The Web Services 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 All 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
88. ed by Lymeware Corporation to grant such a license This Manual is O Copyright 1999 2004 Lymeware Corporation Old Lyme Connecticut USA All Rights Reserved 2004 IAUG311 0011 IAgent3 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 iii IAgent3 User s Guide Preface Page iv IAgent3 User s Guide Preface Contents E tees X BS tiet e E ndm E Ree be attese eat XI LIST OR TABLES ee tette ele XII PREFAC A AAO XIII DOETWARE VERSION eter e EET DEN RU UI in e ae E E XIII READERSHIP edat d oon te tue E XIII SCOPE OF THIS GUIDE eer etse d he EP E TOO I GE ER CREER GE TE eR EU XIII MANUAL REVISION HISTORY 2505 ne tton RT A OR TEE REG ER A IEEE XV SUPPORT QUESTIONS AND BUG REPORTING cc ccccsssscecssscecessnseecseseeecseaeecssseeecsesaeeecsesaecessaeecsesaesecseaaesecsnsaessesaeeeceagas XVI DOCUMENTATION CONVENTIONS aa E pv e cr e v E P T EGER Gee ER tel
89. ed 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 i 3 partner i isaid TP 1 strp TP 1 20000417 035852 iagent 5348 No receipt required for TP 1 20000417 035850 iagent 5355 i 4 partner i isaid TP TWO strp TP TWO 20000417 035850 iagent 5355 AE2ENR i2d IA EDI MSG signed returned a 1422 Example 24 An example of Basic Debug Messages November 2004 Page 77 version 3 1 1 IAgent3 User s Guide Administration 20000417 035850 iagen 20000417 035850 iagen 20000417 035850 iagen 20000417 035850 iagen 20000417 035850 iagen 20000417 035850 iagen 20000417 035850 iagen 20000417 035850 iagen 20000417 035851 iagen 20000417 035851 iagent 5355 PKI verify cert 20000417 035851 iagent 5355 5SL connect SSLv3 read server certificate t 5355 t t t t t t t t t 20000417 035851 iagent 5355 551 connect SSLv3 read server certificate request A t t t t t t t t t t t 5355 5355 5355 5355 5353 5355 5355 5355 CTX is NULL loading CTL fill stuff only loaded CTX return 0 CACHED SESSION lookup GENERATING A NEW SESSION 0 CTX already loaded skipping CTL fill stuff SSL is NULL loading SSL with 551 new SSL connect before connect initialization SSL_connect SSLv3 write client hello SSL_connect SSLv3 read s
90. ed for each IA EDI message sent to the remote trading partner November 2004 Page 42 version 3 1 1 IAgent3 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 IAgent3 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 exists The second message will not generate a pending receipt record IAgent3 allows a third party or external process to send an external receipt message to the remote trading partner through the IAgent3 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 IAgent3 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 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 IAgent3 system will generate the appropriate pending receipt for each outbound IA EDI message and will send the appropr
91. ed 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 The 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 The initial state of this trading partner s IA server 0 not operational 1 active Table 7 Trading Partner Configuration Fields continued An example of a standard trading partner configuration file may be found in Appendix C November 2004 Page 37 version 3 1 1 IAgent3 User s Guide Configuration CHAPTER 11 TRADING PARTNER CONNECTIVITY It is required that the IAgent3 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
92. emoval 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 trading partner file November 2004 Page 35 version 3 1 1 IAgent3 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 ofthe 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 Agent 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 tr
93. en FIFO lt FIFO die can t read FIFO read length my binary 5 read FIFO binary 2 my S IAlength unpack N binary read priority my binary 5 read FIFO binary 2 my IApriority unpack N binary read data read FIFO IAdata SIAlength Example 19 Web Services API Reader Example Web Services API Writer Example FIFO opt iagent iapipe while 1 next line blocks until there s a reader open FIFO gt FIFO die can t write FIFO 1 store length my binaryl pack N IAlength store priority my binary2 pack N IApriority write it all print FIFO SIAlength IApriority 1Adata close FIFO sleep 2 to avoid dup signals Example 20 Web Services API Writer Example November 2004 Page 64 version 3 1 1 IAgent3 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 SIApriority Callback sub to print the messages sub my callback my session name replyName msgType msgSize msg arg a if SmsgType RVMSG_RVMSG then look for our three fields IA message length ret rvmsg_Get session msg length msgType msgSize SIAlength die rvm
94. ept SSLv3 read client certificate 8 DEBUG Getting Client s certificate kghkiG9wOBAQOFADC RpY3VOMREwDwYDVOOHEwh 9yYXRpb24xGzAZBgNVBASTEkl1BZ2VudCBEZXZ BsTELMAkGA1UEBhMCVVMx PbGOgTHItZzTEdMBSsGAl1UE 1bG9w EAxMOTH1tZXdhcmVEZW1VQOEXJDA LmNvbTAeFwO5OTEyMTYwMjA DVOOGEwJVUZ LHiGFdY5nt DQ 0 T Ew5MeWl1ld2FyZURlbW9DOTEkMCIGCSqGSIDb3DO 3 7 m50F7Zpf9MIHeBgNV O4ABurW9u2VQfNjwoYG3pIGOMIGxMOswCOYDVQOG 1 b3Jwb3JhdGlvbjl EUMBIGALUECBMLQ2 9 Ex 5bWV3YXJLIENvVcnBvcmF0aW9uMRswGOQYDVOQO cG11lbnQxDTALBgNVBAMUBFROQXz cmUuY29tMIGfMAOGCSqGSIDb3DO 6ASZbAkaWMordDqsNxIc7RJ ExIDAeBgkqhkiG9wO0 EBAQUAAAGNADCBiOK cdam5G2dkD71Bb7EDMoi ETAPBgNVBACTCE9sZCBMeW11MROwGwY ECxMSSUFnZW5OIERldmV I iBgkqhkiG9w0BCQEWFXN1 5NTBaFwOwMDEyMTUwMjA5 ubmVjdGljdXOxHTAbBgNV ExJJYWdlbnOgZGV2ZWxv BCOEWEW5vbmVADbHltZXdh BgODiNrXXQSCPQ3LqmCgO KReEUK SxRVAKNBS13KIi CbXYE G kObywoSYXu7ImBvobkhkD8Xj cM1HyU dMnZTj3 rQc9hFSlozsaTN6OK3OIDAQABOAIBPTCCATkwCQY hkgBhvhCAQOEHxYdGT3BlblNTTCBHZW5lcmFOZWOgO2VydGlmaWNhdGUwHQY BBYEFN54YgJJsAq801pCwI DVROTBAIwADAsBglg DVROO HSMEgdYwgdOAFC7 bnL1D0B 4 EwJVUZEUMBIGA1UECBM 029u Sb3BtZW50MRcwFQY EJARYVc2VjdXJpdHlAbHl DVOOKEXRMeW11d2FyZSBD DVOOD tZXdh EBBAUAA4GBAGOXsOLSHrPwhn dajBZ1stUQxn vBWiad3gRb3KD6huY1V lrs9v7VOyeRsIp9iJRZ
95. er 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 WAN 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 November 2004 Page 50 version 3 1 1 IAgent3 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 messag
96. erver hello GE ct ct 20000417 035851 iagent 5355 5SL connect SSLv3 read server done 20000417 035851 iagent 5355 5SL connect SSLv3 write client certificate 20000417 035851 iagent 5355 5SL connect SSLv3 write client key exchange 20000417 035851 iagent 5355 5SL connect SSLv3 write certificate verify 20000417 035851 iagent 5355 5SL connect SSLv3 write change cipher spec 20000417 035851 iagent 5355 5SL connect SSLv3 write finished 20000417 035851 iagent 5355 5SL connect SSLv3 flush data 20000417 035852 iagent 5355 551 connect SSLv3 read finished 20000417 035852 5355 551 connection using DES CBC3 SHA 20000417 035852 iagent 5355 SSL Session 20000417 035852 iagent 5355 SSL Handshake DONE PE CL CU COP CE FF CT Example 25 An example of Debug SSL Handshake State Messages Client side 20000417 035850 iagen 20000417 035850 iagen 20000417 035850 iagen 20000417 035850 iagen 20000417 035850 iagen 20000417 035850 iagen 20000417 035850 iagen 20000417 035851 iagen 20000417 035851 iagen 20000417 035851 iagen 20000417 035852 iagen 20000417 035852 iagen 20000417 035852 iagen 20000417 035852 iagen 20000417 035852 iagen 20000417 035852 iagen 20000417 035852 iagen 20000417 035852 iagen 20000417 035852 iagen 5348 5348 5348 5348 5348 5348 5348 calling SSL
97. ess 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 ip address standard ip port hipri ip port November 2004 Page 85 version 3 1 1 IAgent3 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 ISA08 The Trading Partner Receiver ID TWO in the example below ISA 00 IAGENT 00 TEST 7777 1 ZZ TP TWO 990629 1248 U 00303 000000001 0 T Example 37 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 GENERATE EDI MSG FILE This message can be caused by system resource problems file permission errors or an existing duplicate file CA
98. essages 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 changes 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 lymeware com November 2004 xvi version 3 1 1 IAgent3 User s Guide Preface Documentation Conventions 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 Example iagent conf file Bold Bold type is used for key term
99. essages with multiple publishers supporting multiple platforms November 2004 Page 46 version 3 1 1 IAgent3 User s Guide Administration 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 IAgent3 product Directory Note network or network mounded drives are not recommended for working directories Socket Any IP connected machine Web Services Tibco Any IP connected machine on same subnet Note the use of Tibco s rvrd is not recommended Table 8 BES Locations supported by Interface November 2004 Page 47 version 3 1 1 IAgent3 User s Guide Administration CHAPTER 16 OUTBOUND CLIENT FORMATS The IAgent3 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 IAgent3 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 Agent
100. f IA Timer Messages November 2004 Page 84 version 3 1 1 IAgent3 User s Guide Administration CHAPTER 28 PRODUCT ERROR MESSAGES Descriptions and possible solutions for specific Agent3 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 IAgent 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 network connection used to reach the remote IA server The remote IA may be behind a firewall and the firewall may not allow acc
101. guration and configuration files When this has been successfully completed run the following to start Agent3 as a system daemon with the following command su root c etc rc3 d S99iagent start Example 23 Starting Agent3 as a system daemon Sun Solaris Only It is assumed that the PRNG daemon was already started prior to the above command This daemon is also automatically started on boot At this point the Agent 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 Debug Startup A debug startup script is provided in opt iagent3 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 IAgent3 system To run the IAgent3 system in debug mode the following steps need to be done 1 login to the IA machine as root 2 change the working directory to opt iagent3 3 stop the IAgent3 system if it was running 4 start the IAgent3 system with the new debug startup script as detailed below November 2004 Page 69 version 3 1 1 IAgent3 User s Guide Administration The root user will then be able to start stop the IAgent3 system in debug mode manually by typing or
102. he 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 requires 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 is 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
103. he data will be lost See Appendix D for a sample simple BES Integration API test plan November 2004 Page 60 version 3 1 1 IAgent3 User s Guide Administration CHAPTER 23 EXAMPLE INTEGRATION API CODE SAMPLES The following code samples demonstrate how to interface to each of the supported Integration APIs All 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 loop foreach file glob DIR open FILE file die can t read file read entire message read FILE 1Amessage 128 1024 sleep 1 dir loop read delay Example 15 Directory API Reader Example Directory API Writer Example DIR opt iagent dir in my file DIR fn Counter my file2 file open FILE gt file2 die can t create write to file2 write entire IA message to file2 in single print print FILE 1 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 November 2004 Page 61 version 3 1 1 IAgent3 User s Guide Administration Socket API Code Samples Socket Reader Example
104. iate 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 November 2004 Page 43 version 3 1 1 IAgent3 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 in IAgent3 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 IAgent3 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 November 2004 Page 44 version 3 1 1 IAgent3 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 November 2004 Page 45 version 3 1 1 IAgent3 User s Guide Administration
105. ic Constraints CA FALSE Netscape Comment OpenSSL Generated Certificate X509v3 Subject Key Identifier DE 78 62 02 49 B0 0A BC D3 5A 42 C0 81 E X509v3 Authority Key Identifier t ct E7 41 7B 66 97 FD keyid 2E FF 6E 72 F5 0F 40 7E 3B 80 01 BA Bb BD BB 65 50 7C D8 FO DirName C US ST Connecticut L Old Lyme O Lymeware Corporation OU IAgent Development CN LymewareDemoCA Email security lymeware com serial 00 Signature Algorithm md5WithRSAEncryption 6 17 3 42 4 2 1 53 0 86 7 94 6 30 59 96 54 43 19 fe e2 b6 79 14 2a 13 0d9 32 17 db 27 a2 8e 0a 86 08 13 7b bc 15 a2 69 dd e0 45 bd ca 0f a8 6e 63 55 7f d6 le af 6 fb c8 6a c1 d3 90 ba al c3 9d c9 2b 82 6f ed 17 da 56 41 9f 33 2a 30 54 0d 6b 14 7d b6 56 ca d5 7d 20 88 00 70 59 0 4 6 5 86 3 0 2 41 d3 e0 Example 30 An example of Debug Certificate Messages Server side continued November 2004 Page 81 version 3 1 1 IAgent3 User s Guide Administration 20000417 035850 iagent 5355 Adding IA specific ASN 1 Object Identifiers 4 20000417 035850 iagent 5355 1 3 6 1 4 1 3576 7 IA X12 eciaAscX12Edi 1 3 6 1 4 1 3576 8 IA EDIFACT eciaEdifact
106. ice of digest function determines how a digest is created from a record unit SSL supports the following November 2004 Page 14 version 3 1 1 IAgent3 User s Guide Introduction No digest Null choice MDS a 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 underlying 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 Da
107. ide 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 November 2004 Page 9 version 3 1 1 IAgent3 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 Agent users by pulling together various concepts definitions and examples as a starting point for further exploration For more detailed information 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 a
108. ied 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 November 2004 Page 58 version 3 1 1 IAgent3 User s Guide Administration CHAPTER 22 TESTING INTEGRATION API CONFIGURATIONS Because of the IAgent3 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 API support testing Figure 12 Integration 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 Agent 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 Agent process read write and execute
109. ificate Authority Digital non repudiation by both the sending and receiving Trading Partners November 2004 Page 2 version 3 1 1 IAgent3 User s Guide Introduction Supports current and emerging Public Key Infrastructure PKT security standards including RSA PKCS and IETF PKIX standards support Supports transaction receipts with multiple levels of validation customized by trading partner Supports multiple levels of message validation on each transaction customized by trading partner The following cipher suites are supported by the IA standard RSA NULL SHA Basic authentication without encryption RSA DES CBC SHAI Authentication with DES encryption and RSA 3DES CBC SHAI Authentication with triple DES encryption More information on supported cipher suites can be found in TCIF 98 009 All 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 IA V2 only Enhanced EDI Security with Non Repudiation includes SSL encryption and signed message integrity Receipt types No receipt Basic Receipt with Security SSL encryption only Enhanced Receipt Security with message integrity sup
110. ion 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 iagent 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 iagent3 examples directory Copy this example file to opt iagent3 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 IAgent3 system cachesize ENTRIES Server session cache size in session entries clusternum NUMBER Cluster number of IAgent3 system config FILENAME IAgent configuration file name default is iagent conf iaversion VERSION IA version for an IAP process May be either 2 or 3 interf
111. ireas ieia e Ee E VE EE E EEA SEEE enne 19 CHAPTER 6 PRODUCT 2 1 1 242 024402 000068000000000000008000 500000000000 20 CHAPTER 7 POST INSTALLATION T ASKS 1x jcicicdjstncsasdaasdectobsntcdenatevedssctunteGssedesdatscvcseseasanads 21 POST INSTALLATION T ASK INSTRUCTIONS 4 5 lt cscssesiescssesecnestessesenteacenestestenes teacenesteatenesteacouestestobes ivt eee AS SKEE eerie ge 21 I Installing the Ticenseilez o iustos oo tet aset t e bitu t ge ae 21 2 Installing local CertifiCates and keys ret ee eee te piii ete be 21 3 Creating the Agent3 configuration eene nre nhe nenne nete rre 21 4 Verifying PRNGD installation and configuration Sun Solaris versions only eee 21 5 Creating the Trading Partners configuration nete eere 22 6 Testingdntegration APL Connectivity tii ette etes see e etin it eene eee birra atone hea iere eee s 22 Ze Testing Trading Pariner Connectivity ed cei est tete e itd pee e pi eter Eee ep teca 22 8 Post Install Security Tasks teer ur etes tae ees 22 PART 3 IAGENT3 CONFIGURATION 23 CHAPTER 8 CERTIFICATE AND KEY GENERATION AND INSTALLATION 24 CERTIFICATE AND KEY GENERATION AND CONFIGURATION seen ee ee e een en eren en eren nnne 24 1 Selecting a third party Certificate Auth
112. lone 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 November 2004 Page 67 version 3 1 1 IAgent3 User s Guide Administration Part 5 lAgent3 Administration Part 5 of this manual contains IAgent3 administration information including operations tasks maintenance issues and troubleshooting guidelines This section also includes security recommendations November 2004 Page 68 version 3 1 1 IAgent3 User s Guide Administration CHAPTER 25 IAGENT3 OPERATIONS ISSUES Product Startup Issues The IAgent system is installed with a standard Linux Unix rc startup script This script will allow the product to be started on each platform boot or reboot It is usually located in etc init das iagent and is linked to etc rc3 d S99iagent You must choose to start the Agent system either as a system daemon at boot or from the command line Do not do both See Chapter 9 for details on the command line options It is suggested that you start Agent3 from the command line to test your confi
113. lso at this time any required connectivity installation of hardware circuits and connections should be completed provisioned and tested prior to Agent3 installation November 2004 Page 19 version 3 1 1 IAgent3 User s Guide Installation CHAPTER 6 PRODUCT INSTALLATION The actual installation of the IAgent3 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 install txt inthe IAgent3 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 Agent please complete the following steps prior to installation 1 Shutdown the current IAgent3 system 2 Copy all configuration files and any other files you have modified including license files to a new location not under opt iagent3 3 Backup all transactions pending receipts and log files to a new location You are now ready to install the latest version on top of your last installed version Please refer to the INSTALL file install txt in the IAgent3 distribution for
114. m KAJv7RfaVkGfMyowVAlrFH22VsrVfewriAD tcFmg Example 29 An example of Debug Certificate Messages Server side November 2004 Page 80 version 3 1 1 IAgent3 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 Development CN LymewareDemoCA Email security lymeware com Certificate Data Version 3 0x2 Serial Number 12 0 Signature Algorithm md5WithRSAEncryption Issuer C US ST Connecticut L Old Lyme O Lymeware Corporation OU IAgent Development CN LymewareDemoCA Email security lymeware com Validity Not Before Dec 16 02 09 50 1999 GMT Not After Dec 15 02 09 50 2000 GMT Subject C US ST Connecticut O Lymeware Corporation OU Iagent development CN TP 1 Email non lymeware com Subject Public Key Info Public Key Algorithm rsaEncryption RSA Public Key 1024 bit Modulus 1024 bit 00 2 36 5 427 41 20 8 43 72 98 28 34 8 04 99 6c 09 1a 58 ca 2b 74 3a ac 37 12 lc ed 12 5 75 9 9 16 67 64 0 41 6 1 03 32 2 22 72 9 9 47 7 7 67 07 5 88 9 2 7d 46 15 d6 39 9e db 55b 5d 81 3e 1b 9 0e 6f 2 28 49 85 89 81 86 4 86 40 5 37 0 44 7 94 74 9 49 4 3 41 61 15 29 68 6 93 37 4 0 Exponent 65537 0x10001 X509v3 extensions X509v3 Bas
115. mation 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 in 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 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 Establishi
116. n 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 November 2004 Page 92 version 3 1 1 IAgent3 User s Guide Administration Contact Lymeware Product Support Two e mail addresses are available for Agent3 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 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 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
117. nce information Date added to IAgent3 configuration Added by who This information should be saved after being added to the IAgent3 trading partner configuration file Copyright 1999 2004 Lymeware Corporation All rights reserved Permission to copy for use in IAgent3 installation is granted November 2004 Page 99 version 3 1 1 IAgent3 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 information 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 required Copyright 1999 2004 Lymeware Corporation All rights reserved Permission to copy for use in IAgent3 installation is granted November 2004 Page 100 version 3 1 1 IAgent3 User s Guide Appendixes License Request Form A specific license data file will be required to run the IAgent3 system Lymeware or you
118. ng eOptionally supports the Tibco TIB Rendezvous API for BES support eUses the popular OpenSSL cryptography toolkit Simple Integration is the key The underlying structure of the TCIF IA standard and the IAgent3 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 IAgent 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 IP Socket interface the Web Services interface and the Tibco TIB Rendezvous message bus interface Integration APIs Fik Directory Server Client IP okt Figure 3 IAgent3 Integration APIs eThe File Directory interface atomically reads and writes ASCII text files EDI messages in standard ASC X 12 formats eThe 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 IAgent3 system eThe Web Services 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 h
119. ng 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 November 2004 Page 12 version 3 1 1 IAgent3 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 network 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
120. 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 All files are written with either an edi extension for standard priority ora 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 an edior 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 PATH options The output inbound directory may be set with the D PATH outdir PATH options All 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 November 2004 Page 54 version 3 1 1 IAgent3 User s Guide Administration CHAPTER 19 SOCKET API INTEGRATION Socket Interface Mode The socket interface mode reads and writes all messages as a byte s
121. o the IAgent3 process or process group identified by the iagent pid file This last step will signal all IAgent3 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 IAgent3 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 the client s These logs are called client trans 1og 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 Type Number UNSUPPORTED BASIC EDI INTEGRITY EDI SIGNED EDI BASIC RECEIPT INTEGRITY RECEIPT SIGNED RECEIPT IA STATUS NA MW Bl WI NR Table 9 Transaction Log Message Type Numbers The SA segment of the message should be the first 105 bytes of a raw EDI or Receipt message For IA Status messages this field is popul
122. of this manual covers Certificate Signing Request CSR and Key generation and installation in detail 3 Creating the lAgent3 configuration file Chapter 9 of this manual covers IAgent3 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 IAgent3 requires the 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 November 2004 Page 21 version 3 1 1 IAgent3 User s Guide Installation PRNGD and EGD as solutions to this requirement Note It is required that one of the two entropy programs is installed configured and running prior to starting the IAgent3 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
123. opt iagent3 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 November 2004 Page 22 version 3 1 1 IAgent3 User s Guide Configuration Part 3 lAgent3 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 November 2004 Page 23 version 3 1 1 IAgent3 User s Guide Configuration CHAPTER 8 CERTIFICATE AND KEY GENERATION AND INSTALLATION Certificate and Key generation and configuration IAgent3 certificate and key generation and installation consists of six steps 1 Selecting a third party Certificate Authority CA 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
124. ority 24 2 Completing the certificate request 8 1 eee nennen eere 24 3 Creating a Certificate Signing Request file and private key 24 4 Sending the Request to your chosen eene nennen trente trente 24 5 Installing local certificates and 9 9 25 6 Installing local Certificate Authority 25 CHAPTER 9 IAGENT SYSTEM CONFIGURATION ADMINISTRATION 26 THE SYSTEM OR IAGENT CONFIGURATION 2 2 24 2 6 nnnm 26 Eduensi tette Als Abate Integration API settings and options and rU DM Ld la 26 BASIC SYSTEM WIDE CONFIGURATION OPTIONS eene eee een en n en en nene enne enr nenne nennen nnne nnne 26 PROCESS SPECIFIC CONFIGURATION 8 27 CERTIFICATE AND KEY LOCATION OPTIONS 1 27 INTEGRATION API SETTINGS AND 27 File T tevface OptioWsz us Meet ai a 27 Directory Interface ODtonhs ta e tee Dri hea terere Pee e eH DE Ter ae feat oes 28 Socket Interface tea de oe eene
125. pem CAfile opt iagent3 security CAcert pem pacing delay 220 transport listen port 127 0 0 1 8103 clientp 1 process type CLIENT PROCESS insocket 7300 FE AE AE AE AE AE AE AE aE aE Ea AE aaa aaa aaa EOF iagent conf November 2004 Page 115 version 3 1 1 IAgent3 User s Guide Trading Partner configuration file This is an example of a typical trading partner configuration file f IAgent3 example Trading Partner configuration file default section trading partners Remote IN 1 local certificates Local IN 1 trading partners aaa aa aa a AF IE aA AE AE aT EAE a AE AE aE aE aT AE AE AE a FE aE aE aE AE AE aE aE aaa aaa Remote IN 1 certificate common name TP 1 msg retry limit receipt timeout inactivity dur lifetime dur bidirectional flag max inbound connections endpoints EP IN 1 1 EP IN 1 2 EP IN 1 3 EP IN 1 4 f local certificates HEHEHE E EERE HEE EE EEE HEE HE EEE EH EEE HE EEE
126. 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 P ET RD Vues dep der 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 US US State or Province Name full name Connecticut Locality Name eg city Old 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 41 Using gen
127. permissions Socket Interface The socket interface expects the input 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 Web Services Interface The web services 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 Agent process read and write permissions set November 2004 Page 59 version 3 1 1 IAgent3 User s Guide Administration 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 t
128. pieces of AT amp T created to provide Local telephone service Often referred to as the Baby 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 November 2004 Page 123 version 3 1 1 IAgent3 User s Guide Appendixes session 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 RFC 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 X 509 November 2004 Page 124 version 3 1 1 IAgent3 User s Guide APPENDIX H REFERENCES Appendixes Standards Standards Body Standards Title and Publication Date Identification TCIF 98 006 Issue 2 ECIC Electronic Communications Interactive Agent Functional Specification TCIF 98 006 Issue 2 Decem
129. platform and environment specific update instructions If the updated version is a newer version number than currently installed 1f 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 November 2004 Page 20 version 3 1 1 IAgent3 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 IAgent3 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 Request Form The license file must be installed at opt iagent3 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
130. port SSL encryption and digest IA V2 only Enhanced Receipt Security with Non Repudiation includes SSL encryption and signed message integrity Status messages A defined TEST IA status message A defined STOP WAN IA status message A defined STOP OSS IA status message A defined PING Request IA status message V3 only A defined PING Response IA status message V3 only A custom 32 bit IA status message November 2004 Page 3 version 3 1 1 IAgent3 User s Guide Introduction 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 TCIF standards documents including the TCIF 98 006 and TCIF 98 016 These documents are available from the Alliance for Telecommunications Industry Solutions www atis org November 2004 Page4 version 3 1 1 IAgent3 User s Guide Introduction CHAPTER 2 INTRODUCTION TO THE IAGENT3 PRODUCT The IAgent3 product is Lymeware Corporation s commercial class secure messaging solution for the Telecommunications Industry The IAgent3 product is a conformal implementation of the TCIF ECIC Interactive Agent IA v2 and v3 which allows secure EDI transactions over relatively insecure networks via TCP IP and SSLv3 amp TLS Trading Partner 1 Trading Partner 2 Secure encrypted connections EDI Translator Figure 2 U
131. ptosystem 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 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
132. pwire 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 Agent 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 suggestions 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 13 Suggested Security Tools
133. q default bits 768 default keyfile privkey pem distinguished name req distinguished name attributes req attributes 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 e g city 0 organizationName Organization Name e g company O organizationName default Lymeware Corporation organizationalUnitName Organizational Unit Name organizationalUnitName default commonName Common Name e g YOUR FQDN or CN commonName max 15 emailAddress Email Address emailAddress max 40 req attributes challengePassword A challenge password challengePassword min 4 challengePassword max 20 Example 38 gen_csr Configuration File Request Section November 2004 Page 106 version 3 1 1 IAgent3 User s Guide Appendixes Creating a Certificate Signing Request The gen csr command is used to create a PKCS 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 csr v1 4 generates X 509v3 certificate signing requests CSRs and RSA key p
134. r distributor will supply this license file if the following information is supplied For requesting a valid commercial or evaluation IAgent3 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 1999 2004 Lymeware Corporation All rights reserved Permission to copy for use in IAgent3 installation is granted The license file will be delivered to the Contact E Mail Address The license file must be installed at opt iagent3 as license dat and should be owned by root November 2004 Page 101 version 3 1 1 IAgent3 User s Guide Appendixes For reporting IAgent3 product problems Customer specific information Your Name Your Company Name Your Telephone Number Your E mail Address Your IAgent3 product version Your IAgent3 platform Any software add ons to your IAgent3 system A detailed description of the problem The sequence of steps that led to the problem Actions you have taken
135. ratories PKCS 8 Private Key Information Syntax Standard version 1 5 November 1993 PKCS 9 IRSA Laboratories PKCS 9 Selected Attribute Types version 1 1 INovember 1993 PKCS 10 IRSA Laboratories PKCS 10 Certification Request Syntax Standard version 1 0 November 1993 Table 17 National International Internet and Industry Standards used by this product November 2004 Page 125 version 3 1 1 IAgent3 User s Guide Appendixes 12 5 ANSI ANSI X 12 5 1977 Interchange Control Structure November 24 1997 X 12 6 ANSI ANSI X 12 6 1977 Application Control Structures November 24 1997 12 22 ANSI ANSI X 12 22 1977 Segment Directory January 21 1998 12 3 ANSI ANSI X 12 3 1977 Data Element Dictionary January 21 1998 Table 18 National International Internet and Industry Standards used by this product concluded TIBCO Software Inc TIB Rendezvous Installation Guide Release 5 0 September 1998 TIBCO Software Inc TIB Rendezvous Concepts Release 5 0 September 1998 TIBCO Software Inc TIB Rendezvous Administrator s Guide Release 5 0 September 1998 TIBCO Software Inc TIB Rendezvous C Programmer s Guide Release 5 0 September 1998 Table 19 Commercial or third party documentation used by this product or manual November 2004 Page 126 version 3 1 1 IAgent3 User s Guide INDEX A Alliance for Telecommunications In
136. receipts and duplicate BES messages Ignore Duplicate Receipts Send IA Status messages to Remote trading Partners on error Send Status Copyright 1999 2004 Lymeware Corporation All rights reserved Permission to copy for use in IAgent3 installation is granted November 2004 Page 98 version 3 1 1 IAgent3 User s Guide Appendixes This worksheet is to be used for each local and remote trading partner to be supported by the system Fill this out before generating modifying the trading partner configuration file Valid field values will be found in Chapter 10 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 ILEC 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 receipt type Trading Partner s receiving IA receipt type Trading Partner s IA Server status Maintena
137. ribes how to configure the IAgent3 system with configuration files November 2004 xiii version 3 1 1 IAgent3 User s Guide Preface Chapter 10 Describes how to add a Trading Partner to the IAgent3 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 Integration Chapter 19 Socket Integration Chapter 20 Web Service Message Integration Chapter 21 Optional 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 November 2004 xiv version 3 1 1 IAgent3 User s Guide Manual Revision History Version 3 1 1 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 November 2004 August 2003 January 2003 April 2002 November 2001 April 2001 September 2000 March 2000 January 2000 Version 0 2 Quick Readme version November
138. rsion 3 1 1 IAgent3 User s Guide Administration Examples ofall ofthe debug level logging display screens follow below 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 035740 iagent 5348 Generating temp 512 bit RSA key 20000417 035852 iagent 5348 i 3 partner i cname 1 strp TP 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 return
139. rsion 3 1 1 IAgent3 User s Guide Configuration standard ip port The trading partner s standard IA server IP port address on same IP address as above hipri ip port The trading partner s high priority IA server IP port address on same IP address as above session timeout Connection session cache timeout in seconds If 0 then no resumable sessions supported for this trading partner 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 EDI Integrity with digest EDI message SIGNED EDI Signed with digital signature EDI message ia message to tp The 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 ia receipt from tp The 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 ia receipt to tp The IA Receipt Type to send to this trading partner May be any of the following NO RECEIPT No receipt requir
140. rypt 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 November 2004 Page 10 version 3 1 1 IAgent3 User s Guide Introduction Message Digests Although Alice may encrypt her message to make it private there is 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 one 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
141. s All 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 November 2004 Page 91 version 3 1 1 IAgent3 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 IAgent3 product Scope of Support Services Lymeware Product Support can provide assistance and information for the following Installing the IAgent3 product IAgent3 product questions Software revisions and upgrades Implementing a specific feature How to use the IAgent3 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 Corporatio
142. s the first time they are used within a chapter Example The Common Name is Curier New This font is used for commands to be Font typed by the user or for system commandis or utilities Example Type iagent m F I dir Angle Angle brackets indicate variable brackets Information such as input file names created by the user Example inputfilename gt edi Table 1 Typographic conventions November 2004 version 3 1 1 IAgent3 User s Guide Preface Symbols used within syntax statements This table describes symbols used within program syntax statements used within this document Convention Use gt Substitute a 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 a Braces indicate a required part of a statement Do not enter the 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
143. same output socket Sample code to support the Socket Interface is supplied in Chapter 23 November 2004 Page 56 version 3 1 1 IAgent3 User s Guide Administration CHAPTER 21 TIBCO MESSAGE API 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 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 Agent 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
144. sed 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 RC4 with 40 bit keys RC4 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 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 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 IAgent but is very popular in Europe and is patented by MediaCrypt AG RC2 is a proprietary algorithm from RSA Security Digest Function The cho
145. ser 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 iagent3 security 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 iagent3 security 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 iagent3 security 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 November 2004 Page 25 version 3 1 1 IAgent3 User s Guide Configuration CHAPTER 9 IAGENT SYSTEM CONFIGURATION ADMINISTRATION The System or lAgent configuration file The system configuration file iagent 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 configurat
146. sg Get ret length n unless ret RVMSG OK IA message priority ret rvmsg_Get session msg priority msgT ype msgSize SIApriority 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 my callback 0 die rv_ListenSubject n unless ret RV_OK Enter the event loop rv MainLoop session Example 21 Tibco API Reader Example November 2004 Page 65 version 3 1 1 IAgent3 User s Guide Administration Tibco API Writer Example use Rv subjectname iagent tibco client message versionl 1 lAmessage spaces 1024 for test only SIAlength strlen IAmessage SIApriority 1 rvMessage spaces SIAlength 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 rvmsg Append Add IA message length as RVMSG_ INT ret rvmsg Append session rvMessage strlen rvMessage length RVMSG INT 2 SIAlength die rvmsg Appen
147. 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 configured 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 the SSL specification for the full range of possibilities Once an SSL session has been established it may be reused thus avoiding the performance pen
148. sing an IAgent3 system for IA trading partner communications The lAgent3 product supports Secured data transactions over unsecured networks including the Internet using Secure Socket Layer SSLv3 protocol a de facto Internet standard developed by Netscape and the IETF Transaction Layer Security TLS 1 0 Sender and Receiver Trading Partner authentication identification and validation via Industry standard X 509 certificates issued by a valid third party Certificate Authority Digital non repudiation by both the sending and receiving Trading Partners Supports current and emerging Public Key Infrastructure security standards including RSA PKCS and IETF TLS and PKIX standards support Supports transaction receipts with multiple levels of validation customized by trading partner Supports multiple levels of message validation on each transaction customized by trading partner lAgent3 product benefits eClient Server Architecture with Public Standards including TCIF IETF and RSA support eNear Real time High Volume Performance up to 300 transactions a minute eMulti threaded and Scaleable Design eCustomer centric Security and Auditing eElimination of EDI Value Added Network VAN fees November 2004 Page 5 version 3 1 1 IAgent3 User s Guide Introduction eSimple Operational Support System OSS Integration via Multiple Application Program Interfaces Integration APIs eWeb based Monitori
149. sloppyinactive off cachesize ENTRIES 128 outdir PATH out dir file FILENAME ignoredupreceipts loopbackdelay SECOND oneshot off receiptmode MODE test file ff S 0 nternal outsocket SOCKET ADDR ESS PORT 127 0 0 1 outtibco MESSAGE version off savereceipts of packetmode off indir PATH in config config fi debug debuglevel entropy FILENAME _NAM dir le D E iagent tibco server message versionl 1 FILENAME iagent conf EPTH 0 tmp entropy insocket SOCKETPORT 6500 hipriport interface ll intibco MESSAGE NAME PORT 6998 TYPE dir lagent tibco client message versionl 1 key key file F mode MODE F dirpolldelay stdport port vhack off raw off TPconfig tpartne usage help of verbose off sendstatus off cert cert file CAfile FILENAME ILEN r AME own_key pem SECONDS 5 PORT 6999 FILENAME tpartner conf FIL ENAME own cert pem ca cert pem CFG DEFAULT CHAR mode 5 November 2004 Table 8 Default Iagent3 configuration values Page 34 version 3 1 1 IAgent3 User s Guide Configuration CHAPTER 10 TRADING PA
150. t Testing eerte one LIU aea 59 IAgent3 Processing as a Series of Pipes outbound sse eene 75 IAgent3 Processing as a Series of Pipes inbound sse 75 November 2004 xi version 3 1 1 IAgent3 User s Guide Preface List of Tables Tablet Fypographic Conyentions 4 tee RR ee EU T PURO de CR E RG He SEE 17 Table 2 Symbols used within syntax statements 18 Table 3 TAgent3 Ha dshake Sequence cese ie ee e e E E eee eet 8 Table 4 IAgent3 Command Line Arguments enne ener enne entren rre 30 Table 5 IAgent3 Command Line Arguments continued sse eene ener nnns 31 Table 6 Trading Partner Configuration Fields eee 36 Table 7 Trading Partner Configuration Fields continued sess 37 Table 8 BES Locations supported by Interface sse eee nennen enne 47 Table 9 Transaction Log Message Type Numbers sess nnne trennen enne 72 Tabl T09 gent3 Error Numbers rod eet et m o t PR a RT ee e 73 Table 11 IAgent3 Error Numbers continued esses enne enne 74 Tabl 2 Debug Level Masks nete tt emma eh RR E ort 76 Table 13 Suggested Security t We red KR osea ta ti
151. t message line 11 MSG This is a test message line 12 MSG This is a test message line 13 CTT 0 SE 23 000000001 GE 1 000001 IEA 1 000000001 Example 32 An example of Debug Parsed ASN1 Messages November 2004 Page 82 version 3 1 1 IAgent3 User s Guide Administration 1211 d 2 hl 3 l 208 cons SET 1214 d 3 hl 3 l 205 cons SEQUENCE 1217 d 4 hl 2 l 1 prim INTEGER 00 1220 d 4 hl 2 1 51 cons SEQUENCE 1222 d 5 hl 2 l 13 cons SEQUENCE 1224 d 6 hl 2 1 11 cons SET 1226 d 7 hl 2 l 9 cons SEQUENCE 1228 d 8 hl 2 l 3 prim OBJECT countryName 1233 d 8 hl 2 1 2 prim PRINTABLESTRING US 1237 d 5 hl 2 l 31 cons SEQUENCE 1239 d 6 hl 2 l 29 cons SET 1241 d 7 hl 2 l 27 cons SEQUENCE 1243 d 8 hl 2 l 3 prim OBJECT organizationName 1248 d 8 hl 2 1 20 prim PRINTABLESTRING Lymeware Corporation 1270 d 5 hl 2 l 1 prim INTEGER 0C 1273 d 4 hl 2 1 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 33 An example of Debug Parsed ASN1 Messages continued 20000417 035852 iagent 5348 Peer RSA Public Key Modulus 1024 bit 00 2 36 05 7 41 20 8 43 72 98 28 34 8 04 299 6 09 1a 58 2ca 25b 74 3a ac 37 12 1c ed 12 15c 75 a9 p09 215267 64 0 bd 41 6f
152. ta 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 ssl3 November 2004 Page 15 version 3 1 1 IAgent3 User s Guide Installation Part 2 lAgent3 Installation Part 2 of this manual contains a step by step description of IAgent3 product installation including pre installation and post installation tasks November 2004 Page 16 version 3 1 1 IAgent3 User s Guide Installation CHAPTER 4 INSTALLATION OVERVIEW The installation and configuration of the Agent3 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 IAgent3 product support utilities and associated products Configure Agent3
153. the IAgent3 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 IAgent3 startup options The following table lists all the available Agent3 command line arguments Each argument may also appear in the system configuration file iagent con f 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 E failover reconnect delay Failover BES reconnect check delay in seceonds F FILENAME file FILENAME Input or output file name for File interface only G bes connect attempts Maximum BES server connect attempts before failure H bes connect delay Delay between BES server connect attempts in milliseconds I ignoredupreceipts Flag to allow duplicate receipts without triggering errors for testing purposes only J low failover threshold Minimum number of failover records for failover processing to
154. the data exchange was to support Local Service Ordering but any EDI transaction or type of ordering is supported The intent of the IA 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 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 AXN network etc have no built in delays and will support near real time transaction processing Trading Partner 1 Trading Partner 2 y Nx fp Connection Network Secure encrypted connections Figure 1 An Interactive Agent IA system for EDI communications The IA design provides Secured data transactions over unsecured networks including the Internet using Secure Socket Layer SSLv3 protocol a de facto Internet standard developed by Netscape and the IETF Transaction Layer Security TLS 1 0 Sender and Receiver Trading Partner authentication identification and validation via Industry standard X 509 certificates issued by a valid third party Cert
155. 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 November 2004 18 version 3 1 1 IAgent3 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 lAgent3 Product detailing product features and system requirements Lastly this section includes an introduction to SSL November 2004 Page 1 version 3 1 1 IAgent3 User s Guide Introduction CHAPTER 1 INTRODUCTION TO 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 1 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
156. 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 November 2004 Page 93 version 3 1 1 IAgent3 User s Guide Appendixes Appendixes The final part of this manual contains appendixes with additional information on IAgent3 administration including worksheets and other maintenance issues November 2004 Page 94 version 3 1 1 IAgent3 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 IAgent3 system The following table describes each worksheet IAgent3 Pre Installation Worksheet This worksheet is used to identify all the information and resources required for installing the IAgent3 product IAgent3 Connectivity Worksheet This worksheet is used to capture all networking information required to complete a network diagram for the local IAgent3 system and its connection to remote trading partners IAgent3 Configuration Worksheet This worksheet is used to identify all required and optional configuration settings and to assist the user in
157. tificate Authority CA file in PEM format Integration API settings and options These options describe the setting for the Integration API Interface used and set above All 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 November 2004 Page 27 version 3 1 1 IAgent3 User s Guide Configuration Directory Interface Options dirpolldelay SECONDS Client directory poll delay in seconds for Directory interface only indir PATH Input directory name for Directory interface only outdir PATH Output directory name for Directory 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 Agent system and are usually used only during testing sloppyallow 0 1 Flag to allow receipt of any type of messages from active trading partners for testing purposes only sloppyinactive 0 1
158. 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 IAgent3 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 Agent 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 IAgent3 product Subsequent chapters cover specific tasks in detail November 2004 Page 17 version 3 1 1 IAgent3 User s Guide Installation CHAPTER 5 PRE INSTALLATION TASKS Pre Installation Task Instructions IAgent3 pre installation consists of five tasks 1 Completing the pre install worksheet 2 Acquiring root access on the target machine 3 Acquiring the correct 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
159. top for WAN or OSS stop messages ping for PING response messages or status for custom status messages A custom status message file will only contain a single bit string up to 32 bits All failed transactions are saved in very ugly temporary file names to the failed message directory opt iagent3 failed messages If possible they are saved in their ASNI DER binary format so don t try to cat them They may be inspected with the included asnldump utility see Appendix F November 2004 Page 70 version 3 1 1 IAgent3 User s Guide Administration All invalid messages and receipts will be saved in very ugly temporary file names to the invalid message directory opt iagent3 invalid messages If possible they are also saved in their ASN1 DER binary format They may also be inspected with the included 1 utility All inbound receipts be saved in Receipt Input Message Format to temporary file names in the receipt log directory opt iagent3 receipts for manual examination and archiving if the savereceipts flag is set November 2004 Page 71 version 3 1 1 IAgent3 User s Guide Administration CHAPTER 26 IAGENT3 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 t
160. tream 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 All 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 10 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 deliver the message If the connect fails then the message will b
161. uthentication 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 Ifthis 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 other private messages The task of privately choosing a key before communicating however can be problematic Public key cryptography PKT 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 dec
162. ware 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 2004 Lymeware Corporation All rights reserved Permission to copy for use in IAgent3 installation is granted November 2004 Page 96 version 3 1 1 IAgent3 User s Guide For IAgent3 Machine information collection to be used during connectivity testing Appendixes Machine specific information Hostname FQDN IP address Standard IA port High Priority IA port Net mask Gateway IP address Firewall Machine information IP 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 IAgent3 machine External Standard IA port External High Priority IA port Router information IP Address Subnet Limit Port filtering supported Port filtering for IA ports disabled
163. 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 Name 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 15 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 stan
164. y 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 are used to monitor this handshake A protocol two computers or processes use to initiate a communication session HTML The HyperText Markup Language The language used to build and describe web pages ILEC Incumbent Local Exchange Carrier November 2004 Page 122 version 3 1 1 IAgent3 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 cry
165. ystem 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 November 2004 Page 87 version 3 1 1 IAgent3 User s Guide Administration CANNOT CREATE CONNECTION Cannot create a new connection in the internal connection table CANNOT FIND CONNECTION Cannot find a connection in the internal connection table CANNOT FIND LOCAL CERT ENTRY Cannot find a required local certificate for this message Skipping message RECV INTERNAL DATA SEND INTERNAL

Adobe PDF - Lymeware Corporation

Contents

Download Pdf Manuals

Related Search

Related Contents