Services

Currently the following services are available

Memory / Session service be.securit.trustbuilder.util.TimedBlockingHashMap
MemCached / Session service be.securit.trustbuilder.service.MemcachedService
DateService be.securit.trustbuilder.service.DateService
EncryptionService be.securit.trustbuilder.service.EncryptionService
StoreEncryptionService be.securit.trustbuilder.service.StoreEncryptionService
Radius Endpoint Service be.securit.trustbuilder.service.RadiusService
Ldap Endpoint Service be.securit.trustbuilder.service.LdapService
Domtai Service be.securit.trustbuilder.service.DomTai
AMQProducerService: be.securit.trustbuilder.service.AMQProducerService
AMQConsumerService: be.securit.trustbuilder.service.AMQConsumerService

Getting direct access to a service from within the workflow can be done via the following

CODE

tb.getService("urlStore");

Session Management

Basic Session management in Trustbuilder can be enabled by adding the following property in trustbuilder.properties in the TB_HOME folder. This will delegate the storage of the session attributes into the container session.

CODE

sessionService=true

The sessions can be stored in third-party storage services too. For this, you should set the property to the id of the service handling the storing/retrieval. Currently 3 other backends are available: Database, Memcached and Redis (For configuration see the services section). But it's pretty trivial to write your own, provided that this service implements TrustBuilderCacheService.

In order to use the session service in the workflow 4 functions were created:

CODE

// Get a session variable by it's key
getSessionVariable(key)

// Set a session variable with a specific key/value pair
setSessionVariable(key,value)

// Set the timeout of a session in case of a servlet backed session
setSessionTimeoutInSec(sec)

// InvalidateSession Invalidate the session in case of a servlet backed session
invalidateSession()

For example an in-memory store.

CODE

<stb:Service stb:id="urlStore" stb:type="be.securit.trustbuilder.util.TimedBlockingHashMap" stb:singleton="true">
   <stb:property stb:name="ttl">30000</stb:property>
</stb:Service>
<stb:Service stb:id="objectStore" stb:type="be.securit.trustbuilder.util.TimedBlockingHashMap" stb:singleton="true">
  <stb:property stb:name="ttl">30000</stb:property>
</stb:Service>

In this example we configure 2 memory stores, this can be used to store a session, send information between threads and so on. The ttl property specifies how long a key exists in the store in milliseconds.

DateService

Classname : be.securit.trustbuilder.service.DateService

Format variables

Letter Date or Time Component Presentation Examples
G Era designator Text AD
y Year Year 1996; 96
M Month in year Month July; Jul; 07
w Week in year Number 27
W Week in month Number 2
D Day in year Number 189
d Day in month Number 10
F Day of week in month Number 2
E Day in week Text Tuesday; Tue
a Am/pm marker Text PM
H Hour in day (0-23) Number 0
k Hour in day (1-24) Number 24
K Hour in am/pm (0-11) Number 0
h Hour in am/pm (1-12) Number 12
m Minute in hour Number 30
s Second in minute Number 55
S Millisecond Number 978
z Time zone General time zone Pacific Standard Time; PST; GMT-08:00
Z Time zone RFC 822 time zone -0800

Functions

now(format) Format now as specified
epoch() Now as epoch number (seconds since 1970)
inRange(start,end) Returns true if now is between start and end as epoch dates
nowISO8601() Now in ISO8601 format
formatISO8601(date,timezone) Date in ISO8601 format where date is in epoch, timezone is a string
format(date,format) Date in specific format where date is in epoch
calcDateISO8601(expression) Date in expression in ISO8601 format where expression can be +/- x [s|m|h|d]
calcDate(expression,format) Date in expression in format where expression can be +/- x [s|m|h|d]
calcDateAsEpoch(expression) Date as epoch where expression can be +/- x [s|m|h|d]
calcDateAsEpoch(date,expression) Calculate date with expression using date as starting point

formatISO8610()

CODE

NormalizedCustomID:
         GMT Sign TwoDigitHours : Minutes
 Sign: one of
         + -
 TwoDigitHours:
         Digit Digit
 Minutes:
         Digit Digit
 Digit: one of
         0 1 2 3 4 5 6 7 8 9

