TAFJ M e s s a g e I n t e g r i ty

R22
 TAFJ M e s s a g e I n t e g ri ty

Amendment History:

Revisio
Date Amended Name Description
n
1 22nd Mar 2019 Riswana F Initial version
th
2 17 Oct 2019 Riswana F Update XML signing

3 25th March 2020 Riswana F R20 AMR review

Add User Authentication and update configuration

4 27th April 2020 Riswana F
of keystore.properties with MI_HOME

5 30th April 2020 Riswana F Update supported algorithms of XML signature.

6 6th July 2020 Riswana F Update Message Integrity Crypto API

UshaNandhini.
7 12th April 2021 R21 AMR
S

Update Java properties and encryption of

8 22nd Feb 2021 Riswana F
password in properties.

9 24th March Prasshanth R22 AMR Review

Page 2
TAFJ M e s s a g e I n t e g ri ty

Copyri g h t
Copyright © Temenos Headquarters SA 2009-2022. All rights reserved.
This document contains proprietary information that is protected by copyright. No part of this document may
be reproduced, transmitted, or made available directly or indirectly to a third party without the express
written agreement of TEMENOS UK Limited. Receipt of this material directly TEMENOS UK Limited
constitutes its express permission to copy. Permission to use or copy this document expressly excludes
modifying it for any purpose, or using it to create a derivative therefrom.

Errat a and Com m e n t s

If you have any comments regarding this manual or wish to report any errors in the
documentation, please document them and send them to the address below:
Technology Department

Temenos Headquarters SA
2 Rue de l’Ecole-de-Chimie,
CH - 1205 Geneva,
Switzerland

Tel SB: +41 (0) 22 708 1150

Fax: +41 (0) 22 708 1160

Please include your name, company, address, and telephone and fax numbers, and email
address if applicable. [email protected]

Page 3
TAFJ M e s s a g e I n t e g ri ty

Table of Contents
Copyright................................................................................................................................................ 3
Errata and Comments............................................................................................................................ 3
Overview................................................................................................................................................ 5
Features.............................................................................................................................. 5
Create Keystore...................................................................................................................................... 5
Configuration....................................................................................................................... 5
Configure Keystore Location............................................................................................5
Add Authenticated user....................................................................................................6
Start the Web APP using embedded Jetty.......................................................................7
Create Keystore................................................................................................................... 8
JBC & JAVA API..................................................................................................................................... 9
JBC API............................................................................................................................... 9
Configuration................................................................................................................... 9
Sign................................................................................................................................ 11
Verify.............................................................................................................................. 12
JAVA APIs......................................................................................................................... 13
SYNTAX........................................................................................................................ 13
Configuration.................................................................................................................. 13
Field Metadata................................................................................................................... 16
Algorithms......................................................................................................................... 17
Supported Digest Algorithms.........................................................................................17
Supported Signature Algorithms....................................................................................17
Error Details...................................................................................................................... 18
Crypto Interface for L3 Implementation................................................................................................ 18
Enable and configure CryptoAPI.......................................................................................19
AppServer............................................................................................................................................ 20
References:.......................................................................................................................................... 20

Page 4
TAFJ M e s s a g e I n t e g ri ty

Overvi e w
The primary Objective of this document is to provide guidance to create Keystore and use
JBC and JAVA API provided for Message Integrity.

Message Integrity is a solution for handling messages securely. We sign the outgoing
message and verify the message using the signature. In addition, we provide solutions to
manage keys securely.
Either Symmetric or Asymmetric Key is required to Sign/Verify.
Asymmetric Key – Use PrivateKey to sign the message and use PublicKey to verify the
message.
Symmetric key – Same SecretKey is used sign and verify the message.

Feat u r e s
1. Store the Security keys in Java keystore.

2. Provide API to sign the outward message and verify the inward message using the
keys stored in Keystore, which it can used by both JBC and Java.
 Sign: It is the API to sign the message and it will provide the signature or hash
value for the message using the configured keys. For XML type messages, the
signature element is append to the actual message.
 Verify: It is the API to verify the message and it will return 0 in case of successful
verification.
 Digest

Creat e Keys t o r e
Use TemenosSecurityWeb.war to create Keystore and register entries and keys to it. It is
available part of TAFJ at $TAFJ_HOME/MessageIntegrity/lib. It can be deployed in any
supported Application Server.

Confi g u r a t i o n

Confi g u r e Keys t o r e Loca ti o n

Edit the keystore.properties file, which is available in resource/conf folder in
TemenosSecurityWeb.war.

