XCOM File Transfer. Specification

Transcription

1 XCOM File Transfer Specification Version Jul 2015

2 Date Version Description 14-Dec Original Version 5-Jan Updated 29-Mar Corrected key generation 14-Aug Updated references to newer version of gnupg v Jun Corrected Key ID reference 03-Jul ilink administration documentation added Page 2

3 Table of Contents 1 Introduction Security Initial Key Exchange Pushing a file to Westpac Westpac pushing a file to the Customer Polling a file from Westpac File & Directory Names Network Connectivity Transport Mechanism Addresses Test Production Quick Start ilink connectivity setup ilink URLs Setup connectivity form and documentation location Connectivity form for XCOM customers Getting the WIBS server s details Software Installation Software Required Gnupg Installation Gnupg RSA public / private key generation Step 1 - Create the Key Pair Step 2 Export you Public Key Step 3 Import Westpac s Public Key To Decrypt and incoming file using Gnupg To Encrypt, Sign and ASCII Armour a file: Installing and Configuring Unicenter CA-XCOM Data Transport (version R11) Artefacts System requirements Page 3

4 4.3.3 Install Notes Steps Verification CA-XCOM R11 Application configuration Security Permissions Testing the XCOM Connection To test the connection via the Internet or leased line To Send a file via XCOM To Retrieve a file via XCOM XCom Receiving Command File Error Handling FAQ Common XCom Error Messages What Platforms is XCOM available for? XCOM User Account / Windows Domains GPG2 Questions Glossary Page 4

5 1 Introduction This document defines Westpac s WIBS XCOM file transfer protocol. The XCOM file transfer protocol allows partners to transfer files securely and reliably over the internet. PGP is used to provide encryption of data between partners, and digital signing assures the identity of each partner. The intended audience of this document is: Server administrators who wish to use the provided command line scripts, and Software developers who wish to implement this messaging protocol in their software. 1.1 Security All files transferred must be encrypted and digitally signed between P&P and the customer site. This serves two purposes; the first is to ensure that the data cannot be viewed by unauthorised sources. The second is to provide non-repudiation. Through the use of public / private keys, data can be digitally signed, by signing the file both Westpac and the customer can be assured that the data originated from a known source and it has not been tampered with Initial Key Exchange To set up the XCOM transfer a customer will: Provide Westpac with a PGP public key used to verify the digital signature of the data file that is transferred between the customer and Westpac. Banking policy mandates that any file written to a hard drive in an untrusted zone (a server connected to an external network) must be PGP encrypted and digitally signed. Provide a username and password for Westpac to log onto the customer s XCOM server if Westpac is required to push files back to the customer. In return Westpac will: Provide a username and password for the customer to log onto Westpac s XCOM server. Provide the customer with Westpac s PGP public key. This would be used by the customer to encrypt a file that is sent to Westpac (this customer signs the file with their private key). Agree with the customer on the file naming convention and their directory paths. 1.2 Pushing a file to Westpac To push a file to Westpac the sending site carries out the following steps: 1. Encrypts the data using Westpac s public key and signs the encrypted data with its private key. To ensure that data does not get corrupted, when messages are encrypted they must be ASCII armoured. Page 5

6 2. The file is then given to XCOM client for transmission. XCOM connects to the remote computer using the user/password that Westpac provided. 3. Once it is connected the file is transferred to the Westpac XCOM server into the agreed directory. 4. Westpac detects the arrival of the file. The digital signature is checked against the customers previously supplied PGP public key. If this matches then the file is decrypted using Westpac s private PGP key. Once the security aspects of the file have been verified, it is then processed. 5. Once the file has been processed, it will be deleted from the incoming directory on Westpac s XCOM server Westpac pushing a file to the Customer For Westpac to push a file to the customer the following steps are carried out: 7. Westpac encrypts the data using customer s public key and signs the encrypted data with its private key. To ensure that data does not get corrupted, when messages are encrypted they must be ASCII armoured. 8. The file is then given to XCOM client for transmission. Westpac s XCOM server connects to the remote computer using the user/password that the customer provided. 9. Once it is connected the file is transferred to the customer s XCOM server into the agreed directory. 10. The customer detects the arrival of the file. The digital signature is checked against Westpac s previously supplied PGP public key. If this matches then the file is decrypted using the customer s private PGP key. Once the security aspects of the file have been verified, it is then processed Polling a file from Westpac To poll a file from Westpac the polling site carries out the following steps: 12. Westpac encrypts the file using the customer s public key ascii armours it and signs it with Westpac s private key and deposits it in a customer directory ready to be picked up. 13. The customer s XCOM client connects to the remote computer using the user/password that Westpac provided. 14. Once the customer connects the customer preforms a Retrieve to fetch the file based on the agreed upon file naming specification. 15. Once the customer has fetched the file back to their site they should check the digital signature is checked against Westpac s previously supplied PGP public key. If this matches then the file is decrypted using the customer s private PGP key. Once the security aspects of the file have been verified, it is then processed. 16. Westpac will keep the file on its XCOM server for 30 days to allow the customer plenty of time to retrieve the file in the event of communications issue. After 30 days Westpac will automatically delete the file. After this time the file can be regenerated by contacting Westpac customer support. Page 6

7 1.5 File & Directory Names File names can be of any format as long as they do contain standard ASCII characters that are valid for file names. It is not advised that filenames contain spaces, as this makes XCom command line calls more difficult to build. The destination directories of both Westpac and Customer sites must be communicated to each other before a transfer can take place. 1.6 Network Connectivity Transport Mechanism XCOM will function on a variety of platforms and IP based networks. This includes the Internet, Frame Relay and ISDN. Note before you will be able to access Westpac s XCOM server you must provide the IP address of your server running your XCOM client. Westpac will then modify its firewall to allow your server access to Westpac s XCOM server on port The customer may also need to engage their own network support staff to allow their XCOM client to connect on port Addresses Test To transmit to Westpac via the Internet you must configure XCOM to send to ssiw.support.qvalent.com ( ) on port To transmit to Westpac via a dedicated leased line (Frame relay, ISDN, dial or Ethernet) you must configure XCOM to send to or port Production To transmit to Westpac via the Internet you must configure XCOM to send to ssiw.qvalent.com ( ) on port To transmit to Westpac via a dedicated leased line (Frame relay, ISDN, dial or Ethernet) you must configure XCOM to send to or port Page 7

