Chapter 1   Configuration



Configuration Overview

---

The following configurations need to take place:

• Certificates and Bank Back End Authorisation

• Database checkpoints that allow you gain access to information about the cause of error during runtime

• Screen Services

• Payments Screens

• Customers Authorisation Services

Certificate Configuration

---

Before testing your installation is complete you will need to configure the system with the appropriate certificates.

Buyers Bank Certificates

You'll need a signing certificate issued to you by your Bank and containing a Trusted Identrus Root. This is a certificate hierarchy and contains a PKCS12 signing chain containing private key for signing information.

Sellers Website Tooled Up Certificates

This is dealt with in the Install procedure for tooledup.

iPlanet Trustbase Transaction Manager Certificates

Certificates need to be configured as described in the Identrus four corner model. See runCertWizard in the iTTM 3.0.1 Installation and Configuration Guide

http://docs.sun.com/source/816-6283-10/index.html

iPlanet Trustbase Payment Services Certificates

None required

BiaB Certificates

No certificates required

CPI certificates

Please refer to Chapter 3 of the Developer Guide for details of how to install certificates

Secure properties (Optional)

Once installation is complete you may wish to secure certain properties by redirecting these properties to an encrypted file

/opt/ittm/myhost/secure.properties

For details on how to do this please consult the iPlanet Trustbase Transaction Manager Installation and Configuration Guide.

Database Table Definitions

---

This section classifies all of the tables in an iTTM/iTPS/BIAB/Tooled Up installation.

Table Name	Product	Description
archive_table	iTTM	No Longer Used
attribute_key_attrs	iTTM	No Longer Used
attribute_name_attrs	iTTM	No Longer Used
auditdata	iTTM	Log of all audit events
audit_parameters	iTTM	Log of all event specific parameters for each audit event
audit_services	iTTM	Private Internal Data
audit_text	iTTM	Mapping of audit strings to locale specific strings
authorisation	iTTM	Private Internal Data
biab_requests	BIAB	All messages arriving at BIAB
biab_responses	BIAB	All messages leaving BIAB
biab_user	BIAB	Valid users of BIAB
bill_data	iTTM	An entry for each Identrus Message is made here, it maps the message signer information to a raw log entry.
category	Tooled Up	Private Internal Data
cdpcert	Tooled Up	Private Internal Data
certificateauthentication	iTTM	Private Internal Data
cert_data	iTTM	All unique certificates from Identrus CertBundles are logged here.
cert_table	iTTM	No Longer Used
condition	Tooled Up	Private Internal Data
config	iTTM	Private Internal Data
cr_condition	iTPS	Private Internal Data
cr_condition_set	iTPS	Private Internal Data
cust_dn_mapping	iTPS	Maps customer certificate to a Bank internal reference. Used for authorisation checking if enabled.
default_locale	iTTM	Private Internal Data
ecips_gatewaypref	iTPS	Private Internal Data
ecips_memdetails	iTPS	Private Internal Data
ecips_timeouts	iTPS	Private Internal Data
eleanor_reference_map	iTPS	Maps Eleanor Tx Id to associated MsgGrpId
environments	iTTM	Private Internal Data
error	iTTM	Log of all errors
error_codes	iTTM	Mapping of error codes to locale specific strings and error severity
error_map	iTPS/BIAB	Maps reason codes to reason texts
error_map_1_0	iTPS/BIAB	No Longer Used
error_map_locales	iTTM	Private Internal Data
error_parameters	iTTM	Log of all error specific parameters for each error entry
error_support	iTTM	Log of supporting error data for error entries - java stacktraces
identrus_data	iTTM	For each Identrus message in the raw log table an entry exists here with key Identrus message fields extracted into the table entry
identrus_messages_set	iTPS	Private Internal Data
init_table	iTTM	Private Internal Data
key_table	iTTM	No Longer Used
ocsp_data	iTTM	Every OCSP request/response that goes to the local OCSP responder - OR request/response from a remote OCSP responder in fallback mode.
ocsp_requests	iTTM	Used by the OCSP responder in iTTM to log all requests received.
ocsp_responses	iTTM	Used by the OCSP responder in the iTTM to log all responses sent out.
ohr	iTPS	Private Internal Data
ordered_product	Tooled Up	Private Internal Data
payment	Tooled Up	Private Internal Data
payments_log_email	iTPS	All outbound emails from iTPS are logged in this table.
payments_raw_in	iTPS	All messages received from the backend bank system are logged
payments_raw_out	iTPS	All messages sent to the backend bank system are logged
product	Tooled Up	Private Internal Data
product_order	Tooled Up	Private Internal Data
raw_data	iTTM	All messages arriving at iTTM are logged in this tamper evident table
registered_user	Tooled Up	Private Internal Data
registered_user1_0	Tooled Up	No Longer Used
revocation_attrs	iTTM	No Longer Used
revocation_serial_num	iTTM	No Longer Used
revocation_table	iTTM	No Longer Used
roles	iTTM	Private Internal Data
role_description	iTTM	Private Internal Data
salt_table	iTTM	No Longer Used
sc_currency_code	iTPS	All allowable currency codes
sc_currency_code_list	iTPS	Currency code to currency description mapping
sc_financial_institution	iTPS	Private Internal Data
sc_settlement_chain	iTPS	Private Internal Data
smime_transport	iTTM	All smime messages have their security information logged
smtp_connection	iTTM	All connections to the SMTP proxy are logged
smtp_message	iTTM	All smtp messages received by the SMTP proxy are logged
sohr	iTPS	Private Internal Data
ssl_connection	iTTM	No Longer Used
trans_ref_cancellation_req	iTPS	Private Internal Data
trans_ref_payment_req	iTPS	Private Internal Data
ttm_organisation	iTTM	Private Internal Data
ttm_role	iTTM	Private Internal Data
ttm_user	iTTM	Private Internal Data
ttm_user_role	iTTM	Private Internal Data
usernamepasswordauth	iTTM	Private Internal Data