Example :

CODE

var time = tb.getService("dateService");
var now = time.epoch();                        // EPOCH : 1395996050671
var iso = time.formatISO8601(now);             // ISO DATE : 2014-03-28T09:40:50.671+01:00
var gmt5 = time.formatISO8601(now,'GMT+05:00'); // NO SPACES !   GMT+5 DATE: 2014-03-28T13:40:50.671+05:00
var zulu = time.formatISO8601(now,'UTC');       // ZULU DATE: 2014-03-28T08:48:38.075Z

Domtai Service

Classname : be.securit.trustbuilder.service.DomTai

Properties

keySpec generated base64 encoded Key for the DomTai plugin in Lotus Notes
charSet charset for the encryption (normally ISO-8859-1)

Example

CODE

DOMTAI = tb.getService("domtai service");
var domtaiattr = DOMTAI.encrypt("some string");

Encryption Service

Properties

keySpec password tool encoded key key raw base64 encoded key iv initialization vector for ciphers in feedback mode (encoded with password tool) encoding Sets the character encoding , default is UTF-8

Functions

function	Description
encrypt(cipher,string,format)	Encrypt the string and return the encrypted data in the format (base64,hex,y64)
decrypt(cipher,encryptedString,format)	Decrypt the encryptedString by decoding in format (base64,hex,y64) and return the original string
sign(algorithm,data,decodingFormat,encodingFormat)	Sign the data decoded with decodingFormat and return the signature in the encodingFormat (base64,hex,y64)
verify(algorithm,data,signature,decodingFormat)	Verify the data by decoding in decodingFormat (base64,hex,y64)
generateHMac(cipher,string,inputformat, outputformat)	Encrypt the string with hmac and return the result in the outputformat (base64,hex, y64). Inputformat : null, base64, hex, y64
hash(hashAlg, message, encodingFormat)	Hash (according to the hashAlg=algorithm) the message and return it in the encoding format (base64, hex, y64)
saltedHash(password, salt)	Hashes (sha-1) the concatenated password+salt and retuns it base64 encoded
generateSalt(int len)	Generates a salt with the specified length

Available ciphers can be found for the sun at jdk6 jdk7

Example

CODE

var encryptionService = tb.getService("encryption"); // encryption is the name of the service
var pwd_hash_user = encryptionService.hash("SHA-512",workItem.input.credentials.password+salt,"base64");

// Encrypts the signaturebase with HMAC-SHA1 and returns a BASE64 encoded string
var signature = encryptionService.generateHMac( "HmacSHA1", signaturebase, null, "base64");

.setKey

When using the setKey functionality it's recommended to use the Encryption Service with the singleton flag set to false. If the singleton is set to true, the key is persistent until the next .setKey call or restart of the TrustBuilder Server.

Some cases another key must be used instead of the default one. This key can be set dynamic as an BASE64 encoded string.

CODE

encryptionService.setKey(tb.base64Encode("5VRtmBeg9jRJ5mRAsncaGwCGJ2YazTxReQIqbcHqZc",true));   // Encode as string true
var signature = encryptionService.generateHMac( "HmacSHA1", signaturebase, "base64");   // base64 is default

Store Encryption Service

Same as the encryption service but uses key/truststores to encrypt/decrypt/sign/verify

Properties

encoding Sets the character encoding , default is UTF-8

Functions

function	Description
encrypt(cipher,keyname,data,format)	Encrypt the data and return the encrypted data in the format (base64,hex,y64) using the public key from the certificate found in the truststore
decrypt(cipher,keyname,encryptedString,format)	Decrypt the encryptedString by decoding in format (base64,hex,y64) and return the original string using the private key from the keystore
sign(algorithm,keyname,data,decodingFormat,encodingFormat)	Sign the data decoded with decodingFormat and return the signature in the encodingFormat (base64,hex,y64) using the private key found in the keystore.
verify(algorithm,keyname,data,signature,decodingFormat)	Verify the data by decoding in decodingFormat (base64,hex,y64) using the public key of the certificate found in the truststore.
generateHMac(cipher,keyname,data,inputformat, outputformat)	Encrypt the data with hmac and return the result in the outputformat (base64,hex, y64). Inputformat : null, base64, hex, y64