8 2 Quick Start Customer task Westpac task 1. Qvalent implementation consultant creates an ilink test account for the customer s technical contact. 2. Customer contact completes ilink connectivity form in test ilink. 3. Qvalent implementation consultant arranges configuration of the test WIBS XCOM server. 4. Customer configures 3 rd party software. 5. Customer codes XCOM scripts. 6. Customer undertakes testing in the test environment. 7. Once customer is satisfied that testing is complete a sign off is required to progress into production. 8. Qvalent implementation consultant creates an ilink production account for the customer s technical contact. 9. Customer contact completes ilink connectivity form in production ilink. 10. Qvalent implementation consultant arranges configuration of the production WIBS XCOM server. 11. Customer tests the XCOM connection in the live environment. 12. Once this testing is successful customers can perform low value live testing of the other Westpac products that are being implemented. Page 8

9 3 ilink connectivity setup In the early stages of your Westpac project you will be asked to provide the contact details of the IT person who will be responsible for setting up your XOM connection. Once these details are received you will be provided with an ilink login to enter your IP addresses and public keys. The ilink connectivity process has the following steps 1. The Qvalent implementation consultant will provide the user s technical contact with a login to the ilink test instance. 2. Fill in the setup connectivity form and submit 3. The WIBS connectivity team will receive a notification when the form is completed and will configure the WIBS XCOM server with the new details. Please allow up to 3 working days for this configuration. 4. Once this configuration is complete a notification will be sent and the user will need to configure the connection details provided on the updated connectivity page. 5. User to send in a test file to test the XCOM connection and PGP encryption. Once this is confirmed the use can also undertake any user acceptance testing relative to their implementation. 6. Once the Qvalent implementation consultant has received confirmation that all relevant testing has been completed steps 1 5 will need to be repeated in the production environment. 3.1 ilink URLs Test Production Setup connectivity form and documentation location The ilink setup connectivity form is under administration -> Connectivity Page 9

10 3.2.1 Connectivity form for XCOM customers PGP key Before files are sent via XCOM they are encrypted, the user s PGP public key is required to decrypt these files before processing them in the WIBS messaging server. Your XCOM server details The fields in this section are the details that WIBS uses when connecting to the user s XCOM server to place files. The login provided for this connection will need to have privileges to write to the directory provided. IP addresses The WIBS solution has a white list of IP addresses accepted for each user. Users need to provide the IP address or addresses that their incoming requests will be coming from, this is the external IP address taking into account any proxy servers or other externally facing network infrastructure. This can be found by logging on to ilink on your XCOM server and taking the browser address shown in the IP addresses section of the connectivity form. Page 10

11 3.2.2 Getting the WIBS server s details Once the WIBS server configuration is complete the user will receive an notifying them that they can begin testing. The user will then be able to see the WIBS server details on the Setup connectivity page. Westpac s keys PGP key this is the public key that you will need to use to decrypt the files you receive from WIBS. Your key - You can use these fields during testing to confirm which key you have loaded into ilink Westpac s XCOM server details This section contains the XCOM username and password to enter to connect to the WIBS XCOM server and the directory for placing customer -> WIBS files. Your XCOM server details This section contains the XCOM username and password for WIBS to connect to your server and the directory for placing WIBS -> customer files. Page 11