• All tables marked as 'Private Internal Data' are controlled by the specified product and the structures of these tables are subject to change in future revisions.

• All tables marked as 'No Longer Used' are tables that existed in an earlier version of the product that are deprecated in the current version. Because of upgrade paths these tables are not dropped by their respective products, the DBA is at liberty to drop these tables once the contained data is no longer needed.

Database Check Points

---

This data flow checkpoint diagram and list of points will be used during a transaction and can be used to help locate where an event or error occurs in the system. This is only applicable to synchronous messages. When messages are sent from the Seller web site, messages can be traced at the following points, illustrated using the three corner model in Figure 1-1 "Data Checkpoint List for the three corner model":

Checkpoint	Action/Step/Entry	Table/Location to view data/Message
1	Buyer posts a request to the seller's web site.	Web server log (web server): /opt/iws6/logs/access
2	Message (transaction) is sent from CPI to iTTM/iTPS (TC). The message is logged.	Kxs access is written with a timestamp:/opt/ias6/logs/kxs Kjs jvm log file with system.out text: /opt/ias6/logs/kjs iTTM Oracle table: RAW_DATA
	Initially message is validated. If error in validation, log to audit. If error in system, log to error	iTTM Oracle table: AUDITDATA iTTM Oracle table: ERROR
3	TC performs validation check using OCSP to check the status of the Seller's (Tooled Up) signing certificate.	OCSP_DATA log (See OCSP vendor logs)
4	CSC request to Identrus root (freshness).	iTTM Oracle table: RAW_DATA
5	CSC response from Identrus root	iTTM Oracle table: RAW_DATA
6	TC sends message to BiaB.	iTTM Oracle table: PAYMENTS_RAW_OUT
7	BiaB receives message and logs to BiaB Oracle	BiaB Oracle table: BIAB_REQUESTS. Note this message is identical to the message in PAYMENTS_RAW_OUT (step 6). BiaB terminal shows that a message is received.
8	BiaB processes message and logs response to TC in BiaB Oracle.	BiaB terminal shows that a message is ready. BiaB Oracle table: BIAB_RESPONSES
9	TC receives message from BiaB and logs incoming message.	iTTM Oracle table: PAYMENTS_RAW_IN. Note the message is identical to the message in BIAB_RESPONSES (step 8).
10	TC sends message to web server and logs the outgoing message.	iTTM Oracle table: RAW_DATA
11	Seller (tooled up) logs payment message and status.	iTPS PAYMENT

Figure 1-1    Data Checkpoint List for the three corner model

A typical query might be

select * from biab_requests where lastack like `%Service%' and type like `%xPx';

order by timestamp desc;

iTTM Tables

---

Auditdata

Contains internal audit information & indicates what the TC processed.

Figure 1-2    TTM table Auditdata

Column Name	Type	Size	NULL	Key Information	Description
auditid	NUMBER			Primary Key	Unique Identifier. Monotonic sequence number.
messageid	VARCHAR2	240			Not Used
machineid	VARCHAR2	50	Not Null		IP address of machine that logged audit event
timestamp	DATE		Not Null		The timestamp of when event was logged.
audittype	VARCHAR2	200	Not Null	FK-> audit_text.audit_text_id	The class of audit that this event is
message	VARCHAR2	1000	Not Null	FK - audit_text.audit_text_id	The audit message reference

Auditparameters

Log of all event specific parameters for each audit event.

Figure 1-3    iTTM table Auditparameters

Column Name	Type	Size	NULL	Key Information	Description
auditid	NUMBER			FK-> AUDITDATA.auditid	The audit id in auditdata that this parameter relates to.
parameter	VARCHAR2	2000			The value of the parameter
parameter_no	NUMBER				The "tag" number when this parameter value is inserted into the audit_text

audit_text

Maps audit strings to locale specific strings

Figure 1-4    iTTM table audit_text

Column Name	Type	Size	NULL	Key Information	Description
audit_text_id	VARCHAR2	1000	Not Null	PK	Unique Id
text	VARCHAR2	1000			The text of the audit message or type in a locale specific form
locale	VARCHAR2	10	Not Null		The locale of the text

bill_data

Billing records are a sub-set of the information within the raw message log that provides sufficient information to determine who made each transaction. These tables are designed for used by third party tools that generate the actual Bill for the customer. The definitions for the bill table columns are as follows:

Figure 1-5    iTTM table bill_data

Column Name	Type	Size	NULL	Key Information	Description
subjectdn	VARCHAR2	500	Not Null		This will be the originator distinguished name extracted from the mandatory Identrus level 1 message signature. This will determine who should be billed.
issuerdn	VARCHAR2	500	Not Null		This will be the issuer distinguished name extracted from the mandatory Identrus level 1 message signature. This is to enable the identification of the exact key used to sign this message - in conjunction with the serial number field below.
serialnumber	VARCHAR2	100	Not Null		This will be the originator certificate serial number that may be used to identify the exact key used to sign the message - in conjunction with the issuer distinguished name.
rawrecordid	VARCHAR2	240	Not Null	FK->raw_data.recordmarker	This will be the RawRecordId of the associated raw log table record.