Page 5
TAFJ M e s s a g e I n t e g ri ty

If the Keystore is available as a physical file in the machine, provide the path in the property
temn.keystore.location. Multiple path can be provided as comma seperated.

If the Keystore is available in database provide the properties temn.keystore.database.url,

temn.keystore.database.driver, temn.keystore.database.user and
temn.keystore.database.password.

Add Auth e n t i c a t e d us e r
User authentication is required to access the Keystore registry. Follow the below steps to
add the user in respective Appserver.

Embedded Jetty provided with Message Integrity

Add user in $TAFJ_HOME/MessageIntegrity/conf/MIRealm.properties . Default crednetial is
miuser/password

username: password[,rolename ...] -> rolename should be “MIAdmin”, password is the

user’s (possibly obfuscated or MD5 encrypted) password;

Eg: miuser: MyPassword,MIAdmin

Jboss
Execute add-user.bat available at $JBOSS_HOME\bin. Create an application user in
MIAdmin group.

Page 6
TAFJ M e s s a g e I n t e g ri ty

Weblogic
From Weblogic Console, create user as below.

Security Realms -> Click myrealm -> Create new group as MIAdmin

Security Realms -> Click myrealm -> Create new user. Add user to group MIAdmin group.

Websphere Liberty
Create basicRegistry as follow in server.xml.

<basicRegistry id="basic" realm="MIRealm">

<user name="test" password="test@123" />
<group name="MIAdmin">
<member name="test" />
</group>
</basicRegistry>

Start th e Web APP usi n g e m b e d d e d Jetty

Navigate to the bin folder of extracted MessageIntegrity directory. Set JAVA_HOME and
PATH.

set JAVA_HOME=<JAVA_DIR>

set PATH=<JAVA_DIR>\bin;%PATH%

Execute the LaunchKeyStoreWebApp.bat to start jetty-runner deploying

TemenosSecurityWeb.war

Page 7
TAFJ M e s s a g e I n t e g ri ty

Now access the web application with the URL http://localhost:8080/TemenosSecurity

Page 8
TAFJ M e s s a g e I n t e g ri ty

Crea t e Keys t o r e
Create Keystore page will be as below.

Keystore Name : Name of the keystore

Keystore Password: Password to access keystore
Select one of the below key Type :
 Asymmetric – Private Key : It can be used only for sign operation. It should be
an instance of PrivateKey.
 Asymmetric – Public Key : It can be used only for verify operation. It should be
an instance of PublicKey.
 Symmetric Key : Key can be used for both sign and verify operations.
Should be an instance of SecretKey
 Split the key into two halves. The first part of the key is Left Key and the other
part is Right Key. We recommend it to enter it by two different users. When
the Left part key is stored first and when the second user attempt to store right
key, choose the “Stored Left Key” as YES. Similarly, choose yes for “Stored
right Key” if the left key is stored after right. Store keystore in Database, if the
left and right keys are registered from different machines.
 Choose both the options as NO if it is the first (left/right) key to be stored.
 Grace days is number of days the keys can be configured to be valid. Based
on configurations the key is considered as active in the grace period.
Note: Use Private/Public in PKCS#8 standard.

Page 9
TAFJ M e s s a g e I n t e g ri ty

JBC & JAVA API

JBC API’s are interface to access SIGN and VERIFY features from an Infobasic program
using CALLJ.

Java API’s are interface to access SIGN and VERIFY features from a Java program.

JBC API

Confi g u r a t i o n
Copy all the dependency jars from TAFJHome\3rdParty\Integrity to TAFJHome\lib

Either option provided to use the Keystore as a physical file or it could be from a database.

We may set the properties as either of the below:

 Configure this in keystore.properties file available in conf folder of

TemenosSecurity.jar.

 Instead, we can also configure keystore.properties at MI_HOME. Set/export

MI_HOME and create folder structure as below. If MI_HOME is set, it takes
precedence over the properties file configured inside jar.

 Alternatively, set them as Java Properties. i.e, -Dtemn.keystore.location when you

start the application/appserver.

Folder structure with MI_HOME:

<MI_HOME>

conf

keystore.properties

Page 10
TAFJ M e s s a g e I n t e g ri ty

Folder structure within jar:

If the Keystore is available as a physical file in the machine, provide the path in the property
temn.keystore.location. Multiple path can be provided as comma seperated.

If the Keystore is available in database provide the properties temn.keystore.database.url,

temn.keystore.database.driver, temn.keystore.database.user and
temn.keystore.database.password.

