Services

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

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.

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:

// 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.

<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()

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 :
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
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

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.

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

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.

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
<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

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

Exposed fields in the input :

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

Search Request

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 :

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 :

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

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

Search Response :

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.
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.