cert_data

In order to reduce the volume of data logged with each Identrus message the certificates contained with the message header are stripped out and stored in a certificate table. If the iPlanet Trustbase Transaction Manager has already logged a particular certificate in the table it will not be logged again. The information stored within the table is:

Figure 1-6    iTTM table cert_data

Column Name	Type	Size	NULL	Key Information	Description
issuerdn	VARCHAR2	500	Not Null	PK	The issuer distinguished name of the certificate, RFC 2253 format string.
serialnumber	VARCHAR2	100	Not Null	PK	The serial number of the certificate
subjectdn	VARCHAR2	500	Not Null		The subject distinguished name from the certificate, in RFC2253 format
certdata	LONG		Not Null		The Base64 certificate data.

Error

The actual error log table is described below, this table is not normally viewed by the administrator directly, instead there is an Oracle view called errorview that provides a resolved view of the errors that have been logged.

Figure 1-7    iTTM table error

Column Name	Type	Size	NULL	Key Information	Description
errorid	NUMBER		Not Null	PK	This is a unique id for the error log entry; it is generated from a monotonic sequence that means that this field may be used to accurately order error messages in the order that they were logged
errorcode	VARCHAR2	7		FK - error_codes.errorcode	This is the errorcode of the error being logged, see the error_codes table description.
timestamp	DATE				This is an ORACLE DateTime field that identifies when the error was logged.
machineid	VARCHAR2	50			This is a string representing the IP address of the iPlanet Trustbase Transaction Manager that logged the error - this may be different in a multi-node IAS installation.
contextid	VARCHAR2	200			This context id field is for future expansion.

error_codes

The iPlanet Trustbase Transaction Manager error logging mechanism requires that every different occurrence of an error be given a code which is unique throughout iPlanet Trustbase Transaction Manager.

Figure 1-8    iTTM table error_codes

Column Name	Type	Size	NULL	Key Information	Description
errorcode	VARCHAR2	7	Not Null	PK	This is the unique errorcode string that identifies the error; this must be 7 characters exactly. The normal for an error code is XXXnnnn. Where XXX is a three-letter code for the service or subsystem and nnnn is a unique number. e.g. IPH0009 is an error in the Identrus Protocol Handler.
classname	VARCHAR2	500			The class from which this error is logged. This places a constraint that each error code may only be used from one place.
severity	NUMBER				This is the severity level of the error, described previously. Constants for each of the error severities can be located in the uk.co.jcp.tbaseimpl.log.error.ErrorLog class.
message	VARCHAR2	2000	Not Null		This is the localised version of the error message that will appear in the error log. Parameters may be used in this message as described by the standard Java class java.text.MessageFormat. The values to be placed in these parameters are passed in an array of strings that one of the ErrorObject constructors allows.
locale	VARCHAR2	10	Not Null		The locale of this error message text

error_parameters

This is a cross referencing table used for querying errors. parameters are used to expand text according to the error text.

Figure 1-9    iTTM table error_parameters

Column Name	Type	Size	NULL	Key Information	Description
errorid	NUMBER			FK - error.errorid	Error Number
parameter	VARCHAR2	200			Parameter description
parameter_no	NUMBER				Parameter number

error_support

When an error is logged it is often accompanied by some free form string data which helps to store the context in which the error occurred to aid diagnosis. The most common example of such data is exception stack traces.

Figure 1-10    iTTM table error_support

Column Name	Type	Size	NULL	Key Information	Description
errorid	NUMBER			FK - error.errorid	This links this entry to an entry in the Error table
datatype	VARCHAR2	200	Not Null		This datatype is an arbitrary string identifier that categorises the data in the data field. The only value for this field defined by iPlanet Trustbase Transaction Manager is "STACKTRACE" which identifies the contents of the data field to be a Java Exception Stack Trace.
data	LONG				Free form string data

identrus_data

The Identrus data table records identrus specific message data, which can be related to the raw log records in the raw_data table, using the rawrecordid foreign key.

Figure 1-11    iTTM table identrus_data

Column Name	Type	Size	NULL	Key Information	Description
rawrecordid	VARCHAR2	240	Not Null	FW - rawdata.recordmarker	the id of the associated raw log record
msggrpid	VARCHAR2	120	Not Null		the Identrus MsgGrpId from the NIB of the message
msgid	VARCHAR2	120	NotNull
doctype	VARCHAR2	120	Not Null		the DOCTYPE of the message.e.g.CSCRequest, PingRequest etc.
connectionid	VARCHAR2	100	NotNull		No Longer Used
protocoltype	VARCHAR2	10	Not Null		The protocol over which the message arrived e.g. HTTP or SMTP
input	NUMBER		Not Null		1 indicates message was inbound to the TC. 0 indicates that the message was outbound from the TC.

ocsp_data

This data records all the ocsp transactions -- responses and requests that are carried out between the local ocsp responder and iTTM.

Figure 1-12    iTTM table ocsp_data