Note: Only when the location is not provided, Keystore is read from the database

Encrypt Password:
Using tCrypt tool available at TAFJ_HOME\bin, encrypt the keystore.properties and update
the path to .key in the below property.

temn.security.key.path= path\to\directory\contains\.key

tCrypt -key path\to\directory\contains\.key -pk temn.keystore.database.password -conf

path\to\keystore.properties

tCrypt -key path\to\directory\contains\.key -pk ENTRY.ENCRYPTED.PASSWORD -conf

path\to\keyConfig.json

Page 11
TAFJ M e s s a g e I n t e g ri ty

Si g n
Access Sign API from JBC CALLJ. Use “com.temenos.security.jbc.Integrity” as
package.class to access the method sign as in below sample request.

Sample Sign Request

Set “ENTRY.TYPE” as unidirectional for private and public key (Asymmetric). Set it as
bidrectional for secret key(Symmetric).

The message can be classified as XML type as below. Specify the message type at <1,12>
and the digest algorithm at <1,13> . SHA1, SHA256, SHA512 are supported digest
algorithms. In case if it is not set, SHA1 algorithm is the default algorithm. For XML message,
the <signature> element is append to the message itself and provided as output for sign API.

signRequest<1,12> = "XML" ;*Message Type

signRequest<1,13> = "SHA256" ;* Digest Algorithm

Page 12
TAFJ M e s s a g e I n t e g ri ty

Verify
Access Verify API from JBC using CALLJ. Use “com.temenos.security.jbc.Integrity” as
package.class to access the method verify as in below sample request.

Sample Verify Request:

Set “ENTRY.TYPE” as unidirectional for private and public key (Asymmetric). Set it as
bidrectional for secret key(Symmetric).

As below, set message type as XML to verify the message signed as XML and note here the
message with <signature> element should be available at <1,9> .

signRequest<1,payload>=returnValue

signRequest<1,12> = "XML" ;*Message Type

Note: EB.SEC.INTEGRITY.API is a wrapper available for Temenos Transact to use the

Message Integrity API.

Page 13
TAFJ M e s s a g e I n t e g ri ty

JAVA APIs
Add TemenosSecurity.jar and the dependency libraries available at
$TAFJ_HOME\3rdParty\integrity in classpath.

SYNTAX
SIGN:

sign(<message>,<compliance>);

VERIFY:

verify(<message>,<compliance>,<signature>);

VERIFY XML SIGNATURE:

verify(<message>,<compliance>, null, MISecurityConstants.MessageType.XML)

Configu r a tio n
Update the KeyConfig.json in TemenosSecurity.jar/conf to add the key configuration for
sign\verify operation. Alternatively, you may set the path with below Java property

temn.security.key.config.path=/path/to/keyConfig.json

Below is a sample configuration for a symmetric and asymmetric key respectively.

"COMPLAINCE" can be set "SwiftLAU" to get the signature as a HEX 64 bytes value.

“USE.GRACE”, if set to TRUE then the key is valid for the GRACE DAYS registered in
Keystore.

"WARN.EXPIRY" is to describe when onwards expiry warning be notified in SECURITY.log.

If it is 30, then the warning message is started to log 30 days before the key expire date until
the key expire.

“DIGEST.ALGORITHM” is to set the algorithm to generate digest for the XML type
messages. SHA1, SHA256, SHA512 are supported algorithms. If it is not set, SHA1 is the
default algorithm.

Set “ENTRY.TYPE” as unidirectional for private and public key (Asymmetric). Set it as
bidrectional for secret key(Symmetric).