12 4 Software Installation 4.1 Software Required CA-XCOM PGP Unicenter Data Transport (version R11). This is a commercial file transfer product created by Computer Associates (CA). Westpac will provide a copy to the customer. GNUPG (version 2.1.x). GnuPG ( This is a public domain PGP server that may be used free of charge. Obtaining of this product is the responsibility of the customer; however Westpac is able to provide technical assistance to support this. 4.2 Gnupg Installation 1. Start the installation by clicking on the gnupg exe (gnupg-w32cli-1.4.x.exe). The following screen will be displayed. 2. Click on the Next button Page 12

13 Page 13

14 3. Click on the Next button 4. Accept the default selection and click on Next Page 14

15 Page 15

16 5. Either accept the default installation directory or enter in your preferred path. 6. Accept the default start menu folder name and click on Install. Page 16

17 Page 17

18 7. The installation complete dialog will be displayed. 8. Click on Finish to complete the installation. Read all documentation associated with Gnupg. Page 18

19 Page 19

20 4.2.1 Gnupg RSA public / private key generation Once Gnupg has been installed you need to generate a public key to give to partners you will exchange files with and a private key. These two keys will be kept in your private and public key rings. Your private key ring will only contain only your private key, while your public key ring will contain your own public key and the public keys of any other business partners (such as Westpac) who will provide you with their public key Step 1 - Create the Key Pair The first step is to create the key rings and your own public / private key pair. Log onto the server that you installed gnupg and change to the gnupg installation (d:\program files\gnu\gnupg) directory. Enter the following command: C:\Program Files\GNU\GnuPG\gpg2 --gen-key gpg2 (GnuPG) 2.1.0; Copyright (C) 2009 Free Software Foundation, Inc. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Please select what kind of key you want: (1) RSA and RSA (default) (2) DSA and Elgamal (3) DSA (sign only) (4) RSA (sign only) Your selection? 1 RSA keys may be between 1024 and 4096 bits long. What keysize do you want? (2048) Requested keysize is 2048 bits Please specify how long the key should be valid. 0 = key does not expire <n> = key expires in n days <n>w = key expires in n weeks <n>m = key expires in n months <n>y = key expires in n years Key is valid for? (0) Key does not expire at all Is this correct? (y/n) y You need a user ID to identify your key; the software constructs the user ID from the Real Name, Comment and Address in this form: "Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>" Real name: Stephen Macmillan Page 20

21 address: Comment: Acme You selected this USER-ID: "Stephen Macmillan (Acme) Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O You need a Passphrase to protect your secret key. We need to generate a lot of random bytes. It is a good idea to perform some other action (type on the keyboard, move the mouse, utilize the disks) during the prime generation; this gives the random number generator a better chance to gain enough entropy We need to generate a lot of random bytes. It is a good idea to perform some other action (type on the keyboard, move the mouse, utilize the disks) during the prime generation; this gives the random number generator a better chance to gain enough entropy gpg2: key 682B25F2 marked as ultimately trusted public and secret key created and signed. gpg2: checking the trustdb gpg2: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model gpg2: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u pub 2048R/A28F9F1C Key fingerprint = 3230 E29F BA96 23D3 DA57 1D9E 204A B8F7 A28F 9F1C uid Stephen Macmillan (Acme) <smacmillan@acme.com> sub 2048R/E5CA C:\Program Files\GNU\GnuPG> Note that the pubring and secring are stored in the following locations. GPG2 knows these locations via the registry. gpg2: keyring `C:/Documents and Settings/StephenM/Application Data/gnupg\secring. gpg2' created gpg2: keyring `C:/Documents and Settings/StephenM/Application Data/gnupg\pubring. gpg2' created Page 21

22 To specify a different location of the key rings use the --homedir parameter. Please make sure these files will not be removed/deleted Step 2 Export you Public Key Once the public and private keys are generated you need to export your public key and provide it to Westpac (or any other business partner you will be exchanging PGP encrypted data with) 1 From the command prompt, navigate to the GnuPG folder (if not already in this directory from the last section) 2 From the command line, issue the following command: > gpg2 --output <filename_to_write_exported_key_to> -a --export <id_of_key_to_export> [Enter] 3 To check to see if a PGP public key was generated, you are able to perform from the command line the following command: > type <filename_specified_in_step_2> [Enter] Output Check The output from Steps 1 and 3 should be similar to: D:\Program Files\GNU\GnuPG>gpg2 --output acme_pgp_pub_key.txt -a --export smac millan@acme.com D:\Program Files\GNU\GnuPG>type acme_pgp_pub_key.txt -----BEGIN PGP PUBLIC KEY BLOCK----- Version: GnuPG v2.1.0 (MingW32) mqgibenf9oyrbacsnpgvd5opjwik0qzktqxb/rmz4fxvk/t9tjct1qpkrf9f9it0 8nBRBydViILOnp5LjwcaUyE11I6tJtx4ziJEj6OXw2zEJZtemLHlEwnPz96Pv3yp ICiAkJsjmD8W5anoQN73E7bPV6XomNq/qSoX7iJnothCGZwlMqTxxWmbywCgjjBU okopcad9dc2jw/x+rofe5hud/j9lf5vivehwt+mv2is97j0hftduusdvw/nap0gp vg1t8f9hqthd4ws73z2gp6sat5z9x30ytlkdkpkuuev5qkgxnazv2tcq3zy5wql0 50BWXY9aXqupta5F0bhR50Py3AJd86ENOfgAti69BC2wYcxLyGeQYujYyy39Pz6q ezdka/9nswmvorndzo1tpz7gl3wpzzrayxhesi66vt38l+okvawwww/nfl7a7+n8 jjf/kb5amrqux4k0nr35wzbyxzs8j9q/j6etxpu2omjoz9a2dq3phuasa4hgjrlc XljzwKdKQJKDUOa8TNpGrTepVYt39WJZoTcGv3yV4/4k+4mYcrQ0U3RlcGhlbiBN Page 22

23 YWNtaWxsYW4gKFF2YWxlbnQpIDxzbWFjbWlsbGFuQHF2YWxlbnQuY29tPohgBBMR AgAgBQJDRfaGAhsDBgsJCAcDAgQVAggDBBYCAwECHgECF4AACgkQMRzcKAb3MX4e GwCghCnjfAxV4gN2Ou4Khv1T0OWzzhEAoIIP9WR/ruH9IlNZ03Z4j5EG8t7guQEN BENF9ocQBAChnSqMG3urBUDxdVT3o2vxFI6s3lj0VBtPPavx3iAWIJksF+xtfvSb s478+v5frryehzpoiztpoobf5+ndtfrmf1gi4ujbaetqkbrrjvfy3pz4qas3d9yp qa2egou8punbyixngfln2rbha//aklgjwyneeqniooto5bdv6tjhhwadbqp8dhup QHkbAQYgM4rJP6nOEk9tBbhEiCJTKcVHjb+FuTBc4/zkcUqDh7pE8AKSB2rNH2Zm KIiBkWoPTcCch6cYE15Rsb4qo5FDamYo2nhmTW/uNANulDUbl4jOM6TzyAVtG1V4 3nVRcCx2z4VlLPN36hu/j7VKCbsMQyVXYyIiNmiISQQYEQIACQUCQ0X2hwIbDAAK CRAxHNwoBvcxfuG3AJ4hGj/ry4Wy9TXCsXPkaTREcijh2ACfXoCWU36YM+S9yJqx X4neR119XaM= =6k END PGP PUBLIC KEY BLOCK----- D:\Program Files\GNU\GnuPG> this file to Qvalent (or any other business partner). When they import your public key they should contact you to verify the fingerprint (to be assured that it came from you). To check the fingerprint of your public key issue the command > gpg2 -fingerprint The output should be similar to: Output Check The output from the fingerprint check command should be similar to the following: C:\Program Files\GNU\GnuPG>gpg2 --fingerprint pub 2048R/A28F9F1C Key fingerprint = 3230 E29F BA96 23D3 DA57 1D9E 204A B8F7 A28F 9F1C uid Stephen Macmillan (Acme) <smacmillan@acme.com> sub 2048R/E5CA C:\Program Files\GNU\GnuPG> From the above the fingerprint for this key is:3230 E29F BA96 23D3 DA57 1D9E 204A B8F7 A28F 9F1C Page 23

24 Step 3 Import Westpac s Public Key Westpac will provide you with their public key to import into your public key ring. This is a two-step process. You firstly import the key then you digitally sign it to say you trust the key. 1 To import the Qvalent public key into the keyring, type the command... gpg2 --import <filename_of_file_containing_qvalent_public_key> [Enter] 2 Verify the key was added to the keystore correctly by listing the public keys in the public keyring gpg2 --list-keys [Enter] Output Check The output from the above two steps should be similar to: D:\Program Files\GNU\GnuPG>gpg2 --import 17155x01_qvalent_pub_key.asc gpg2: key C2E36CC8: public key "17155x01" imported gpg2: Total number processed: 1 gpg2: imported: 1 C:\Program Files\GNU\GnuPG>gpg2 --list-keys C:/Documents and Settings/user/Application Data/gnupg\pubring.gpg pub 2048R/A28F9F1C uid Stephen Macmillan (Acme) <smacmillan@acme.com> sub 2048R/E5CA pub 1024D/C2E36CC uid 17155x01 sub 2048g/2E52ED D:\Program Files\GNU\GnuPG> Note: Page 24

25 In the Production environment, the Qvalent Production Public Key is 17155x01 3 The Qvalent public key needs to be validated (assume the imported key id was imported_key ) gpg2 --edit-key imported_key [Enter] You should receive some text on screen and then a prompt which looks like this Command> 4 At the Command> prompt within gpg2, please type the following in bold Command> sign [Enter] 5 You should verify at this step that the Qvalent key is valid and that they key you are signing with is the key generated in the previous step If you are confident of this. Enter Y to sign the key 6 Enter the passphrase of the keys generated in Part 1 Gpg2 will then take you back to the Command> prompt once completed 7 At the Command> prompt press q to quit 8 When asked to confirm the changes, press Y Output Check The output from Steps 3 to 8 should be similar to the below output: C:\Program Files\GNU\GnuPG>gpg2 --edit-key test@qvalent.com gpg2 (GnuPG) 2.1.0; Copyright (C) 2009 Free Software Foundation, Inc. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. pub 1024D/AD8A9D42 created: expires: never trust: unknown validity: unknown sub 1024g/26787C6E created: expires: never [ unknown] (1). test <test@qvalent.com> usage: SCA usage: E Page 25

26 Command> sign pub 1024D/AD8A9D42 created: expires: never usage: SCA trust: unknown validity: unknown Primary key fingerprint: D732 F115 31BE 2DE1 40C9 185F 07F8 8DFE AD8A 9D42 test Are you sure that you want to sign this key with your key "Stephen Macmillan (Acme) (A28F9F1C) Really sign? (y/n) y You need a passphrase to unlock the secret key for user: "Stephen Macmillan (Acme) <smacmillan@acme.com>" 2048-bit RSA key, ID A28F9F1C, created Command> q Save changes? (y/n) y C:\Program Files\GNU\GnuPG> To Decrypt and incoming file using Gnupg d. To decrypt an incoming file: > gpg2 --output <filename_to_write_plaintext> --decrypt <filename_of_encrypted_data> - Enter password for private key ( OR if using a batch-type environment ) >gpg2 --yes --output [filename_to_write_plaintext] --batch --passphrase-fd 0 --homedir [path_of_keyrings] -- decrypt [filename_of_encrypted_data] <[filename_of_file_containing_password] An example of a batch file to do this would consist of: gpg2 --y --output test_dec.txt --batch --passphrase-fd 0 --decrypt example.txt.asc <password.txt Page 26

27 note: that password.txt contains you PGP private key password and is piped into the gpg2 command. The output when this batch file is executed would be: D:\Program Files\GNU\GnuPG>dec D:\Program Files\GNU\GnuPG>gpg2 --y --output test_dec.txt --batch -- passphrase-fd 0 --decrypt test.asc <password.txt gpg2: encrypted with 2048-bit ELG-E key, ID 2E52ED13, created "17155x01" gpg2: encrypted with 2048-bit ELG-E key, ID C45CC395, created "Stephen Macmillan (Acme) <smacmillan@acme.com>" gpg2: Signature made 10/07/05 15:49:30 using DSA key ID C2E36CC8 gpg2: Good signature from "17155x01" D:\Program Files\GNU\GnuPG> To Encrypt, Sign and ASCII Armour a file: To encrypt (and sign) data to send to Westpac (assume recipient key id is 'imported_westpac_key', and your local key-pair id is 'local_key'): > gpg2 --compress-algo 1 --cipher-algo cast5 --armor --recipient imported_westpac_key --local-user local_key --output <filename_to_write_encrypted_data> -se <filename_containing_data_to_encrypt> - Enter password for private key ( OR if using a batch-type environment ) > gpg2 --compress-algo 1 --cipher-algo cast5 - -passphrase-fd 0 --armor --recipient imported_westpac_key --local-user local_key -- output [filename_to_write_encrypted_data] -se [filename_containing_data_to_encrypt] <[filename_of_file_containing_password] An example of a batch file to do this would consist of: gpg2 --compress-algo 1 --cipher-algo cast5 --passphrase-fd 0 --armor --recipient 17155x01 --local-user smacmillan@acme.com --output test_enc.asc -se test.txt <password.txt Page 27

28 note: that password.txt contains you PGP private key password and is piped into the gpg2 command. The output when this batch file is executed would be: D:\Program Files\GNU\GnuPG>enc.bat D:\Program Files\GNU\GnuPG>gpg2 --compress-algo 1 --cipher-algo cast5 --passphras e-fd 0 --armor --recipient 17155x01 --local-user smacmillan@acme.com --output test_enc.asc -se test.txt <password.txt Reading passphrase from file descriptor 0 You need a passphrase to unlock the secret key for user: "Stephen Macmillan (Acme) <smacmillan@acme.com>" 1024-bit DSA key, ID 06F7317E, created gpg2: checking the trustdb gpg2: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model gpg2: depth: 0 valid: 1 signed: 1 trust: 0-, 0q, 0n, 0m, 0f, 1u gpg2: depth: 1 valid: 1 signed: 0 trust: 1-, 0q, 0n, 0m, 0f, 0u D:\Program Files\GNU\GnuPG>type test_enc.asc -----BEGIN PGP MESSAGE----- Version: GnuPG v1.4.2 (MingW32) hqioa38v4qeuuu0teaf+ireshirz+v8rfl6cqojkxa/lrgy+3n24unniqxydjuid +rvckgsgs2xjn6gukyxtsi7baxngghvbkragb6xbcl62sw7lqol5a8n2uwai6we/ qjildovdopd6oqfmnk8cntvb4mixjcqi+z6w+ljahthkjn2r8brdoyqdtypidj+u Z0sk1EjbZXVV1gJTj+uVy3LDvUiMOB1XMJn06lxz2nZQs4uzgRjqeGlI9x8HZS3d ti5fz39hwz4sn7chdj8qjhfxlo5u+ebc7hwdhsd/oiambfcey96f+njl0mvmnjr/ +vj6qgn9milccziwjt1csorogqrjmewpy0kcrqxcxwf/esbo/rs/dduygdniihj3 do1xl4wbpuntccwvqivpx8q5dzpdbsh98vvidalohzuyeupo7gwkps3zuesrb75l JDbzVCgXEvXrS00CMi/on2R66gsBaEHmwGzaMLHVBTavrImWmR1kvL6CYMufloYg MXbHF0ACEtR5DZ4PX6262OlnLKI+5St9EJ48zaYeJRT691IUqKqUIYNW9lnwOd7V jjea12it74opsavzm6alafn0vz483vzdlavnid2q/ijy2/pma8ejzbqbs/idptej Th5AuZcO9TI0tQEcyFxxIXM1AM/iZOhQUmvwAUGQWThta8Ri8fdhraupYyA5bZ0o 8MlzLRSAGO31hXLlBXUBUBH/4uhXpvE7n7dylCd8YDGl0ZAgypxQiuSGKzx01+s1 y1ghxp+xfo9dqaxqwbatnfkf3hs3diz15t/urpkt0ffue0gasyh62cbahhof/mja Page 28

29 d9mf/0it3gwrdf5zhpc7tx7mj8nv2w== =mbyr -----END PGP MESSAGE----- D:\Program Files\GNU\GnuPG> Page 29

30 4.3 Installing and Configuring Unicenter CA-XCOM Data Transport (version R11) Artefacts 1. Advantage CA-XCOM Unicenter Data Transport (version R11) installation CD System requirements Required OS for windows install: Windows 2003 Server. Note: XCOM R11 will not install on a domain controller Install Notes Ensure you have the correct version of XCOM. If you are installing XCOM on a server you need the server addition of XCOM. If you are installing it on a desktop you need the professional addition. XCOM must be installed via the console or terminal services using the console switch i.e. mstsc / console <server.rdp>. XCOM will note install via a standard terminal server window Steps 1. Insert the Advantage CA-XCOM installation CD into the machine s CD-ROM drive. If the installation process does not start automatically, start it by running the setup.exe executable in the root directory of the CD. 2. Click Next Page 30

31 Page 31

32 3. Click Yes 4. Click Next. Page 32

33 5. Ensure the Anyone who uses this computer (all users) radio button is selected, and click Next. Page 33

34 6. Set the XCom installation directory by clicking the Browse button. The recommended installation directory for Unicenter CA-XCOM is D:\xcomnt. If a different installation directory is chosen then record it for later use. Once the installation directory has been set, click Next 7. Select Custom and click Next. Page 34

35 8. Un-check the CA-XCOM SNA checkbox and click Next. Page 35

36 9. Click Next. 10. When the installation is complete, select the No, I will restart my computer later radio button and click Finish. Page 36

37 11. Using the Windows Services configuration window, change the XCOMD Unicenter CA- XCOM Scheduler Service service to Automatic start-up type. 12. Restart the machine. Page 37

38 4.3.5 Verification 1. Check that the XCOMD Unicenter CA-XCOM Scheduler Service exists in the list of system services, and is Started CA-XCOM R11 Application configuration 1. From the root directory of the CA-XCOM application installation, open the file \config\xcom.glb in Notepad, (or your preferred text editor) 2. Set the value for the property EXPIRATION_TIME= to 600 instead of the default A batch file can be set up to run upon XCom successfully receiving a file. Set the value for the property XPPCMD= to the name of the batch file to be run (full path required). 4. Set the value for the property XCOM_USERID= to the empty string (ie. Nothing). 5. Save and close the file. 6. Restart the XCOMD Unicenter CA-XCOM Scheduler Service Windows service. 7. To obtain external access to the XCOM Client, a Windows User will need to be added to the Windows Operating System, as per details required by the external system, which the XCOM Client will be used to communicate with. This will be the XCom username/password logon details used by external systems to communicate with your XCom client Security Permissions In order for Westpac to send a file to your XCOM server you must provide Westpac with an account and password. This is a system level account i.e. Windows or Unix account. The account must have enough privileges to do the following: 1. Write to the directory where you installed XCOM. This is required to place the incoming data on the XCOM queue. 2. Write to the directory where you require the incoming file to be placed. This is the directory where Westpac will tell XCOM to write the file Testing the XCOM Connection The next step is to test the connectivity between your XCOM client and Westpac. Before doing this please confirm the following: 17. You have provided your server s IP address and Westpac has confirmed that it has allowed that address through its firewall on port You have allowed your server to communicate on port 8044 through your own firewalls. 19. You have provided your PGP public key to Westpac. 20. Westpac has provided you with their PGP public key. 21. Westpac has provided you with an XCOM username and password To test the connection via the Internet or leased line To first check that you have connectivity try the following from your XCOM client: Page 38

39 1. Open a command prompt (cmd.exe) 2. Depending on your network path try the following telnet command: a. Via Internet try: telnet ssiw.qvalent.com 8044 b. Via Leased line try: telnet If you get a connection the screen should look like: _ (blank screen with flashing cursor in top left hand corner) If the screen looks like: H:\>telnet ssiw.qvalent.com 8044 Connecting To ssiw.qvalent.com...could not open connection to the host, on port 8044: Connect failed Then you can not establish a connection so consult with your network personnel. This could mean one of a couple of things. If you are connecting to the TEST environment (ssiw.support.qvalent.com) then it could mean that you have not opened your firewall for outbound connections. Westpac has no firewall restrictions on connections from the internet to its test environment. If you are connecting to production, then you must provide Westpac with your production IP address as you must open your own firewall and Westpac need to open there s as well. The IP address must be provided 5 days in advance before the go live date. To send a test transmission use a command similar to: d:\xcomnt\xcomtcp.exe -c1 -f REMOTE_SYSTEM=<Westpac_ip_address> PORT=8044 USERID=<user> PASSWORD=<password> REMOTE_FILE=<directory\file_to_write_into> PROTOCOL=TCPIP FILE_OPTION=CREATE TRANSFERIDENTIFIER=FILE QUEUE=NO COMPRESS=NO LOCAL_FILE=<file_to_send> Note: If your XCOM server is in a windows domain then please refer to FAQ section 5.3 Page 39

40 An example XCOM transfer is similar to: D:\pgp_scripts>d:\xcomnt\xcomtcp.exe -c1 -f REMOTE_SYSTEM=ssiw.qvalent.com PORT=8044 USERID=testuser PASSWORD=xxxxxx REMOTE_FILE=test\test_file.txt.asc PROTOCOL=TCPIP FILE_OPTION=CREATE TRANSFERIDENTIFIER=FILE QUEUE=NO COMPRESS=NO LOCAL_FILE=test_file.txt.asc (c) 2002 Computer Associates International, Inc. (CA). 05/10/14 11:49:14 TID= [test_file.txt.asc --> test\test_file.txt.asc at qv ts3] XCOMN0029I Locally initiated transfer started. 05/10/14 11:49:18 TID= XCOMN0011I Transfer ended; 19 records (1030 bytes) transmitted in 4 seconds (257 bytes/second) D:\pgp_scripts> 4.4 To Send a file via XCOM d:\xcomnt\xcomtcp.exe -c1 -f REMOTE_SYSTEM=<remote_system_ip_address> PORT=8044 USERID=<Westpac_assigned_username> PASSWORD=<Westpac_assigned_password> REMOTE_FILE=remoteDir\remoteFilename.txt PROTOCOL=TCPIP FILE_OPTION=CREATE TRANSFERIDENTIFIER=FILE QUEUE=NO COMPRESS=NO LOCAL_FILE=localFilename.txt 4.5 To Retrieve a file via XCOM d:\xcomnt\xcomtcp.exe -c4 -f REMOTE_SYSTEM_RF=<Westpac_ip_address> PORT=8044 USERID=<Westpac_assigned_username> PASSWORD=<Westpac_assigned_password> REMOTE_FILE_RF=<file_to_retrieve> PROTOCOL=TCPIP TRANSFERIDENTIFIER=RETRIEVE QUEUE=NO FILE_OPTION_RF=CREATE LOCAL_FILE_RF=<file_to_write_retrieved_data_to> the <file_to_retrieve> will be \\nas\production\xcomretrieve\<customerdir>\<filename> i.e. \\nas\production\xcomretrieve\acme\recall txt.asc 4.6 XCom Receiving Command File An example command file that gets executed by the XCOM client when it receives a file: Page 40

41 echo This batch file should only be opened using an XCom program, as the parameters that are required are very specific! rem rem Application and Resource locations rem SET JAVA_HOME=e:\jdk1.3 SET JARS_FOLDER=e:\FileTransfer\jars rem rem Property file location (fully qualified) rem SET PROPERTIES_FILENAME=e:\FileTransfer\cte_filetransfer_adapter.properties rem rem Class files rem SET DEPENDENT_JARS=%JARS_FOLDER%\xerces.jar;%JARS_FOLDER%\xalan.jar;%JARS_F OLDER%\ctcore.jar;%JARS_FOLDER%\jcert.jar;%JARS_FOLDER%\jnet.jar;%JARS_FOL DER%\jsse.jar;%JARS_FOLDER%\xp.jar;%JARS_FOLDER%\ConnectorCore.jar rem rem Get the parameters we need rem rem Get the Transaction ID (13th parameter) SHIFT /1 SHIFT /1 SHIFT /1 SHIFT /1 SHIFT /1 SHIFT /1 SHIFT /1 SHIFT /1 SHIFT /1 Page 41

42 SHIFT /1 SHIFT /1 SHIFT /1 rem Get the Received filename (20th parameter) SHIFT /2 SHIFT /2 SHIFT /2 SHIFT /2 SHIFT /2 SHIFT /2 %JAVA_HOME%\bin\java -mx800m -ms16m -classpath %DEPENDENT_JARS% com.westpac.exchange.connector.xcom.receivenewfile %PROPERTIES_FILENAME% %1 %2 4.7 Error Handling From a batch file you should always check the error level after the xcom call to ensure that the transfer was successful. Sample pseudo code for the batch file would be: d:\xcomnt\xcomtcp.exe -c1 -f REMOTE_SYSTEM=ssiw.qvalent.com PORT=8044 USERID=testuser PASSWORD=xxxxxx REMOTE_FILE=test\test_file.txt.asc PROTOCOL=TCPIP FILE_OPTION=CREATE TRANSFERIDENTIFIER=FILE QUEUE=NO COMPRESS=NO LOCAL_FILE=test_file.txt.asc >> output.txt if %ERRORLEVEL% NEQ 0 GTOTO ERROR echo Successful Transmission exit ERROR: Echo Bad Transmission output.txt to support personnel Page 42

43 5 FAQ 5.1 Common XCom Error Messages a. If the XCom error message looks like: (Standard Output Stream...) (Error Stream...) Copyright (c) 1992, 1996 Computer Associates International, Inc. All rights reserved. 03/04/14 10:52:51 TID= [<filename> --> <filename> at <ip_address>] XCOMN0029I Locally initiated transfer started. 03/04/14 10:52:52 TID= #XCOMN0298E Unable to allocate remote transaction program: Txpi 211: Socket connect error return value = This means that your XCom client could not obtain a connection to the external XCom client. This will be due to either a network issue, or the external system s XCom client service not running. b. If the XCom error message looks like: 2008/02/11 18:18:12 TID= PRG=xcomtcp PID=4904 IP= XCOMN0805I TCP/IP Connection Ended. 2008/02/11 18:18:12 TID= XCOMN0288E System function failed This means that when Westpac sends you a file the batch job you has specified in the <xcom install directory>\config\xcom.glb i.e. XPPCMD=e:\FileTransfer\ReceivedNewXComFile.bat Is failing to execute correctly and terminating abnormally. To debug the issue edit the xcom.glb file and change: 1. SHELL_CMD="cmd.exe" "/c" To SHELL_CMD="cmd.exe" "/k" 2. Restart the XCOM service Page 43

44 This will cause the DOS box to stay on the screen when the batch file runs when a file is received. Log into the server using the console and you will be able to see what is causing the error in your batch file. When it is fixed ensure that you set SHELL_CMD back to the /c switch to prevent the dialog boxes staying on the console. c) XCOM will not install via terminal services Please see section Install Notes 5.2 What Platforms is XCOM available for? Please consult the following link: XCOM User Account / Windows Domains When you create an XCOM user account under Windows NT it must be a local user on the server XCOM is installed and not a domain user account. A few other tips when creating an XCOM user account are: It is also advisable that you create an XCOM User Group and place this user into this group. For NT2000 and NT2003, ensure that the XCOM User Group has sufficient privileges to read & write files and execute scripts on the disk(s) where XCOM is installed or files will be accessed (such as the batch file that is called when a file is received). Try logging into the server using the just created XCOM user to ensure that there was no typo s with the username or password. If you are using NT2003, ensure that the XCOM User Group has the security rights to Access this computer from the network. If your xcom server is in a windows domain you must use the command line parameter DOMAIN= (blank space following equals sign) when sending to Westpac i.e. d:\xcomnt\xcomtcp.exe -c1 -f DOMAIN= REMOTE_SYSTEM=<remote_ip_address> PORT=8044 USERID=<Westpac_assigned_username> PASSWORD=<Westpac_assigned_password> REMOTE_FILE=remoteDir\remoteFilename.txt PROTOCOL=TCPIP FILE_OPTION=CREATE TRANSFERIDENTIFIER=FILE QUEUE=NO COMPRESS=NO LOCAL_FILE=localFilename.txt If you do not use this you will receive an error setting the remote user id from Westpac as your xcom server will be passing its domain name with its user name and Westpac will reject it. Page 44