Column Name	Type	Size	NULL	Key Information	Description
ocspid	NUMBER		Not Null	PK	A unique identifier for the record
type	VARCHAR2	2000	Not Null		OCSPREQUEST or OCSPRESPONSE
message	VARCHAR2	2000	Not Null		A text summary of the contents of the request or response
machine	VARCHAR2	2000	Not Null		The URL to which the request was submitted to or the response was received from
timestamp	NUMBER		Not Null		The date and time that the entry was made
data	LONG		Not Null		Base64 encoding of the request or response

ocsp_requests

Records messages sent from iTTM to the OCSP Responder.

Figure 1-13    iTTM table ocsp_requests

Column Name	Type	Size	NULL	Key Information	Description
id	VARCHAR2	127	Not NULL	PK	Unique Identifier
requestor_name	VARCHAR2	500	Not Null		The DN of the person requesting the OCSP
signed	NUMBER				Whether it was signed (0 or 1)
version	NUMBER				Version number of OCSP
request	LONG RAW				DER of the request
timestamp	DATE		Not Null		Time of the request

ocsp_responses

Records messages received from the OCSP responder to iTTM

Figure 1-14    iTTM table ocsp_responses

Column Name	Type	Size	NULL	Key Information	Description
id	VARCHAR2	127	Not Null	PK	Unique Identifier connected between request and response
status	NUMBER				Overall status of the response (See RFC2560)
response	LONG RAW				DER of the response
timestamp	DATE		Not Null		Time of the response

raw_data

The raw log inserts a row into a relational database table for each log operation. The structure of the database table is described here. All raw log tables have the same structure, although each raw log uses a different table, whose name is determined when the raw log is created with the AddLoggerWizard. The raw logging facility records raw incoming and outbound message data.

Figure 1-15    iTTM table raw_data

Column Name	Type	Size	NULL	Key info	Description
sessionid	NUMBER		Not Null		The id of the raw log session that wrote record
logconnectionid	NUMBER		Not Null		The id of the connection within the session
recordid	NUMBER		Not Null		The id of the record within the connection
msggrpid	VARCHAR2	120			No Longer Used
msgid	VARCHAR2	120			No Longer Used
doctype	VARCHAR2	120			No Longer Used
recordmarker	VARCHAR2	240	Not Null	PK	A unique monotonically increasing identifier
connectionid	VARCHAR2	100			No Longer Used
protocoltype	VARCHAR2	10			No Longer Used
input	NUMBER				No Longer Used
timestamp	NUMBER		Not Null		An integer which represents the UNIX time at which the record was logged.
rawdata	LONG		Not Null		The Identrus Message XML, without the CertBundle fields. The certificates from the bundle are logged separately in the "cert_data_table"
digestofrecord	RAW	2000			A SHA-1 digest of this record.
signeddigestofcalculation	RAW	2000			An RSA signature of this record and data from the previous record.

smime_transport

Logs incoming SMIME connections

Figure 1-16    iTTM table smime_transport

Column Name	Type	Size	NULL	Key Information	Description
connection_id	VARCHAR2	100	Not Null	PK	Provides a link back to the smtp_message table
peer_issuer_dn	VARCHAR2	2000			The issuer_dn of the certificate that was used to verify the message
peer_cert_serial_number	VARCHAR2	100			The serial number of the certificate used to verify the message.
message_protection	VARCHAR2	100			The type of protection used to secure the message
time_stamp_type	VARCHAR2	10			The type of timestamp LOCAL or NETWORK
time_stamp	DATE		Not Null		The time at which the entry was made

smtp_connection

The ssl_connection and smtp_message tables both have connection_id fields that are passed to the iPlanet Trustbase Transaction Manager running in the application server. This connection_id is stored within the Identrus Log table allowing queries that link the originator information with the actual requests made.

Figure 1-17    iTTM table smtp_connection

Column Name	Type	Size	NULL	Key Information	Description
stream_id	VARCHAR2	100	Not Null	PK	Identifier for the connection
peer_ip_addr	VARCHAR2	20	Not Null		IP address of the peer
timestamptype	VARCHAR2	10			Whether the time of the connection was local or remote
timestamp	DATE		Not Null		The time the connection was made

smtp_message

Logs incoming SMTP mail messages.

Figure 1-18    iTTM table smtp_message

Column Name	Type	Size	NULL	Key Information	Description
stream_id	VARCHAR2	100	Not Null	FK->smime_transport.connection_id	A unique id for the smime_transport
connection_id	VARCHAR2	100	Not Null	FK->smtp_connection.stream_id	A unique id for the smtp connection
recipients	VARCHAR2	1000	Not Null		The recipients of this message
sender	VARCHAR2	100	Not Null		The sender of this message
timestamptype	VARCHAR2	10			The type of timestamp LOCAL or NETWORK
message_valid	NUMBER		Not Null		Is the message valid? 1 indicates it is valid
message_invalid_reason	VARCHAR2	1000			The reason for the invalidity of the message
timestamp	DATE		Not Null		The date and time at which the entry was made

iTPS Tables

---

cust_dn_mapping

This table maps the Distinguished name of the customer signing certificate to the bank's internal customer reference number.

Figure 1-19    ITPS table cust_dn_mapping

Column Name	Type	Size	NULL	Key Information	Description
dn	VARCHAR2	1024	Not Null	PK	This is the subject distinguished name of the customer's signing certificate
cust_id	VARCHAR2	36	Not Null		This is the bank's internal customer reference number that is associated with the customer's signing certificate subject dn.

eleanor_reference_map

Maps Eleanor transaction references to Eleanor messages that contain the associated message group id.

Figure 1-20    iTPS table eleanor_reference_map