Available ciphers can be found for the sun at jdk6 jdk7

Example

CODE

var encryptionService = tb.getService("encryption"); // encryption is the name of the service
var pwd_hash_user = encryptionService.hash("SHA-512",workItem.input.credentials.password+salt,"base64");

// Encrypts the signaturebase with HMAC-SHA1 and returns a BASE64 encoded string
var signature = encryptionService.generateHMac( "HmacSHA1", signaturebase, null, "base64");

.setKey

When using the setKey functionality it's recommended to use the Encryption Service with the singleton flag set to false. If the singleton is set to true, the key is persistent until the next .setKey call or restart of the TrustBuilder Server.

Some cases another key must be used instead of the default one. This key can be set dynamic as an BASE64 encoded string.

CODE

encryptionService.setKey(tb.base64Encode("5VRtmBeg9jRJ5mRAsncaGwCGJ2YazTxReQIqbcHqZc",true));   // Encode as string true
var signature = encryptionService.generateHMac( "HmacSHA1", signaturebase, "base64");   // base64 is default

LDAP Endpoint Service

classname : be.securit.trustbuilder.service.LdapService

The LDAP endpoint service is opening a listener port for the ldap endpoint.

Currently only a search and authenticate is supported. Search is however limited to what you define in the workflows. Using a normal ldap client to browse the server isn't possible as the endpoint is ment for authentication only.

Properties

port : Port used for the listener
workflow : Which workflow has to be run by the engine when this service is called

Note on ldap port

If you running your as non-root user you can't open ports under 1024. We recommend setting the ldap port higher and if you want to use port 389 fpr ldap make usage of software that forwards the connection from port 389 to your trustbuilder ldap endpoint.

Config

CODE

<stb:Service stb:id="ldapserv" stb:singleton="false" stb:synchronised="false" stb:type="be.securit.trustbuilder.service.LdapService">
   <stb:property stb:name="port">1389</stb:property>
   <stb:property stb:name="workflow">ldapworkflow</stb:property>
</stb:Service>

We set the listener to port 1389 and attach the "ldapworkflow" to it. Each requests to this endpoint starts the configured workflow.

Requests

Bind Request

CODE

{"user":"null","type":"bind","ip":"10.0.10.243","dn":"cn=administrator,dc=securit,dc=biz","password":"somepasswd"}

Exposed fields in the input :

CODE

user : 
type : bind 
ip : ip of requesting host 
dn : DN to bind to 
password : the given password to bind

Search Request

CODE

Engine.WorkItem - set ___INPUT___=LdapEndpointSearchRequest: {
       baseDN: 'dc=securit,dc=biz',
       scope: 'SUB',
       filter: '(&(objectclass=posixaccount)(uid=ewold))',
       attributes: '[userPassword, cn, gidNumber, uidNumber, loginShell, objectClass, gecos, uid, homeDirectory]',
} []

{"user":"null","type":"search","base":"dc=securit,dc=biz","scope":"SUB","filter":"(&(objectclass=posixaccount)(uid=username))","attributes":["userPassword","cn","gidNumber","uidNumber","loginShell","objectClass","gecos","uid","homeDirectory"]}

Exposed fields in input :

CODE

User : 
Type : Search 
Base : Search base 
Scope : Search scope 
Filter : Search filter 
Attributs : Required attributes in return

Response

To create a response to the ldap client TrustBuilder uses a function that called on the input object.

Bind Response :

CODE

// Authentication accepted
workItem.output = workItem.input.generateResponse(0);

// Authentication rejected
workItem.output = workItem.input.generateResponse(49);

Search Response :

CODE

var username = "testuser";
var response = {
                       "host" : "10.0.10.243",
                       "gidNumber" : info.gidNumber,
                       "uidNumber" : info.uidNumber,
                       "homeDirectory" : info.homeDirectory,
                       "loginShell" : info.loginShell,
                       "userPassword" : "password"
               };