{
"ConfId1":
{
"ALGORITHM":"HmacSHA256",
"DIGEST.ALGORITHM":"SHA256",
"COMPLAINCE":"SwiftLAU",

Page 14
TAFJ M e s s a g e I n t e g ri ty

"Entries":[
{"KEYSTORE.NAME":"TESTKEYSTORE",
"KEYSTORE.ENCRYPTED.PASSWORD":"temenos",
"ENTRY.NAME":"testalias1",
"ENTRY.ENCRYPTED.PASSWORD":"temenos",
"ENTRY.TYPE":"bidirectional",
"USED.FOR":[
{"OPERATION":"sign","USE.GRACE":"FALSE"},
{"OPERATION":"verify","USE.GRACE":"FALSE"}
]
},
{"KEYSTORE.NAME":"TESTKEYSTORE",
"KEYSTORE.ENCRYPTED.PASSWORD":"temenos",
"ENTRY.NAME":"testalias2",
"ENTRY.ENCRYPTED.PASSWORD":"temenos",
"ENTRY.TYPE":"bidirectional",
"USED.FOR":[
{"OPERATION":"sign","USE.GRACE":"FALSE"},
{"OPERATION":"verify","USE.GRACE":"FALSE"}
]
}
],
"WARN.EXPIRY":30
},
"ConfId2":
{
"ALGORITHM":"SHA256withRSA",
"COMPLAINCE":"",
"Entries":[
{"KEYSTORE.NAME":"TESTKEYSTOREUNI",
"KEYSTORE.ENCRYPTED.PASSWORD":"temenos",
"ENTRY.NAME":"testalias3",
"ENTRY.ENCRYPTED.PASSWORD":"temenos",
"ENTRY.TYPE":"unidirectional",
"USED.FOR":[
{"OPERATION":"sign","USE.GRACE":"FALSE"}
]
},
{"KEYSTORE.NAME":"TESTKEYSTOREUNI",
"KEYSTORE.ENCRYPTED.PASSWORD":"temenos",
"ENTRY.NAME":"testalias4",
"ENTRY.ENCRYPTED.PASSWORD":"temenos",
"ENTRY.TYPE":"unidirectional",
"USED.FOR":[
{"OPERATION":"verify","USE.GRACE":"FALSE"}
]
}
],
"WARN.EXPIRY":30
}

Page 15
TAFJ M e s s a g e I n t e g ri ty

Below is a sample program to use the JAVA API from Temenos Security library.

import com.temenos.security.java.Integrity;

public class TestJavaApi {

public static void main(String[] args) {

System.out.println("test message");
Integrity obj = new Integrity();
try{
String signature = obj.sign("message","SwiftLAU");
System.out.println(signature);
String retVal = obj.verify("message","SwiftLAU",signature);
System.out.println(retVal);
} catch (Exception e){
System.out.println("Error from API " + e.getMessage());
}

//For XMLType messages, pass type as third parameter

try{
String signature = obj.sign("message","SwiftLAU",
MISecurityConstants.MessageType.XML);
System.out.println(signature);
String retVal = obj.verify("message","SwiftLAU",null,
MISecurityConstants.MessageType.XML);
System.out.println(retVal);
} catch (Exception e){
System.out.println("Error from API " + e.getMessage());
}

Page 16
TAFJ M e s s a g e I n t e g ri ty

Field Me t a d a t a
Muti Value JSON FIELD (JAVA API) Description
Field (JBC
API)

1.1 ALGORITHM Algorithm used to generate signature.

Check Algorithms sections for supported
values. Optional for XML message
verification.

1.2 KEYSTORE.NAME Keystore Name

1.3 KEYSTORE.ENCRYPTED.PAS Keystore Password

SWORD

1.4 ENTRY.NAME Entry Name or Key Alais

1.5 ENTRY.ENCRYPTED.PASSW Entry Password

ORD

1.6 ENTRY.TYPE Entry Type – Unidirectional or

Bidirectional

Private/Public key is Unidirectional.

Secret Key is Bidirectional

1.7 USE.GRACE Set TRUE to use the key in Grace period.

Grace period is set while registering the
key in keystore and it is the period in
which the key is active after expiry date.

1.8 WARN.EXPIRY Warning messages about key expiration

is written to log. If set to 10, message
start to log from 10 days before key
expiry.

1.9 NA Message to be signed. Need not be set

for XML message verification.

1.10 NA Signature. Only required for Verify

operation.

1.11 COMPLAINCE Complaince may be set to “SWIFT.LAU”

to get the signature as HEX value.

Page 17
TAFJ M e s s a g e I n t e g ri ty

1.12 NA MessageType. Vaue can be TEXT or

XML. TEXT is the default.

1.13 DIGEST.ALGORITHM Digest Algorithm. Value can be SHA1 or

SHA256 or SHA521. Default is SHA1.

Page 18
TAFJ M e s s a g e I n t e g ri ty

Algor it h m s
Signature Algorithm is required to create and verify signature. Additionally, Digest Algorithm
is required for XML signature.

Su p p o r t e d Dig e s t Algori t h m s
 SHA1 (Default)

 SHA256

 SHA512

Su p p o r t e d Sig n a t u r e Algori t h m s
Message Type For Asymmetric Key For Symmetric Key

TEXT  SHA1withRSA  HmacSHA1

 SHA256withRSA  HmacSHA256

XML  RSA-SHA1  HMAC-SHA1

 RSA-SHA224  HMAC-SHA224

 RSA-SHA256  HMAC-SHA256

 RSA-SHA384  HMAC-SHA384

 RSA-SHA512  HMAC-SHA512

NOTE: Support for HMAC-SHA224 and RSA-SHA224 is available from JAVA 1.8.0_231 and
above.

Page 19
TAFJ M e s s a g e I n t e g ri ty

Error Det a i l s
Below are the error codes specific to Message Integrity. SYSTEM(0) holds the errors for
CALLJ.

Error Number Description

-1 Keystore doesnot exist or incorrect password.

-2 Invalid keystore password.

-3 Entry not found.

-4 Invalid Entry Password.

-5 All Entries Expired

-6 Invalid Request.

-7 Verification Failed

-8 Algorithm Not supported.

-9 Configuration not found.

-10 SQL\Database Error.

Crypt o Int erf a c e for L3 Impl e m e n t a t i o n

We provide the interface ICryptoSPI that allows implementing sign and verifying API. Method
signature as follows,

/**
* Implement sign SPI to sign the message
* @param message Message to generate signature ;
* @param messageConfId Configuration Id in keyConfig.json; Null for
JBC API
* @param msgType XML or Text
* @param configuration: In case of Java API, configuration from
Keyconfig.json. In case of JBC, configuration from EB.SEC.KEY.CONFIGURATION
* @throws Exception throws any exception
*/
public String sign(String message, String messageConfId, MessageType
msgType, String configuration) throws Exception;

/**
* Implement verify SPI to verify the signature
* @param message Message to generate signature
* @param messageConfId Configuration Id in keyConfig.json; Null for
JBC API

Page 20
TAFJ M e s s a g e I n t e g ri ty

* @param msgType XML or Text

* @param configuration: In case of Java API, configuration from
Keyconfig.json. In case of JBC, configuration from EB.SEC.KEY.CONFIGURATION
* @param signValue Signature of the message to verify
* @return TRUE for success; FALSE for Failure
* @throws Exception throws any exception
*/
public boolean verify(String message, String messageConfId, MessageType
msgType, String configuration, String signValue) throws Exception;

Enab l e and con f i g u r e Crypt oA P I

1. Enable X.CRYPTO.PROVIDER and set custom provider name

For Temenos Transact, enable the field X.CRYPTO.PROVIDER at

EB.SEC.INTEGRITY.MSG.CONF, by default it is false. In addition, set the field ‘Custom
Provider Name’ with the custom property. It identifies the custom implemented class name
for the respective messageConfId using this custom property.

For Java implementation, enable the field X.CRYPTO.PROVIDER at KeyConfig.json, by default

it is false. In addition, set the field CUSTOM.PROVIDER.NAME with the custom property. It
identifies the custom implemented class name for the respective messageConfId using this
custom property.

For E.g: ‘CryptoMessageId’ is the message configuration Id that is the parameter value to
sign/verify API. If required, add other configurations like KEYSTORE.NAME, etc… to it.

"CryptoMessageId": {
"X.CRYPTO.PROVIDER": "true",
"CUSTOM.PROVIDER.NAME": "crypto_service_proxy"
}

Whatever configured in KeyConfig.json and EB.SEC.KEY.CONFIGURATION will be

available in the configuration variable for the implementation of Java and JBC
implementation respectively.

2. Set
temn.security.external.<custom.provider.name>=package_name.class_name
in keystore.properties.
For above configuration, it should be set as,
temn.security.external.crypto_service_proxy=com.temenos.api.MessageIntegrit
yImpl

Page 21
TAFJ M e s s a g e I n t e g ri ty

AppS e rv e r
While the product is used through the appserver make sure the TemenosSecurity.jar, json-
simple.jar and bcprov-jdk15on.jar is available in classpath

Jboss
Add the libraries in jboss/modules/com/temenos/tafj/main/module.xml

Ref er e n c e s :
https://www.eclipse.org/jetty/documentation/current/configuring-security.html
https://www.ibm.com/support/knowledgecenter/SSEQTP_liberty/com.ibm.websphere.wlp.doc
/ae/twlp_sec_basic_registry.html

https://www.ibm.com/support/knowledgecenter/en/SSSHTQ_8.1.0/com.ibm.netcool_OMNIbu
s.doc_8.1.0/webtop/wip/task/web_adm_createuserwebsphere.html

https://docs.oracle.com/cd/E13222_01/wls/docs81/secwlres/usrs_grps.html

Page 22