Column Name	Type	Size	NULL	Key Information	Description
reference	VARCHAR2	36	Not Null		Eleanor transaction reference value.
msggrpid	VARCHAR2	100	Not Null	FK->identrus_data.msggrpid	message group id for the Eleanor message.

error_map

List of Eleanor reason codes and associated reason text

Figure 1-21    iTPS table error_map

Column Name	Type	Size	NULL	Key Information	Description
code	VARCHAR2	6	Not Null		Reason Code
text	VARCHAR2	300	Not Null		Associated reason text that accompanies the reason code
type	VARCHAR2	40	Not Null		The type acknowledgement this reason code is associated with.
status	VARCHAR2	7	Not Null		Indicates whether this reason code is associated with a success or failure state.

payments_log_email

This table records which email is sent to whom.

Figure 1-22    iTPS table payments_log_email

Column Name	Type	Size	NULL	Key Information	Description
time_stamp	NUMBER		Not Null		When the email was sent
subject	VARCHAR2	120			The subject name of the email
toemail	VARCHAR2	120			To whom this email is addressed
fromemail	VARCHAR2	120			The sender of this email
rawemail	LONG				The raw contents of the email data.

payments_raw_in

Records all messages that are sent to iTPS

Figure 1-23    iTPS table payments_raw_in

Column Name	Type	Size	NULL	Key Information	Description
time_stamp	NUMBER		Not Null	PK	Time the message was received by iTPS from Biab
group_id	VARCHAR2	120	Not Null	PK	The msggrpid of the associated message originally received by Biab to which this is a response
message_id	VARCHAR	120	Not Null	PK	The msgid of associated message originally received by Biab to which this is a response
raw_data	LONG				The actual xml data that constitutes the data

payments_raw_out

Records all messages that are sent from iTPS

Figure 1-24    iTPS table payments_raw_out

Column Name	Type	Size	NULL	Key Information	Description
time_stamp	NUMBER		Not Null	PK	The time at which iTPS sent the message to Biab
group_id	VARCHAR2	120	Not Null	PK	The msggrpid from the original Identrus Eleanor message.
message_id	VARCHAR2	120	Not Null	PK	The msgid from the original Identrus Eleanor message.
raw_data	LONG				The actual XML data that constitutes the message.

sc_currency_code

Contain information about currencies that are used in Payment Transactions

Figure 1-25    iTPS table sc_currency_code

Column Name	Type	Size	NULL	Key Information	Description
sc_currcode	VARCHAR2	3	Not Null	PK	The code that represents a currency
sc_currname	VARCHAR2	255	Not Null		The description that describes the currency

sc_currency_code_list

Contains a list of currencies that are linked to a settlement chain.

Figure 1-26    iTPS table sc_currency_code_list

Column Name	Type	Size	NULL	Key Information	Description
sc_currencyname	VARCHAR2	255	Not Null		Currency description that is linked to a specific settlement chain
sc_currencycode	VARCHAR2	3	Not Null		Currency code that is linked to a specific settlement chain

BIAB_Requests

All messages arriving at Biab.

Figure 1-27    iTPS table BIAB_Requests

Column Name	Type	Size	NULL	Key Information	Description
id	NUMBER	22	Not Null	PK	Unique Identifier
timestamp	NUMBER	22			Timestamp reflecting when the message is received
customerid	VARCHAR2	200			The subscriber id
customerdn	VARCHAR2	1024			The DN of the subscribing customer
type	VARCHAR2	40			The type of the message, e.g "xPx"
reference	VARCHAR2	100			Bank Reference associated with the message
sfireference	VARCHAR2	100			SFI reference if any associated with the message
msggrpid	VARCHAR2	120			The Message Group id from the message
msgid	VARCHAR2	120			The Message id of the message
messagetype	VARCHAR2	50			The doctype of the message
scheme	VARCHAR2	7			The payment scheme, i.e. Eleanor
lastack	VARCHAR2	40			The type of the last acknowledgement that was sent in response to this message
ackid	VARCHAR2	22			This identifies the actual response that was sent
message	LONG	LONG			The xml message content

BIAB_Responses

All messages sent from Biab.

Figure 1-28    iTPS table BIAB_Responses

Column Name	Type	Size	NULL	Key Information	Description
id	NUMBER	22	Not Null	PK	A Unique Identifier
requestid	NUMBER	22		FK	The id of the related request
timestamp	NUMBER	22			the timestamp when the response was sent
type	VARCHAR2	40			The type of the response, e.g. PayInst
username	VARCHAR2	40			The name of the user who initiated the response
reference	VARCHAR2	40			Bank reference if provided
message	LONG	LONG			The XML message content

Configuration Pre-requisites

---

iTTM and iTPS, and all their associated components such as iAS and iWS, should be running while configuring services within iTTM.Thus, you must make sure the following software is up and running in the order specified

1. Oracle 8.1.7

2. nCipher HSMs on all machines

3. iMQ for Java 2.0 on both the Buyer and Seller Bank machines

4. Bank in a Box and iWS 6.0 on the Buyer and Seller Bank machines

5. Bank in a Box administration tool server and iWS 6.0 on the Buyer and Seller Bank machines

6. iTPS on the Buyer and Seller machines
   1. iWS 6.0 SP1 on both the Buyer and Seller Bank machines

   2. iAS 6.0 SP3 on both the Buyer and Seller Bank machines

   3. iTTM 3.0.1on both the Buyer and Seller Bank machines