workItem.output = workItem.input.generateResponse(0);
// Add search Result and attributes
workItem.output.addResult("cn="+username,response);

The addResult function can be called multiple times.

Returning error codes

The 49 is an invalid credentials error code. If you wish to use other codes you can have a look at : http://docs.oracle.com/javase/jndi/tutorial/ldap/models/exceptions.html

MemCached Service

Classname: be.securit.trustbuilder.service.MemcachedService

To use this service an extra jar has to be included in your trustbuilder-web.war file. Download the latest xmemcached jar file and place it in the /lib folder of your trustbuilder package.

Property

address Address of the remote memcached service
poolsize Size of the connectionpool to use

Functions

get(key) Get item by key
put(key,value) Put key/value pair
add(key,value) Set key/value pair
replace(key,value) Replace key/value pair
set(key,expiry,value) Put key/value pair with expiry
add(key,expiry,value) Set key/value pair with expiry
replace(key,expiry,value) Replace key/value pair with expiry
remove(key) Remove item from store

Memory / Session service

There are 3 different session services available. They allow to integrate a session service in the workflow. However, it's not limited to only sessions, they can be used as a way to pass information between requests.

Possible implementations

database: be.securit.trustbuilder.util.DatabaseCacheService

Properties: * jndi * putStatement (optional) * getStatement (optional) * remStatement (optional)

memcached: be.securit.trustbuilder.service.MemcachedService

Properties: * address (supports multiple addresses) * poolsize * memory be.securit.trustbuilder.util.SimpleCacheService

expiring memory: be.securit.trustbuilder.util.TimedBlockingHashMap

Properties: * ttl Time to keep the entries in memory before removing them

redis: be.securit.trustbuilder.service.RedisService

Properties: * host (supports multiple addresses) * ttl Time to keep the entries in memory before removing them

These implementations can be used as backend for sessionmanagement, see the section over sessionmanagement.

Functions

put(key,object) Put a key in the store with a value (expiring after ttl defined in the config)
get(key) Get the value from the store by its key
get(key,timeoutSeconds) Get the value from the store by its key with a timeout in seconds
remove(key) Remove a value from the store

Radius Endpoint Service

Classname: be.securit.trustbuilder.service.RadiusService

The radius endpoint service is opening a listener port for the radius endpoint.

Properties :

sharedSecret : The shared secret between the client and the endpoint. This is encoded by the Trustbuilder password tool.
port : Port used for the listener
workflow : Which workflow has to be run by the engine when this service is called

AMQProducerService

Classname: be.securit.trustbuilder.service.AMQProducerService

This service (from here on referred to as producer) is used for sending a message with a certain topic to an exchange, which will deliver it to the consumer(s) (configured by AMQProducerServices) listening to that topic. The delivering and handling of the message is done asynchronously.

Properties

Username: Username for accessing the queuingserver.
Password: Password for accessing the queuingserver.
Host: Host of the queuingserver this producer will send messages to.
Port: Port of the queuingserver this producer will send messages to.
Exchange: The exchange this producer will send messages to.
Topics: The topics this producer is allowed to send messages with.

Functions

send(message, topic): Send a message; message can be any JavaScript object, topic must be a String. Returns an object containing a status key and a message key. Below you can find the different possible status values and corresponding information:
- 0: OK.
- 1: This producer is not allowed to send messages with this topic.
- 2: Internal error.

AMQConsumerService

Classname: be.securit.trustbuilder.service.AMQConsumerService

This service (from here on referred to as consumer) is used for receiving and handling messages.

Properties

Username: Username for accessing the queuingserver.
Password: Password for accessing the queuingserver.
Host: Host of the queuingserver this consumer will receive messages from.
Port: Port of the queuingserver this consumer will receive messages from.
Queue: The queue this consumer is accepting messages from.
Exchange: The exchange the aforementioned queue is getting messages from.
Topics: The topics the queue associated with this consumer will accept from the exchange. (special case: If the same queue is already bound to another consumer or other consumers, the topics this queue will listen to will be the union of the topics for each consumer)
Workflow: The workflow that will handle the messages.