45 5.4 GPG2 Questions Q) When I decrypt a file with GPG2 I get the following WARNING: gpg2: encrypted with 2048-bit ELG-E key, ID 2E52ED13, created "17155x01" gpg2: encrypted with 1024-bit ELG-E key, ID C45CC395, created "Stephen Macmillan (Westpac) <smacmillan@qvalent.com>" gpg2: Signature made 10/07/05 15:49:30 using DSA key ID C2E36CC8 gpg2: Good signature from "17155x01" gpg2: WARNING: message was not integrity protected A) This is a compatibility issue between GPG2 and ebusiness server and can be ignored. The important line to note is Good signature from 17155x01 This tells you that the file has not been tampered with. Q) When I encrypt a file using GPG2 I receive the following WARNING even though I have imported Westpac s key and signed it: It is NOT certain that the key belongs to the person named in the user ID. If you *really* know what you are doing, you may answer the next question with yes. Use this key anyway? (y/n) A) Try setting the trust level on the key using the command: Gpg2 edit-key <key name> Set the trust level to ultimate. Q) When I encrypt a file using a batch program with GPG2 and the file already exists the batch job stops and prompts me to about replacing the file: Page 45

46 File XXX.asc exists. Overwrite? (y/n) B) Try using the parameter --yes on your GPG2 encrypt / decrypt command line. This will automatically answer Yes for most questions GPG2 prompts for i.e. gpg2 --yes --output [filename_to_write_plaintext] --batch --passphrase-fd 0 --homedir [path_of_keyrings] --decrypt [filename_of_encrypted_data] <[filename_of_file_containing_password] Q) I m having trouble connecting to Westpac s test or production environments, what should I try? A) Refer to section Testing the XCOM Connection. Q) Can a file be encrypted with more than one public key? A) Yes! Westpac always encrypts files that it is sending to customers with both the customers public key and Westpac s public key. This allows a customer that is having difficulty decrypting a file (it may have become corrupted in transit) to send it back to Westpac to test decrypting it. Q) How can a file be encrypted with more that one public key? Doesn t this make the file twice as big? A) No. When GPG2 encrypts a file it generates a random session key and uses this random key to do the actual encryption. It then encrypts this session key with the recipient s public key and appends this data to the encrypted file. As Westpac always encrypts an outbound file with its own public key, the session key is also encrypted with Westpac s public key and this data is also added to the encrypted file. So encrypting with additional public keys only makes the file slightly larger. By doing this either the recipient or Westpac can use their private key to decrypt the session key which inturn is used to decrypt the file. Q) When I receive an encrypted file how do I know what public key(s) it has been encrypted with? A) use the following gpg2 command: # gpg2 --list-only --decrypt <file name> gpg2: encrypted with 1024-bit ELG-E key, ID 26787C6E, created "test <test@qvalent.com>" Page 46