7. JMQ Proxy on both the Buyer and Seller Bank machines

8. Buyer web site (BFI) web server

9. Tooledup Seller web site web server

10. Condition Management Website

11. Obligation Management Website

System Configuration

---

iPlanet Payment Services Configuration can be accessed from the following menu

Figure 1-29    Payment Main Menu

Payment Gateway Preferences

The system administrator may configure

· The JMS queue identifiers used to communicate with the payment gateway.

· The timeout to be used when communicating with the payment gateway.

Figure 1-30    Payment Gateway Preferences Screen

This is already configured from the original installation and is set here as the default.

• · Outbound Queue may not be empty

• Timeout is how long you are prepared to wait for a response when you send a message to your JMS queue. 0 is the default and this means it waits indefinitely until it gets a response.

• Number of Timeouts is the number of times you send a message to a queue to get a response. When the timeout is set to 0 it does not matter what you enter here.

Scheme Membership List

The system administrator may add, modify or delete entries from the Scheme Membership List.

If you want to use asynchronous acknowledgements you must populate the membership screens even if the membership is switched off. The membership entries allow iTPS to route acknowledgements to the F.I.

Figure 1-31    Membership List

1. The membership entry must be made for both the member's issuing certificate (L1CA) and its inter-participant signing Certificate (L1IPSC). Use tokenkeystoretool on the member's Financial Institution installation to view the required Certificate DN's. You will also need your own financial institution's details entered into the membership screen so that iTPS is set-up to be able to recognise itself. Asynchronous acknowledgements will fail if these entries are not present.
   1. Type the following preparatory commands

      ./opt/ittm/Scripts/runtokenkeytool

   2. Open the store

      openstoremanager -domainspace "file:///itps-cpi/store" -manager local

      setdefaultstore -manager local -store identrus

   3. For the verification certificate, type

      listcerts

   4. For the Signing Certificates, type

      listkeys

2. When the user clicks on a bank name, the Scheme Member Details screen is shown. When the user clicks the <delete> link, a confirmation dialog is displayed and, if confirmation is given, the corresponding entry is removed from the list. When the user clicks on the <add a new entry> link, the same Scheme Member Details screen is shown with empty fields.

3. On submission, the Scheme Member Details form is validated according to the following rules:

4. Bank Name needs to be present

5. Comment is optional

6. FI Code needs to be present. FI Code needs to be 11 digits.

7. CUG ID needs to be the membership scheme e.g. Eleanor.

8. Routing URI needs to be present and a valid URI according to RFC 2396.

9. Bank Distinguished Name and Issuer Distinguished Name needs to be present and have a valid distinguished name according to RFC 2253. This the DN and Issuer DN of the L1IPSC as copied from the cert_table within Trustbase schema.

10. Date is checked.

Figure 1-32    Member Details

Membership Status can be one of

• Active

• Pending

• Suspended

• Terminated

Service Status determines whether the member is still operating within the scheme. Members can be:

• Available

• Unavailable

To enable membership checking for this iTPS use the screen "General Payment Settings"

Inter-Participant Timeouts

The system administrator may configure the timeout values used when communicating with other Scheme participants.

Figure 1-33    Inter-Participant Timeouts Screen

These parameters determine how often you need to retry sending an interbank message. there are two values: (a) Timeout value: the length of time one waits before sending an interbank message again (b) Number of timeouts: the number of times one keeps retrying to send the interbank message. The Timeout value can be greater than 0. If set to 0, then Timeout is considered infinite. This can be left as the default and under normal circumstances does not need to be changed.

Payments Mail Settings

Configuring the settings for all outgoing messages sent by email used primarily for asynchronous acknowledgement emails and for Payment condition status update emails. Mail filters are provided to allow you to define the appearance of your messages. XLTS Static files are references in these filters to map Eleanor messages onto HTML.

Figure 1-34    Payments Mail Settings

Settlement Chain

Before making payments, a currency settlement chain needs to be established. This requires, in the first instance, deciding which financial institution you want to use to accept payments in a particular currency. You can then

1. Select a currency

2. Assign it to the financial institution (provided the financial institution can trade in that currency)

3. Finally add it to your currency settlement chain.

In some instances you may want payment initiation messages to be settled in many different currencies. Under such circumstances, iPlanet Trustbase Payment Services needs to be configured to accept a number of financial institutions that are used to settle payments in a variety of currencies.

1. Select <Services><Payments><Settlement Chain>

Figure 1-35    Settlement Chain Main Menu

Settlement chains are used by the SFI to inform the BFI of where to make payment if the currency supplied in the transaction cannot be accepted by the SFI directly. Under these circumstances a chain of F.Is is then created and added to the payment details to allow conversion of the payment into a currency that the SFI can accept.

2. There are    four steps for adding a currency to the payment settlement chain:
   1. First select <Financial Institution Administration> assign the account number of the institution that is to settle your currency

   Financial Institution Administration
   
   

   The SFI settlement role is always set to the Beneficiary Institution. Each financial Institution entered may be entered several times for different currencies and associated accounts into which to place the payment.

   1. Second, define the currencies that can be accepted through this SFI. Select <Currency Code Administration>. Each currency code must have at least the SFI associated with the currency, effectively making a settlement chain of one financial Institution, itself.

Figure 1-36    Currency Code Administration

1. Third select a currency that you want to assign a financial institution to. Select <Add Chain>

2. Fourth select a currency, from the screen on the previous page, by double clicking on it and match the currency to the financial institution by selecting <Add Link> as illustrated below:

Figure 1-37    Adding a currency code to the Settlement Chain

If a SFI can accept a currency directly, then it alone has to be associated with that currency. If the SFI cannot directly accept a payment in a specific currency then a settlement chain of additional financial institutions has to be created in order to convert the payment into a currency that can be accepted by the SFI.

3. Adjusting some of the data that appears in some of the tables can be done via the Oracle tables that are installed via the SQL script

   /opt/ittm/current/Config/sql/PaymentsNew.sql

The following table may need to be reconfigured:

• SC_CURRENCY_CODE_LIST - This contains all the possible currency codes that a user can select from when forming a chain or creating a transaction currency code.

Payment Recovery

iTPS provides the facility to re-present a payment request in the event that it failed on the first attempt. This can occur for example, if the buyers financial institution is not contactable at the time of the payment request.

By select the <List Recoverable messages> from the payments menu, any transactions that started but failed to complete will be listed, as shown below.

Figure 1-38    Recoverable Messages

To initiate a recovery, select the <Start recovery process> option from the payments menu. This may take some time as it re-presents any recoverable payment requests through the system. Upon completion a list of recovered transactions is displayed, as shown below.

Figure 1-39    Recovered messages

Payments Product Configuration

Figure 1-40    Payment Products screen

iTPS will accept that a particular payment product if the enabled checkbox is set to true else an acknowledgement message will be returned stating that this payment is not supported.

Condition Registry

Figure 1-41    Condition Registry Screen

Enter Website location. This sets the location of the Condition Management Website. For instance,

http://myhost.mycompany.com/itps-cond/Webcr

Message frequency sent to the SFI. Everytime a condition is discharged you can select the option that allows you to send a message to the SFI on every single condition. Alternatively, you can choose to send one message when all conditions have been discharged.

General Payment Settings

Figure 1-42    General Payment Settings

Membership Check are performed if enabled. In the even you are not a member an acknowledgement message is sent back saying that the Financial Institution is not part of the scheme.

Challenge Request Required. Before a payment request is sent from one financial institution to another there is an ability to send a challenge request to that financial institution to ascertain the validity and credentials of that financial institution.

Customer Authentication Checking. When a customer sends a message to a bank, before proceeding, the bank can authenticate the customer. If enabled and the financial institution is not on the list, authentication fails. If not enabled and not on the list the financial institution may still not get authenticated. See also Subscriber Details Screen.

Customer Authentication - Ignore failure

Back Office Response expected. If enabled the back office system returns synchronously to payment requests. If disabled Back Office/ Biab Back end does not return a synchronous acknowledgment. The synchronous message will be issued from iTPS.

Cancellation Authentication Check Expected. If enabled this requires that the same certificates (both buyer and seller) that signed the payment request must be used to cancel that payment request.

Asynchronous Acknowledge Management

Figure 1-43    Asynchronous Acknowledge Management Screens

This decides who receives and sends asynchronous messages. If the check box is enabled this indicates that the particular financial institution under consideration sends a message. There are three main columns

• BFI is the Buyers financial institution making a payment via the four corner model

• SFI is the Sellers financial institution making a payment via the four corner model

• SFI/BFI is when the seller and buyer are using the same financial institution making a payment via a 3 corner model.

Message types are used to indicate what stage the message has reached within each payment product.

Subscriber Details

Authorising Customers to the payment services is achieved by matching certificate name details. Upon successful match it assigns the customer with a customer ID. This is different from iPlanet Trustbase Transaction Manager's authorisation facility as iTPS has individual authorisation rather than generic corporate authorisation.

Figure 1-44    Subscriber Details

Select <Add>

Figure 1-45    Subscriber Details Add Screen

This screen maps the customer subject DN to a bank defined subscriber identifier. This subscriber identifier is used to identify the subscriber/customer to the back office systems. This check will be enabled only when the customer Authentication checking is enabled from the <general payment settings> menu option. Note, The customer subject DNs supplied must be uniquely defined within this authorisation list, although different subject DNs can be matched to the same bank defined customer identifier. This allows banks to use the same customer identifiers for groups of users or perhaps to allow a customer to have two smartcards if one is about to expire.

Remittance Details

Figure 1-46    Remittance Details

Remittance Data is where the bank can set the maximum size of the extra details you can put into a message to describe a payment.

Date Settings specify the dates between which a financial Institution will accept payment requests.

Transaction Monitoring

The Transaction Monitor is a Trustbase component that provides a data logging and tracing interface for the Trustbase administrator. Note iTPS 2.0 beta Patch 3 release ro later is required for Transaction Monitoring

1. Select <Services> followed by <Payments>

Figure 1-47    Payments Configuration Main Menu

2. Clicking on the <Transaction Monitor> link takes the administrator to the Transaction Monitor Search and Sort Screen. Transaction Monitor Search screen provides the Trustbase administrator facility to specify Search Attributes and date ranges

Figure 1-48    Transaction Monitor Search Screen

The screen provides

• A Sort by option that fetches results and sorts by using the input as specified from the dropdown by the administrator. The available options are,
  • Eleanor Transaction Monitor

  • Message Type

  • Sender

  • Payments Product Type

• Search Dates and Time option to narrow down the search to the specified duration.

• Search Attributes can be
  • Eleanor Transaction Reference.

  • Product Type

  • Message Type

  • Sender