47 6 Glossary CA-XCOM CA-XCOM is a cross-platform, valueadded data transport solution, providing high-performance unattended file transfer with complete audit trails and reporting. CA-XCOM provides a single solution for sending and receiving files, as well as sending reports and jobs, to a wide range of platforms. This is Westpac s standard file transfer mechanism. Certificate An electronic document that identifies an entity (e.g. a person, computer or company). Each certificate contains the entity s public key, along with details about which encryption algorithms the entity can use. Certificates are issued by Certificate Authorities (CAs) when the CA verifies the entity requesting the certificate. Each certificate contains a subject, describing who the certificate is for, and an issuer, describing the organisation that signed the certificate. The certificate contains the entity s public key, as well as the digital signature of the CA. This signature is like a hologram on a credit card, verifying that the CA has authenticated the entity s identity. Certificates can be marked for various purposes, including SSL client, SSL server and CA. See also Certificate Authority, Digital Signature, SSL and Public Key Encryption. Certificate Authority A trusted third party that signs certificates for other parties. Often in internet communications, the two parties will not trust each other, but will trust a third party. Party A can trust party B s certificate if it is signed by that third party (the certificate authority or CA). Certain CAs (e.g. Verisign, Thawte) are automatically trusted by all certificate software. See also Certificate and Certificate Hierarchy. Certificate Hierarchy The chain of certificates for an entity consisting of that entity s certificate and any CAs which signed the certificate. All certificates are signed by another certificate, generating a hierarchy. This hierarchy terminates at a root certificate, which is self-signed. This type of certificate contains an identical issuer and subject. A certificate is trusted by a party if the certificate chain terminates at a CA which is trusted by that party. Each party maintains a list of trusted root CAs. See also Certificate, Certificate Authority and Self-signing. Diffie-Hellman Diffie-Hellman (DH) was the first openly published public key system [DH76] (more correctly Diffie-Hellman is a keyexchange mechanism) and as such has received extensive analysis by eminent cryptographers. Westpac uses a 2048 bit key size. Digital Signature A process of signing a message electronically. Normally, the sender of a message will calculate a message digest, then encrypt that digest value with the sender s private key. This resulting value is the digital signature. The receiver can verify the signature by calculating the message digest, and comparing it to the value obtained by decrypting the digital signature with the sender s public key. See also Message Digest and Public Key Encryption. Page 47

48 DSA / DSS Digital Signature Algorithm (DSA) / Digital Signature Standard (DSS). DSA produces a fixed width signature (irrespective of the public/private key size for the authentication of electronic documents. Westpac uses a 1024 bit key size. ElGamal In cryptography, the ElGamal encryption system is an asymmetric key encryption algorithm for public-key cryptography which is based on the Diffie-Hellman key agreement. ElGamal encryption is used in the free GNU Privacy Guard software, recent versions of PGP, and other cryptosystems. The Digital Signature Algorithm (DSA) is a variant of the ElGamal signature scheme, which should not be confused with ElGamal encryption. Encryption/Decryption The process of scrambling a message so that it cannot be read by a third party while in transit. The sender encrypts a message before sending, and the receiver decrypts the received message before reading it. Many algorithms are available to encrypt data. Examples include RSA, RC4 and DES. The algorithm is generally wellknown, but a number (called a key) must be used with the algorithm to produce an encrypted result or to decrypt previously encrypted information. Decryption with the correct key is simple, whereas without the key, decryption is almost impossible. HTTP Hypertext Transfer Protocol: The application level protocol that is used to transfer data on the web. A client sends a request message to the server, and the server sends a response message. Each message consists of a start line (which is either a request line or a status line as appropriate), followed by a set of message headers and finally an optional message body. The request line contains the method (usually GET or POST) used for the request. GET is a simple request for information, whereas POST allows the client to send data to the server in the request. A web browser generally sends a GET request to the server for information, and the server responds with a HTML document in the response for the browser to display. The HTTP protocol uses the TCP/IP protocol to transport the information between client and server. HTTP uses TCP port 80 by default. See also TCP/IP. HTTPS Hypertext Transfer Protocol, Secure: The HTTP protocol using the Secure Sockets Layer (SSL), providing encryption and non-repudiation. HTTPS uses TCP port 443 by default. See also HTTP and SSL. Message Digest A mathematical function which generates a number from a message (also called a one-way hash). The generated number is unique for the message, in that changing any part of the message changes the resulting number. The function is one-way in that it is, for all practical purposes, impossible to determine the message from the number. Common algorithms are MD5 and SHA-1. Non-repudiation Assurance the sender of data is provided with proof of delivery and the recipient is provided with proof of the sender's identity, so neither can later deny having processed the data. Proxy Server An intermediate server on the client side of a HTTP transaction which makes requests on behalf of the client. Proxy servers improve corporate security by only exposing the proxy server to the Page 48

49 internet, rather than each individual computer in the organisation. The client sends its request to the proxy server, which then sends the request (with any modifications) to the server. The server responds to the proxy, which then passes the response to the client. Client request Proxy Server response response request Server System administrators can restrict which servers are accessible simply by configuring the proxy server. See also HTTP. Public Key Encryption An encryption method where different keys are used for encryption and decryption. Each party has two keys a public key and a private key. Messages encrypted with the public key can only be decrypted with the private key, and messages encrypted with the private key can only be decrypted by with the public key. Each party publishes their public key and keeps their private key secret. Encryption is accomplished by the sender encrypting the message with the receiver s public key. The message can then only be decrypted by the receiver with his private key. Non-repudiation is accomplished by the sender encrypting the message with her private key. The message can then be decrypted by anyone with the sender s public key (which is published), but the receiver can be assured of the message s origin. See also Symmetric Key Encryption and Encryption. Self-Signing Self-signing occurs when the owner of a key uses his private key to sign his public key. Self-signing a key establishes some authenticity for the key, at least for the user IDs. The user ID of the signature must match the user ID of the key. (Where there are multiple user IDs, the ID of the signature must match the primary ID of the key.) Also, the key ID of the signature matches the key ID of the key. This verifies that whoever placed a user ID on a public key also possesses the private key and passphrase. Of course, this does not verify that the owner of the key is really who she says she is. That is done by the signatures of others on the public key (such as a root CA like Verisign). SOAP Simple Object Access Protocol: An XMLbased protocol allowing remote procedure calls and asynchronous messaging. SOAP generally uses HTTP to transport the messages between computers. SOAP is becoming popular because of its use of standard internet protocols as its basis. See XML and HTTP. SSH Secure Shell: SSH is a secure delivery mechanism. It is the encrypted protocol that allows secure communications between two parties. The file transfer protocol that lies under SSH can be either XCOM or SCP. SCP is a single-file copy protocol where a single file can be non-interactively transferred between two hosts. Compare this to the standard copy command across two network shares XCOM is an interactive protocol that allows browsing of the remote host as well as file transfers. Compare this to the standard interactive ftp protocol. SSL Secure Sockets Layer: A protocol designed by Netscape to encrypt data, authenticate the client and server and ensure message integrity. SSL sits between the application layer protocol Page 49