• In addition there is a drop down box with options as <IS> or <ISNOT> beside the search attributes control if the specified search criteria is an inclusive or an exclusive one.

• The following Screen illustrates a typical seacrh

Figure 1-49    Example Search

4. After the Trustbase administrator provides the relevant details, select <Search> takes him to the Transaction Monitor History Screen. Selecting <Back> takes the user to the previous screen.

Figure 1-50    Transaction Monitor History Screen

• The records matching the search criteria specified by the administrator are shown for each of the records as following.
  • Payments Product Type : One of the six payments product types.
    • Direction       : Received or Sent based on whether                      incoming or outgoing message.            

    • Role       : SFI or BFI, depending on the role of                       the particular corner.

    • Model       : SFIM or BFIM if 4 corner, else SFI-3CM                       or BFI-3CM. Undefined, if not relevant.

    • Eleanor Reference : The eleanor transaction reference                             number.

    • Message Type          : The Payment message document type.

    • Sender        : The subject DN of the sender.                

• Pagination. There are 10 fetched records shown per page, and the user navigates between pages by clicking on the page numbers at the bottom of the page.

• Select <view> takes the user to the Single Transaction Messages screen which is described in brief below.

Figure 1-51    Transaction Monitor Single Message Screen

6. Select <view> for a particular Message type for the particular transaction and the folowing screen appears

Figure 1-52    Message type for a particular transaction.

For example, a transaction with PaymentRequest message type will have appropiate details from the Payment Request message in addition to the details such as Direction, Message Type, Role, Sender Details and the Message Dates.

7. Finally, selecting <XML> takes the administrator to the Single Message Original XML screen. The <Back> button takes the user to the previous screen. Certificate details have been removed for readability reasons.

Figure 1-53    Message XML details

Configuring Users (advanced)

---

The UserDbTool is used for registration of Seller access to the obligation website, Buyer access to the condition registry website and the ability for a specific buyer to be enabled for conditional payments.

There are commands to create, browse, delete and modify Users, Organisations, and Roles and the associations between them. To start the UserDbTool, run the runuserdbtool script from within the Scripts directory of an iTTM installation

Attributes

Each user needs to be assigned an organisation attribute. Organisations are identified by name, and there are commands to create, delete and view Organisations

neworganisation -organisation <organisationname>

create a new Organisation. The organisation must be supplied, and may contain spaces if it is delimited by quotes

deleteorganisation -organisation <organisationname>

delete an Organisation. If there are any Users which belong to the Organisation identified then this command will fail. Users belonging to an Organisation must themselves be deleted or have their Organisational associations changed before an Organisation can be deleted

lookuporganisation [ -organisation <organisationname> ]

search for an Organisation. If the optional organisation parameter is omitted, then all Organisations are displayed

Roles

Each User has zero or more Roles. A Role determines the rights and privileges that a User has to access information or perform actions in the system. Roles are identified by name, and there are commands to create, delete and view Roles

newrole -role <rolename>

create a new Role with the given name. The ConditionRegistry recognises the role BUYER [ for a Buyer ] and BFI [ for a BFI agent ]. The ObligationRegsitry recognises the role SELLER. There is no reason that a User could not have more than one role, for instance a Seller may also be a Buyer

deleterole -role <rolename>

delete a Role. If there are any Users which have this Role, then their association with the Role will be removed, and the Role will be deleted.

lookuprole [ -role <rolename> ]

search for a Role. If the optional role parameter is omitted, then all Roles are displayed.

Note, the condition registry website only recognises one role per Smartcard registration therefore a single Smartcard cannot act as a buyer to waive conditions and as a CDP to discharge conditions.

Users

Users are the core entities managed by the UserDbTool. It is the organisational and Role associations of a User that determine what information they can access and what actions they can perform. Users are identified by the Issuer Distinguished Name and Subject Distinguished Name from their digital certificates. There are commands to create, delete, view and update Users

newuser -issuer <issuerDN> -subject <subjectDN> -organisation <organisationName> [ -email <email> ] [ -role <roleName> ]*

create a new User. The users Issuer Distinguished Name and Subject Distinguished Name must be supplied, as must the name of an Organisation [ which must already have been created ]. An email address for conditional payment buyer notification should be assigned if the role will include "BUYER". This email address allows flexibility if the buyer organisation requires conditional notifications to be a different address to that in the buyer certificate for the payment. Roles can be assigned as either "BUYER" or "SELLER" or both.

deleteuser -issuer <issuerDN> -subject <subjectDN>

delete a User. The Issuer and Subject Distinguished Names identify the User to delete

lookupuser [ -issuer <issuerDN> -subject <subjectDN> ]

search for a User. If the optional Issuer and Subject Distinguished Names are not supplied, then all Users will be displayed

updateuser -issuer <issuerDN> -subject <subjectDN> [ -organisation <organisationName> ] [ -email <email> ] [ -deleteemail ]

[ -deleterole <roleName> ]* [ -role <roleName> ]*

Update a Users entry. The User is identified by the Issuer and Subject Distinguished Names, and the remaining optional parameters identify the Organisation and Role association changes to be carried out.

-organisation <organisationName> : change the Users Organisation association to the named Organisation, which must exist in the database

-email <email> : change the Users email address to that supplied

-deleteemail : remove the Users email address, without supplying a new one

-deleterole <roleName> : if the user has the named Role, remove that associations

-role <roleName> : add an association to the named Role for the User